avc

name	avc
description	Use AVC (Agent View Controller) to present complex execution plans, architecture changes, and multi-step operations as interactive visual UIs. Instead of dumping walls of text, pipe structured JSON to `avc` for human visual review and confirmation. The human can drag-to-reorder, edit, skip, delete, and add steps before confirming.

AVC — Agent View Controller

AVC is a visual interaction tool that transforms JSON into interactive native WebView UIs. Use it when you need human approval for complex decisions.

When to Use

Use avc instead of printing plain text when:

• Execution plans with more than 3 steps
• Architecture changes involving multiple modules
• Multi-file refactoring plans
• Deployment sequences that need human review
• Any complex plan where the human should visually review and reorder steps

Prerequisites

avc must be installed and available in PATH:

# From source
git clone https://github.com/study8677/Agent_View_Controller-AVC.git
cd Agent_View_Controller-AVC && go build -o avc . && sudo cp avc /usr/local/bin/

How to Use

Step 1: Construct JSON

Build a JSON object with view type and structured data:

{
  "view": "plan",
  "title": "Your Plan Title",
  "lang": "en",
  "editable": true,
  "token_count": 4500,
  "data": {
    "steps": [
      {"id": 1, "label": "Step description", "status": "pending"},
      {"id": 2, "label": "Another step", "status": "pending"}
    ]
  }
}

Tip — lang field: Localizes UI chrome (buttons / status bar / tooltips) only — not step content. Supported: en (default), zh, ja, ko, es, fr, de. Match it to the language of your step labels for a consistent UI.

Step 2: Pipe to AVC

echo '<json>' | avc

Step 3: Read the Result

• Exit code 0 = human confirmed → stdout contains modified JSON
• Exit code 130 = human cancelled

RESULT=$(echo '{"view":"plan","title":"My Plan","token_count":5000,"data":{"steps":[{"id":1,"label":"Step 1","status":"pending"}]}}' | avc)

if [ $? -eq 0 ]; then
  # Parse $RESULT — human may have reordered, edited, or removed steps
  echo "$RESULT"
else
  echo "Human cancelled"
fi

Important Behavior

1. avc blocks until the human clicks Confirm or Cancel
2. stdout contains the human-modified JSON (may have reordered/edited/removed steps)
3. If token_count ≤ 3000 (default threshold), AVC passes through without opening a window
4. Use --no-threshold to always show the WebView window
5. Use --threshold=N to set a custom threshold

Token Threshold

AVC has a smart filter: short content passes through directly.

• If JSON contains token_count field → uses that value
• Otherwise → estimates from byte length (bytes / 3)
• If ≤ threshold → pass-through (no window, exit 0, original JSON on stdout)

Include token_count in your JSON for accurate control.

What the Human Can Do

When the human sees your plan in AVC, they can:

• Drag & drop to reorder steps
• Edit step descriptions by clicking on text
• Skip steps they don't want executed
• Delete steps entirely
• Add new steps

Always respect the human's modifications in the returned JSON.

Supported Views

view	Use for	Data shape
plan	Linear step-by-step execution plans (deploys, migrations, TODOs)	data.steps[]
graph	Architecture topology / dependency map / ER / workflow	data.nodes[] + data.edges[]

Pick graph when the agent's output is a relationship, not a sequence — e.g., microservice architecture, module dependency map, database ER diagram, data flow. Nodes are { id, label, type?, x?, y? } with type ∈ { service, gateway, database, external, default }. Edges are { from, to, label? }. Positions persist on round-trip (so the human's layout survives).

Example: Full Agent Workflow

# 1. Agent generates a plan as JSON
PLAN='{"view":"plan","title":"Refactor Auth","token_count":5000,"editable":true,"data":{"steps":[
  {"id":1,"label":"Extract auth middleware","status":"pending"},
  {"id":2,"label":"Create JWT service","status":"pending"},
  {"id":3,"label":"Update route handlers","status":"pending"},
  {"id":4,"label":"Add integration tests","status":"pending"}
]}}'

# 2. Pipe to AVC for human review
APPROVED=$(echo "$PLAN" | avc)

# 3. If confirmed, execute only approved steps
if [ $? -eq 0 ]; then
  echo "$APPROVED" | jq -r '.data.steps[] | select(.skipped != true) | .label'
fi