GitHub - Yuki-zik/taskvision: TaskVision is a powerful visual enhancement extension for VS Code to track comments and TODOs

中文文档 | English

Track code comments as real tasks, style them richly, and export AI-ready context without leaving VS Code.

TaskVision turns TODO-style comments into a task board inside the Explorer. It still does the classic work well — highlight tags, show them in a tree, jump back to code — but now it also supports inline task states, priority and note metadata, AI context export, status reports, and state-aware filtering.

code --install-extension A-Znk.taskvision

Important

TaskVision 2.0 uses a four-channel highlight model. Styling scopes are now split into colorType, glowType, glassType, and fontType.

Features

Task Management

Highlight TODO-style tags and markdown checkboxes in source comments
Show tasks in tree, flat list, or tags-only view
Parse inline states: [todo], [blocked], [review] ...
Distinguish task, context, and review annotations in the tree
Store stable IDs, priority, notes, and context refs in .taskvision/tasks-meta.json

AI Integration

Export ai-context.md, ai-context.json, ai-status-report.md
Persist context cards in context-index.json
Persist planning/review sessions in change-sessions/*.json
Let external AI tools write source annotations and reconcile them through official commands
Exclude generated context from scans to prevent self-references
Compatible with Claude Code, Codex, and any Markdown/JSON consumer

Task States

TaskVision supports these built-in task states:

State	Meaning	State	Meaning
`todo`	Planned work that should be addressed	`review`	Implemented, waiting for confirmation
`doing`	Work currently in progress	`done`	Completed
`blocked`	Waiting on an external dependency	`wontdo`	Explicitly declined
`paused`	Intentionally deferred	`idea`	Observation or future direction

// TODO [todo] refactor cache invalidation
// TODO [blocked] waiting for the API schema
// TODO [review] retry flow rewritten, pending QA
// NOTE [idea] split parser and renderer

Compatibility rules:

Shorthand	Resolves to
`[ ]`	`todo`
`[x]` / `[ x]`	`done`
`NOTE` / `IDEA`	`idea`
plain `TODO` (no state)	`todo`

AI Collaboration Syntax

TaskVision supports optional tv: directives after the human-readable text. Most everyday comments do not need an ID; TaskVision adds stable IDs only when a task or context needs durable tracking.

// TODO [todo] fix refresh concurrency
// TODO [doing] fix refresh concurrency [tv:id=task.auth-refresh.c3f12a]
// NOTE [idea] refresh must stay single-flight [tv:ctx=invariant] [tv:id=ctx.auth-refresh.8a91de]
// NOTE [review] verify retry flow [tv:review=verify] [tv:task=task.auth-refresh.c3f12a] [tv:session=sess.20260308.codex.001]

Three source annotation classes are recognized:

Class	Typical form	Purpose
`task`	`TODO/FIXME/[ ]/[x] + optional [tv:id]`	Work item tracked in task state flow
`context`	`NOTE [idea] + [tv:ctx=...] + optional [tv:id]`	Human or AI-authored constraint / invariant / decision
`review`	`NOTE [review] + [tv:review=...] + [tv:session=...]`	Session-scoped AI review or follow-up note

Supported tv: directives:

Directive	Meaning
`[tv:id=...]`	Stable ID for a task or context anchor, usually managed by TaskVision
`[tv:ctx=...]`	Context kind: `must-read`, `constraint`, `invariant`, `decision`, ...
`[tv:task=...]`	Task stable ID(s) linked to a context or review note
`[tv:review=...]`	Review kind: `changed`, `why`, `risk`, `verify`, `blocked`, `followup`
`[tv:session=...]`	Active planning / review / implementation session ID

Stable IDs are required only when an annotation needs durable links: sidecar metadata, taskRefs / contextRefs, AI context export, or long-lived context anchors. Temporary TODOs and ideas can stay as plain human-readable comments.

Tree Workflow

TaskVision supports a full task + AI collaboration workflow directly from the tree:

Action	What it does
Set Task Status	Rewrites the inline `[status]` token in source
Set Task Priority	Stores priority in `.taskvision/tasks-meta.json`
Edit Task Note	Stores extra context for summaries and handoff
Add Context Annotation	Inserts a `NOTE [idea] ... [tv:ctx=...]` context anchor above the current line
Start Agent Session	Creates or switches the active workspace session used by AI review notes
Write Agent Annotations	Inserts `NOTE [review] ... [tv:review=...] [tv:session=...]` above the current line
Sync Data Model	Reconciles source annotations, sidecar JSON stores, and exported AI context
Add Missing Inline Statuses	Backfills status tokens for visible tasks without one
Filter By Status	Filters the tree by one or more states
Clear Status Filter	Resets the state filter

Note

Bulk backfill works on the current visible scope.
When triggered from a context menu (folder / file / tag / task / context / review), only that subtree is affected.
Generated AI files are ignored by scans, so opening them will not pollute the tree.
Task nodes show task metadata, context nodes show ctx:<kind>, and review nodes show review:<kind>.

AI Context Export

TaskVision exports a stable handoff bundle for any external coding assistant:

.taskvision/
├── ai-context.md                 # Human-readable unified context bundle
├── ai-context.json               # Machine-readable unified context bundle
├── ai-status-report.md           # Task status change summary
├── tasks-meta.json               # Task metadata and stable ID index
├── context-index.json            # Context cards linked to source anchors
└── change-sessions/
    └── sess.<date>.<actor>.<n>.json

ai-context.json v2 includes:

tasks: exported task nodes with stable IDs, priority, notes, and linked context refs
contexts: related context cards from context-index.json
openSessions: open planning/review sessions from change-sessions/
readOrder: the recommended AI reading order

Minimal shape:

{
  "version": 2,
  "generatedAt": "2026-03-08T12:34:56.000Z",
  "workspaceRoot": "/workspace",
  "scope": "visible-tree",
  "tasks": [],
  "contexts": [],
  "openSessions": [],
  "readOrder": []
}

Recommended AI Contract

Rule	Description
Use official sync	Change source annotations, then run `Sync Data Model` or `Export AI Context`
Prefer `review`	Use `review` over `done` when verification is incomplete
Hands off sidecars	Do not edit `.taskvision/*.json` directly unless TaskVision generated the change
Report changes	Report which stable task or session IDs changed and why

Minimal Workflows

Add or select a task, then run Add Context Annotation to attach a constraint or invariant.
Run Start Agent Session, then use Write Agent Annotations to capture review notes with a live session ID.
Run Export AI Context to rebuild sidecars and produce a unified bundle for the next agent.

Highlight Model

TaskVision uses four independent styling channels:

┌─────────────────────────────────────────────────┐
│  colorType   →  where text color applies        │
│  glowType    →  where neon glow applies         │
│  glassType   →  where background glass applies  │
│  fontType    →  where weight / italic / deco     │
└─────────────────────────────────────────────────┘

Supported scopes: tag · text · tag-and-comment · text-and-comment · tag-and-subTag · line · whole-line · none

Use tag for the glass channel when you want a compact translucent badge around the task marker. Use line only when you intentionally want a band around the line text, and whole-line only when you want the background to stretch across the full editor width.

Scheme rules:

Scheme	Effect
`"neon"`	Enables text-layer neon/acrylic glow
`"glass"`	Enables the glass colour family; add `glassOpacity` or `glassBorderOpacity` to render glass fill or border
`"neon+glass"`	Enables text-layer neon/acrylic glow plus optional glass fill or border

scheme controls presets only — it no longer decides scope.

Apply a scheme to every tag at once: run TaskVision: Set Highlight Scheme for All Tags from the Command Palette or the tree view's ⋯ overflow menu, then pick neon, glass, neon+glass, or none. TaskVision writes the choice into every existing customHighlight entry and defaultHighlight, so you no longer have to edit each tag by hand.

Quick Start

Add a minimal setup to settings.json:

"taskvision.highlights.customHighlight": {
  "TODO": {
    "icon": "tasklist",
    "foreground": "#42A5F5",
    "scheme": "neon+glass",
    "colorType": "text",
    "glowType": "tag",
    "glassType": "tag",
    "fontType": "tag"
  },
  "FIXME": {
    "icon": "flame",
    "foreground": "#FF5252",
    "scheme": "neon+glass",
    "colorType": "text",
    "glowType": "tag",
    "glassType": "tag",
    "fontType": "tag"
  },
  "[ ]": {
    "icon": "issue-opened",
    "foreground": "#26C6DA",
    "scheme": "neon+glass",
    "colorType": "text",
    "glowType": "tag",
    "glassType": "tag",
    "fontType": "tag"
  },
  "[x]": {
    "icon": "issue-closed",
    "foreground": "#2E7D32",
    "scheme": "neon+glass",
    "colorType": "text",
    "glowType": "tag",
    "glassType": "tag",
    "fontType": "tag"
  }
}

Then try these comments:

// TODO [todo] ship the new onboarding
// TODO [blocked] waiting for legal copy
// TODO [review] shortcut handler updated
// NOTE [idea] split command and render layers

Per-channel brightness

Highlight rendering is layered. You can tune text, glow, optional glass fill, and glass border independently:

"taskvision.highlights.foregroundOpacity": 90,
"taskvision.highlights.glowOpacity": 45,
"taskvision.highlights.glassOpacity": 12,
"taskvision.highlights.glassBorderOpacity": 30

The same keys also work per tag inside taskvision.highlights.customHighlight. Legacy opacity is still supported as an alias for glassOpacity.

For glass schemes, background is treated as the accent colour. By default TaskVision keeps the acrylic effect on the text layer and does not add a filled background, so old alpha-heavy settings such as #42A5F566 do not turn into solid colour blocks. Set glassOpacity or glassBorderOpacity explicitly when you want a filled or outlined glass badge/band.

Settings

Setting	Default	Purpose
`taskvision.tree.showStatusPrefix`	`true`	Prefix default labels with `[status]`
`taskvision.tasks.defaultPriority`	`normal`	Default priority for tasks without metadata
`taskvision.aiContext.outputDir`	`.taskvision`	Output folder for AI context files
`taskvision.aiContext.respectCurrentFilters`	`true`	Export only the currently visible tree scope

FAQ

Why did my generated AI context stop showing up in the tree?

TaskVision intentionally excludes the output folder from scans to prevent self-reference loops.

Why did a task get a status even though I never wrote one?

TaskVision derives a default state from the tag. Use Add Missing Inline Statuses if you want those defaults written back into source.

Why do appearance changes sometimes seem to ignore user settings?

Workspace settings in .vscode/settings.json override global settings, and TaskVision writes appearance changes to workspace settings first when possible.

Project Structure

src/
├── extension.js         # Main extension entry and commands
├── tree.js              # Tree provider and node presentation
├── taskState.js         # Task state model
├── taskMetaStore.js     # Task metadata store + stable index
├── contextStore.js      # Context card sidecar store
├── changeSessionStore.js# Session sidecar store
├── annotationParser.js  # `tv:` directive parser
└── aiContext.js         # Unified AI context renderer

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.taskvision		.taskvision
.vscode		.vscode
agent		agent
resources		resources
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
.vscodeignore		.vscodeignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
License.txt		License.txt
MIGRATION.md		MIGRATION.md
README.md		README.md
README_zh.md		README_zh.md
buildCodiconNames.js		buildCodiconNames.js
debugging_journal.md		debugging_journal.md
package-lock.json		package-lock.json
package.json		package.json
package.nls.json		package.nls.json
package.nls.zh-cn.json		package.nls.zh-cn.json
webpack.config.js		webpack.config.js

Navigation Menu

Repository files navigation

Features

Task States

AI Collaboration Syntax

Tree Workflow

AI Context Export

Minimal Workflows

Highlight Model

Quick Start

Per-channel brightness

Settings

FAQ

Project Structure

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Features

Task States

AI Collaboration Syntax

Tree Workflow

AI Context Export

Minimal Workflows

Highlight Model

Quick Start

Per-channel brightness

Settings

FAQ

Project Structure

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages