AI Workflow Visualizer
An intuitive VS Code extension to visualize your AI Engineering Workflow checkpoints, git branch status, active work items, and context token limit in real-time. This extension acts as the visual companion for the AI Agent Workflow skills framework.
Features
- Real-Time Visualizer: Easily track active session state, checkpoints, and tasks in the Sidebar.
- Token Monitor: Monitor your context tokens limit in real-time.
- Git Branch Status: Keep track of git branch status and active work items during the AI Workflow.
How to Use
Install the Extension
- Search for "AI Workflow Visualizer" in the VS Code Extensions view (
Ctrl+Shift+X or Cmd+Shift+X) and click Install.
- Alternatively, install from the packaged
.vsix file using the "Install from VSIX..." command in VS Code.
Install the AI Skill Framework from GitHub
To make the visualizer functional, your project workspace needs to have the AI Agent Workflow skills installed. You can set them up by cloning from GitHub:
Option A: Global CLI (Recommended)
- Clone the skills framework repository to your machine:
git clone https://github.com/kyleit/AI-Agent-Workflow.git
cd AI-Agent-Workflow
- Run the bootstrap installer to add
aiwf to your system path:
- Linux/macOS:
./bootstrap.sh
- Windows (PowerShell):
.\bootstrap.ps1
- Open a terminal inside your target project workspace and run:
aiwf install
This will deploy the global policies (AI_RULES.md) and all core skills/ to your project's .agents/ directory.
Option B: Local Git Submodule
If you prefer to embed and track the framework version directly within your repository:
- In your project root, add the submodule:
git submodule add https://github.com/kyleit/AI-Agent-Workflow.git .agents/skills-framework
- Copy or symlink the
skills folder into .agents/skills:
- Linux/macOS:
mkdir -p .agents/skills/
cp -r .agents/skills-framework/skills/* .agents/skills/
- Windows (PowerShell):
New-Item -ItemType Directory -Force -Path .agents\skills\
Copy-Item -Path .agents\skills-framework\skills\* -Destination .agents\skills\ -Recurse -Force
Open Your Workspace
- Open your project workspace in VS Code.
Start/Initialize a Session
- Run your workflow's initialization command (e.g.,
aiwf init or /initialize-workflow depending on your setup) to generate the .agents/.session.json state. The extension will automatically watch and detect this file.
Monitor Progress
- Click on the AI Workflow icon in the VS Code Activity Bar (sidebar) to open the interactive dashboard.
Developer Guide: Session File Integration
The extension acts as a visualizer by watching a specific state file in the active workspace. This section outlines how to write data to the session file so the extension can read and display it.
How it Works
- File System Watcher: The extension looks for
.agents/.session.json in the root of the active workspace.
- Auto-update: When
.agents/.session.json is created, modified, or deleted, the extension reads the file, parses it as JSON, and posts the updated data to the sidebar webview panel.
- Dynamic Context Estimate (Fallback): If
workflow_usage_summary is not written in .session.json, the extension tries to estimate token usage by reading the latest brain log under ~/.gemini/antigravity-ide/brain/<conversation-id>/.system_generated/logs/transcript.jsonl.
Session File Schema (.agents/.session.json)
To update the visualizer UI, your CLI tool or agent skill must write to .agents/.session.json using the following JSON structure:
{
"workspace": {
"path": ".",
"valid": true
},
"git": {
"is_git_repository": true,
"branch": "feature/FEAT-001-visualizer",
"working_tree": "clean",
"default_branch": "main",
"latest_tag": "v1.0.5"
},
"work_item": {
"type": "FEAT",
"id": "FEAT-001",
"title": "Build AI Workflow Visualizer"
},
"version": {
"version": "1.0.6",
"source": "package.json"
},
"memory": {
"status": "FRESH",
"last_updated": "2026-07-04T10:33:00Z"
},
"rag": {
"connected": true,
"provider": "qdrant"
},
"checkpoint": 3,
"status": "in_progress",
"current_skill": "blueprint-to-implementation",
"current_step": "Implementing code edits",
"logs": [
"> Started blueprint analysis.",
"> Generated implementation plan docs/plans/FEAT-001_plan.md",
"> Created visualizer sidebar components."
],
"suggested_next_skill": "implementation-to-debug",
"suggested_next_command": "debug",
"updated_at": "2026-07-06T12:41:03Z",
"context_health": "healthy",
"visual_debug": "in_progress",
"visual_debug_skipped": false,
"browser_tools": "available",
"workflow_usage_summary": {
"provider": "antigravity",
"model": "Gemini 3.5 Flash",
"input_tokens": 8120400,
"output_tokens": 68532,
"cache_tokens": 1218060,
"thinking_tokens": 4820,
"active_tokens": 72400,
"total_tokens": 8188932,
"limit_tokens": 2000000,
"percentage": 3.62,
"estimated_cost_usd": 10.4072,
"accuracy": "estimated",
"updated_at": "2026-07-06T12:41:03Z"
},
"project_usage_summary": {
"input_tokens": 8120400,
"output_tokens": 68532,
"cache_tokens": 1218060,
"thinking_tokens": 4820,
"total_tokens": 8188932,
"estimated_cost_usd": 10.4072,
"updated_at": "2026-07-06T12:41:03Z"
},
"global_usage_summary": {
"input_tokens": 12450200,
"output_tokens": 98532,
"cache_tokens": 1860240,
"thinking_tokens": 9480,
"total_tokens": 12548732,
"estimated_cost_usd": 15.9872,
"updated_at": "2026-07-06T12:41:03Z"
}
}
Guidelines for Developers
- Workspace Path: The
workspace.path must always be "." (a relative representation). Do not write absolute paths to the session file.
- Checkpoint Levels: Checkpoints are represented as integers (typically 1 to 10).
- Status Value: Use
"in_progress", "completed", or "failed".
- Visual Debug: Set
"visual_debug_skipped": true or "visual_debug": "skipped" to bypass the visual debugging stage for backend-only features.
- Token Estimation: Developers should compute or estimate the active token size of their current context session and write it directly to
context_usage.total_tokens (with limit_tokens: 2000000 and percentage representation).
