AI Skill 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
        

   Minimum Required Skills

   To ensure the visualizer works properly, your workspace must contain at least the following skills in the .agents/skills/ (or root skills/) directory:

   • workflow-runtime (Mandatory): Contains the essential backend engines (provider_engine.py for provider diagnostics, and workflow_runtime.py to handle human-in-the-loop CLI inputs/approvals).
   • initialize-workflow (Recommended): Responsible for bootstrapping the workspace environment and generating the initial .agents/state/ JSON directory structure.
   • project-memory-bootstrap (Recommended): Extracts project context information and writes workspace metadata to context.json.

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: Split State Integration

The extension acts as a visualizer by watching the state directory in the active workspace. This section outlines how the extension reads and displays the session state.

How it Works

1. Directory Watcher: The extension watches the .agents/state/ directory and .agents/.session.json in the active workspace.
2. State Aggregation: Whenever any .json file inside .agents/state/ is modified, the extension automatically reads all state files, aggregates them into a single session state object, and posts the updated data to the sidebar webview panel.
3. Backward Compatibility: If .agents/.session.json exists as a flat file, the extension falls back to reading it directly.
4. Dynamic Context Estimate (Fallback): If token usage is not found in the state, the extension estimates usage by reading the latest brain log under ~/.gemini/antigravity-ide/brain/<conversation-id>/.system_generated/logs/transcript.jsonl.

State Files Structure (.agents/state/)

To update the visualizer UI, your CLI tool or agent skill must write to specific files inside .agents/state/:

• context.json: Contains workspace profile, version, git configuration, memory and RAG connectivity status.
• workflow.json: Contains the active checkpoint, logs, status, current skill/step, and suggested next steps.
• usage.json: Contains token usage stats (workflow, project, and global summaries).
• recovery.json: Handles fallback and recovery metrics.
• approvals.json: Records human-in-the-loop approvals.
• breakdown.json: Details context breakdown percentages.
• agents.json: Details of active analysis agents.

Example: workflow.json

{
  "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"
  ],
  "suggested_next_skill": "implementation-to-debug",
  "suggested_next_command": "debug",
  "updated_at": "2026-07-06T12:41:03Z"
}

Example: usage.json

{
  "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).