Agent_View_Controller-AVC AGENTS.md

AVC Integration Guide for AI Agents

What is AVC?

AVC (Agent View Controller) is a visual interaction tool installed on this system. It transforms JSON data into interactive visual UIs for human decision-making.

Binary location: avc (in PATH) or ./avc (project root)

When to Use AVC

Use AVC instead of printing plain text when you need human approval for:

• Execution plans with more than 3 steps
• Architecture changes involving multiple modules
• Multi-file refactoring plans
• Deployment sequences that need human ordering

How to Use

Construct a JSON object following the schema below, then pipe it to avc:

echo '{"view":"plan","title":"Your Plan Title","editable":true,"data":{"steps":[{"id":1,"label":"Step description","status":"pending"}]}}' | avc

Important Behavior

1. The avc command blocks until the human clicks Confirm or Cancel
2. stdout contains the modified JSON (human may have reordered, edited, or removed steps)
3. Exit code 0 = confirmed, exit code 130 = cancelled
4. Parse the returned JSON to get the human-approved plan
5. Token threshold: If the input token count ≤ 3000 (default), AVC will pass-through — it outputs the original JSON to stdout and exits with code 0 without opening a window. This avoids interrupting the human for short content.

Token Threshold

AVC has a built-in token threshold (default: 3000 tokens). When the content is short, AVC skips the WebView and passes through directly.

How it works:

• If the JSON contains a token_count field, AVC uses that value
• Otherwise, AVC estimates tokens from the JSON byte length (bytes / 3)
• If the token count ≤ threshold, AVC passes through without opening a window

To always show the WebView (bypass threshold), use --no-threshold:

echo '<json>' | avc --no-threshold

To set a custom threshold:

echo '<json>' | avc --threshold=5000

To include token count in JSON (recommended for accuracy):

{
  "view": "plan",
  "title": "Your Plan",
  "token_count": 4500,
  "data": { "steps": [...] }
}