ASCII Agent — VS Code Extension

Auto-generates and keeps an ASCII file-tree and a Copilot-powered architecture data-flow diagram up to date as your codebase changes. Requires GitHub Copilot Chat.

What It Does

ASCII Agent watches your workspace and autonomously keeps two strictly separated ASCII text diagrams up to date:

Requirements

• VS Code ≥ 1.93
• GitHub Copilot (for architecture diagram generation)

Quick Start

1. Open any workspace in VS Code.
2. Run ASCII Agent: Initialize from the Command Palette (Cmd/Ctrl+Shift+P).
3. ASCII Agent creates docs/file_tree.md and docs/architecture.md immediately, then watches for changes.

Commands

Configuration (.asciirc.json)

Place a .asciirc.json file in your workspace root to customize behavior. All fields are optional; missing fields fall back to defaults.

{
  // Paths/patterns to ignore in the file tree
  "ignore": ["node_modules", ".git", "dist", "out", ".ascii_history"],

  // Glob patterns that trigger architecture re-analysis on change
  "architectureWatchPatterns": ["src/**/*.{ts,tsx,js,jsx}", "api/**/*.ts"],

  // Output file locations (relative to workspace root)
  "outputPaths": {
    "fileTree": "docs/file_tree.md",
    "architecture": "docs/architecture.md",
  },

  // Milliseconds to wait after last file event before regenerating (min 500)
  "debounceMs": 2000,

  // Maximum history snapshots to retain in .ascii_history/
  "maxHistorySnapshots": 50,

  // Start watching automatically on activation
  "autoWatchEnabled": true,

  // Extra files fed as context to the architecture LM prompt
  "contextFiles": ["docs/design.md"],

  // Priority-ordered globs for token-budget truncation
  "filePriority": ["src/index.ts", "src/**"],

  // Custom tag map (replaces defaults entirely when provided)
  "tags": {
    "src/components/**": "[ui]",
    "api/**": "[backend]",
    "*.json": "[config]",
  },
}

History Snapshots

Before every architecture overwrite, ASCII Agent saves a timestamped snapshot to .ascii_history/ in your workspace root. Add this directory to .gitignore — ASCII Agent will prompt you to do this automatically.

Status Bar

The $(eye) ASCII Agent item in the status bar shows the watcher state. Click it to toggle auto-watch on/off. During generation it shows a spinner: $(sync~spin) ASCII Agent: generating...

Output Channel

All diagnostic output is written to the ASCII Agent output channel (View → Output → ASCII Agent).

Token Usage

After every architecture diagram generation, ASCII Agent logs a token usage estimate to the ASCII Agent output channel. Open it via View → Output → ASCII Agent to see per-request and running totals, for example:

Token usage — request: ~1240 in / ~380 out | session total: ~1620 tokens (1 requests) | lifetime: ~4890 tokens (3 requests)

To see a formatted summary at any time, run ASCII Agent: Show Token Usage from the Command Palette (Cmd/Ctrl+Shift+P). A Quick Pick panel opens showing:

• Session (this window) — tokens used since the current VS Code window opened
• Lifetime (all time) — cumulative total across all sessions

Note: Estimates use a ~4 chars/token heuristic because the VS Code LM streaming API does not expose exact token counts. Figures are intended for rough cost awareness, not billing accuracy.

Portability

ASCII Agent is fully project-agnostic. It contains zero hardcoded project names or file paths. All paths are resolved from the active workspace root and driven by .asciirc.json. It works in any VS Code workspace with Copilot enabled.

Development (running locally without installing)

This is for testing the extension while actively working on it.

One-time setup:

cd tools/vscode-ascii-agent
npm install

Steps to run:

1. In VS Code, open tools/vscode-ascii-agent/ as your workspace root (File → Open Folder → select that folder). This is required so VS Code can find .vscode/launch.json.
2. Press F5 (or Run → Start Debugging) and select Run ASCII Agent Extension.
3. VS Code builds the extension automatically, then opens a second VS Code window called the "Extension Development Host." Your extension is live inside that window.
4. In the Extension Development Host window, open your target project folder (File → Open Folder). For example, open word-for-word-game/.
5. Press Cmd+Shift+P and run ASCII Agent: Initialize to test.

Rebuilding after code changes:

• Stop the debugger, press F5 again to rebuild and relaunch, OR
• Run node esbuild.mjs --watch in a terminal for continuous rebuilds, then use Developer: Reload Window in the Extension Development Host to pick up changes without restarting the debugger.