AI Workflow Visualizer

An intuitive VS Code companion extension to visualize your AI Engineering Workflow checkpoints, git branch status, active work items, and token usage in real-time. This extension acts as the visual companion for the AI Agent Workflow skills framework.

Redesigned UI & Dashboards

The visualizer has been fully upgraded to a modern, high-performance tabbed interface, separating stepper checkpoints from advanced developer analytics.

Key Features

• Checkpoints Timeline Tab: Real-time stepper status monitor tracking the active AI Agent role (Planner, Architect, Coder, Reviewer, Release Manager) and detailed sub-tasks.
• Context & Statistics Tab: Deep telemetry for token and cost management:
  • Context Analytics: Context window capacity progress bar, growth trend sparklines, warning/critical alerts, and collapsible Context Breakdown tree view.
  • Accumulated API Usage: Detailed input, output, cache read, and reasoning/thinking tokens count, total request count, active model, and session cost in USD.
  • Efficiency Analysis: Token I/O ratio, cache hit rate, memory hit rate, and estimated savings.
  • Project & Global API usage: Side-by-side tracking of tokens and cost for the active workspace and total history.
• Custom Select UI & Audit Compare: Eliminates native HTML select flickering in VS Code Webviews. Features a custom dropdown select to choose and review request details, or compare token differences between any two requests.
• Tab Persistence: Remembers the active tab (localStorage integrated) so reloading the workspace or toggling the sidebar retains your current view.

How to Use

1. 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.

2. 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)

   1. Clone the skills framework repository to your machine:

      git clone https://github.com/kyleit/AI-Agent-Workflow.git
      cd AI-Agent-Workflow
      

   2. Run the bootstrap installer to add aiwf to your system path:
      • Linux/macOS: ./bootstrap.sh
      • Windows (PowerShell): .\bootstrap.ps1
   3. 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:

   1. In your project root, add the submodule:

      git submodule add https://github.com/kyleit/AI-Agent-Workflow.git .agents/skills-framework
      

   2. 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
        

3. Open Your Workspace

   • Open your project workspace in VS Code.

4. 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.

5. 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

1. File System Watcher: The extension looks for .agents/.session.json in the root of the active workspace.
2. 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.
3. 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).