<p align="center">
<strong>๐ Featured in <a href="https://www.ruanyifeng.com/blog/2026/05/weekly-issue-397.html">Ruan Yifeng's Weekly (Issue #397)</a> โ huge thanks for the shoutout! ๐</strong>
</p>
<p align="center">
<h1 align="center">๐๏ธ AVC โ Agent View Controller</h1>
<p align="center">
<strong>The Visual Dimension Elevator in Unix Pipes</strong><br/>
<em>Agent outputs JSON in โ Human's visual decision JSON out</em>
</p>
<p align="center">
<strong>๐ฌ๐ง English</strong> ยท <a href="./README_CN.md">๐จ๐ณ ไธญๆ</a>
</p>
<p align="center">
<sub><em>More README translations welcome โ see CONTRIBUTING.</em></sub>
</p>
</p>
---
## The Problem
AI Agents (Codex CLI, Claude Code, Cursor, Gemini CLI...) are **blazing fast** in the terminal. They read code, generate plans, and execute commands at machine speed.
But when they need **human approval** โ a refactoring plan, an architecture change, a multi-step deployment โ they dump walls of text into the terminal. Humans are forced to read 50+ lines of monospace text, mentally parse the structure, and type "yes" or "no."
**This is insane.** Humans are visual creatures. Our brains process images 60,000ร faster than text.
## The Solution
AVC is a **3MB single binary** that does one thing perfectly:
```bash
echo '{"view":"plan","data":{...}}' | avc
```
1. Reads JSON from `stdin`
2. Pops up a native WebView window with a beautiful interactive UI
3. Human drags, edits, reorders โ making decisions visually
4. Outputs modified JSON to `stdout`
5. Window closes. Agent continues.
**Like `fzf` gave CLI users interactive selection, AVC gives all CLI agents visual interaction.**
```
Traditional pipe: agent | grep | jq | awk (text processing)
AVC pipe: agent | avc (visual processing)
```
> ### What's new in v0.3.0
> - **๐ 7-language UI** โ `en`, `zh`, `ja`, `ko`, `es`, `fr`, `de` via the `lang` JSON field
> - **๐บ Homebrew tap** โ `brew install study8677/tap/avc`
> - **๐ 6 new example scenarios** โ refactoring, CI/CD, incident response, K8s, data migration, code review
> - **๐งช Test suite + macOS CI** โ 14 cases, runs headless
> - **๐ Critical `.gitignore` fix** โ `install.sh` now actually works on fresh clones
>
> See the [full release notes](https://github.com/study8677/Agent_View_Controller-AVC/releases/tag/v0.3.0) or the [CHANGELOG](CHANGELOG.md).
## Quick Start
### Install
**๐บ Homebrew (macOS / Linuxbrew, recommended)**
```bash
brew install study8677/tap/avc
```
After install, `brew info avc` prints one-line copy commands to wire the skill into Claude Code / Codex / Gemini.
**๐ One-line installer** (builds from source + auto-installs skills for every detected agent)
```bash
curl -sSL https://raw.githubusercontent.com/study8677/Agent_View_Controller-AVC/main/install.sh | bash
```
Installs to `~/.local/bin` (no sudo) when it's on your `PATH`, otherwise falls back to `/usr/local/bin`. Requires Go โฅ 1.24.
<details>
<summary>Manual install</summary>
```bash
git clone https://github.com/study8677/Agent_View_Controller-AVC.git
cd Agent_View_Controller-AVC
go build -o avc .
install -m 755 avc ~/.local/bin/ # or sudo cp avc /usr/local/bin/
# Install skill for your agent
mkdir -p ~/.codex/skills/avc && cp skills/avc/SKILL.md ~/.codex/skills/avc/ # Codex CLI
mkdir -p ~/.claude/skills/avc && cp skills/avc/SKILL.md ~/.claude/skills/avc/ # Claude Code
mkdir -p ~/.gemini/skills/avc && cp skills/avc/SKILL.md ~/.gemini/skills/avc/ # Gemini CLI
```
</details>
### Try It
```bash
cat examples/execution-plan.json | ./avc
```
A native window pops up:
<p align="center">
<img src="docs/plan-view-demo-en.png" width="600" alt="AVC Plan View Demo" />
</p>
Drag steps to reorder, edit text, skip steps, add new ones, then click **โ
Confirm** โ the modified JSON appears in your terminal.
## Usage Examples
### Example 1: Database Migration Plan
```bash
echo '{
"view": "plan",
"title": "Database Migration v3 โ v4",
"editable": true,
"data": {
"steps": [
{"id": 1, "label": "Backup production database", "status": "pending"},
{"id": 2, "label": "Run migration scripts on staging", "status": "pending"},
{"id": 3, "label": "Verify data integrity checks", "status": "pending"},
{"id": 4, "label": "Switch DNS to maintenance page", "status": "pending"},
{"id": 5, "label": "Execute production migration", "status": "pending"},
{"id": 6, "label": "Run smoke tests", "status": "pending"},
{"id": 7, "label": "Remove maintenance page", "status": "pending"}
]
}
}' | ./avc
```
> ๐ก Human can reorder steps (e.g., move smoke tests before DNS switch), skip backup if already done, or add a "Notify team on Slack" step.
### Example 2: API Refactoring Plan
```bash
echo '{
"view": "plan",
"title": "REST โ GraphQL Migration",
"editable": true,
"data": {
"steps": [
{"id": 1, "label": "Set up GraphQL server with Apollo", "status": "pending"},
{"id": 2, "label": "Define schema types for User, Post, Comment", "status": "pending"},
{"id": 3, "label": "Implement resolvers with existing service layer", "status": "pending"},
{"id": 4, "label": "Add authentication middleware", "status": "pending"},
{"id": 5, "label": "Set up DataLoader for N+1 prevention", "status": "pending"},
{"id": 6, "label": "Write integration tests", "status": "pending"},
{"id": 7, "label": "Deploy with REST fallback route", "status": "pending"},
{"id": 8, "label": "Deprecate REST endpoints", "status": "pending"}
]
}
}' | ./avc
```
### Example 3: Capture and Use the Result
```bash
# Agent captures the human-approved plan
RESULT=$(cat examples/execution-plan.json | ./avc)
if [ $? -eq 0 ]; then
echo "โ
Human approved:"
echo "$RESULT" | jq '.data.steps[] | select(.skipped != true) | .label'
# Agent proceeds to execute only the approved, non-skipped steps
else
echo "โ Human cancelled the plan"
fi
```
### More examples
The [`examples/`](./examples/) folder ships **7 ready-to-pipe scenarios** covering refactoring, CI/CD, incident response, Kubernetes deploys, data migration, and code review โ across 4 UI languages (en/zh/ja/fr). Each has a realistic `token_count` so the popup fires without `--no-threshold`:
```bash
cat examples/incident-response.json | avc # zh โ production DB outage runbook
cat examples/kubernetes-deploy.json | avc # ja โ stateless service rollout
cat examples/data-migration.json | avc # fr โ PostgreSQL โ MongoDB
```
See [`examples/README.md`](./examples/README.md) for the full index.
## Supported Views
| View Type | Description | Interaction | Status |
|-----------|-------------|-------------|--------|
| `plan` | Execution plans / step lists | Drag to reorder, edit, skip, add/delete | โ
Ready |
| `graph` | Architecture topology / dependency map | Drag nodes, connect/disconnect edges, edit labels, keyboard nav | โ
Ready |
| `diff` | Code diff review | Accept/reject per line | ๐ง Planned |
| `table` | Data tables | Edit cells, sort columns | ๐ง Planned |
## JSON Schema
```json
{
"view": "plan",
"title": "Microservice Refactor Plan",
"lang": "en",
"editable": true,
"token_count": 4500,
"data": {
"steps": [
{ "id": 1, "label": "Extract UserService", "status": "pending" },
{ "id": 2, "label": "Create API Gateway", "status": "pending" },
{ "id": 3, "label": "Configure service discovery", "status": "pending" }
]
},
"actions": ["confirm", "cancel"]
}
```
> Notes:
> - `token_count` is optional. If omitted, AVC estimates from byte length.
> - `lang` is optional (default `"en"`). Set it to localize UI chrome โ see the next section for all 7 supported languages.
## ๐ UI Languages
AVC's WebView UI (buttons, status bar, tooltips) is translated into **7 languages**. Set the top-level `lang` field on your JSON input to pick one:
| `lang` | Language | Confirm button | Cancel button | Status: "pending" |
|--------|-------------|----------------|---------------|-------------------|
| `en` | English | Confirm | Cancel | pending |
| `zh` | ไธญๆ | ็กฎ่ฎคๆง่ก | ๅๆถ | ๅพ
ๆง่ก |
| `ja` | ๆฅๆฌ่ช | ๅฎ่กใ็ขบๅฎ | ใญใฃใณใปใซ | ไฟ็ไธญ |
| `ko` | ํ๊ตญ์ด | ์คํ ํ์ธ | ์ทจ์ | ๋๊ธฐ ์ค |
| `es` | Espaรฑol | Confirmar | Cancelar | pendiente |
| `fr` | Franรงais | Confirmer | Annuler | en attente |
| `de` | Deutsch | Bestรคtigen | Abbrechen | ausstehend |
Example โ render the UI in Japanese:
```json
{
"view": "plan",
"title": "ใฆใผใถใผ่ช่จผใฎใชใใกใฏใฟใชใณใฐ",
"lang": "ja",
"editable": true,
"data": {
"steps": [
{ "id": 1, "label": "่ช่จผใใใซใฆใงใขใๆฝๅบ", "status": "pending" },
{ "id": 2, "label": "JWT ใตใผใในใไฝๆ", "status": "pending" },
{ "id": 3, "label": "ใซใผใใใณใใฉใผใๆดๆฐ", "status": "pending" }
]
}
}
```
> The `lang` field defaults to `"en"` and only affects UI chrome (buttons, status labels, tooltips). It does **not** translate your step content โ keep `label` text in whatever language matches your audience.
## ๐๏ธ Token Threshold
AVC has a built-in **smart filter**: only when the content exceeds a token threshold (default: **3000 tokens**) will the WebView window pop up. Short content passes through directly without interrupting the human.
### How It Works
```
stdin JSON โโโ AVC reads โโโ Check token count
โ
โค 3K token โ > 3K token
โ โ
Output to stdout Pop up WebView
(pass-through) Interactive review
```
- If the JSON contains a `token_count` field โ use that value
- Otherwise โ estimate from byte length (`bytes / 3`)
- If token count โค threshold โ pass-through (exit code `0`, original JSON on stdout)
### CLI Options
```bash
# Always show WebView (bypass threshold)
echo '<json>' | avc --no-threshold
# Set a custom threshold
echo '<json>' | avc --threshold=5000
```
### Include Token Count in JSON (Recommended)
For accurate control, have the Agent include `token_count` in the JSON:
```json
{
"view": "plan",
"title": "Your Plan",
"token_count": 4500,
"data": { "steps": [...] }
}
```
## Using AVC with AI Agents
AVC is **agent-agnostic** โ it works with any AI coding agent that can execute shell commands.
### โญ Method 1: Install as a Skill (Recommended)
The easiest way. Copy the skill folder into your agent's skills directory โ works globally across all projects:
```bash
# For Gemini CLI / Antigravity
cp -r skills/avc/ ~/.gemini/skills/avc/
# For any project with a skills/ directory
cp -r skills/avc/ your-project/skills/avc/
```
Once installed, the agent **automatically knows** when and how to use AVC. No per-project configuration needed.
### Method 2: Per-Project Config Files
### With OpenAI Codex CLI
Add the included `AGENTS.md` to your project root (already provided in this repo).
```markdown
## Visual Decision Tool
When you generate a complex execution plan (>3 steps), architecture change,
or multi-file refactoring plan, output it as AVC-compatible JSON and pipe
it through `avc` for human visual review:
echo '{"view":"plan","title":"...","data":{"steps":[...]}}' | avc
The command blocks until the human confirms. Capture stdout to get the
human-modified plan, then execute accordingly.
```
Then Codex will automatically use AVC when it generates complex plans:
```bash
# Codex generates a plan โ pipes to AVC โ waits for human โ continues
echo '{"view":"plan","title":"Refactor Auth Module","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"}
]}}' | avc
```
### With Claude Code
In your project's `CLAUDE.md` or system prompt:
```markdown
## AVC Integration
For complex execution plans, use the `avc` visual tool instead of
printing plain text. Construct a JSON object with view type and data,
then pipe it through `avc`:
echo '<json>' | avc
This opens a visual UI for the human to review and modify the plan.
The modified JSON is returned via stdout. Wait for it before proceeding.
```
### With Cursor (AI IDE)
In Cursor's terminal, AVC works as a standard Unix pipe tool. Configure via `.cursorrules`:
```markdown
## Visual Planning
When generating multi-step plans, use `avc` for visual human review:
1. Construct plan as JSON with view:"plan" schema
2. Run: echo '<json>' | avc
3. Read stdout for the human-approved plan
4. Execute the approved steps
```
### With Any Agent
The pattern is universal โ **any** tool that can:
1. Write JSON to a process's stdin
2. Read the process's stdout
3. Wait for the process to exit
...can use AVC. It's just a Unix pipe.
## Design Philosophy
| Principle | Description |
|-----------|-------------|
| **Agent is CPU, AVC is Display** | Agents do the thinking. AVC does the showing. |
| **Agent-agnostic** | Works with Codex, Claude, Gemini, Cursor, or any CLI tool |
| **Unix Philosophy** | stdin in, stdout out. Compose with any pipe |
| **Zero Dependencies** | Single binary. Uses system-native WebView |
| **< 100ms Startup** | Native binary, no Node.js / npm overhead |
## Tech Stack
- **Go** + [webview/webview_go](https://github.com/webview/webview_go) โ system-native WebView bindings
- **Vanilla JS** โ embedded via `go:embed`, zero frontend dependencies
## Platform Support
| Platform | WebView Backend | Status |
|----------|-----------------|--------|
| **macOS** | WKWebView | โ
Verified in CI |
| **Linux** | WebKitGTK | โ Should work โ not yet tested. Reports welcome. |
| **Windows** | WebView2 | โ Should work โ not yet tested. Reports welcome. |
> If you successfully run AVC on Linux or Windows, please open an issue or PR
> so we can mark the platform as verified.
## Architecture
```
โโโโโโโโโโโโ stdin โโโโโโโโโโโโ render โโโโโโโโโโโโ
โ AI Agent โ โโโโ JSON โโโโ โ AVC โ โโโโโโโโโโโโโ โ WebView โ
โ (Codex, โ โ (3MB Go โ โ (Native โ
โ Claude, โ โโโ JSON โโโโ โ Binary) โ โโโ confirm โ โ Window) โ
โ Cursor) โ stdout โโโโโโโโโโโโ callback โโโโโโโโโโโโ
โโโโโโโโโโโโ โ Human
```
## Roadmap
AVC's vision is to become the **universal visual layer** for all CLI agents. Every type of structured data an agent produces should have a beautiful, interactive view.
### Phase 1 โ Foundations โ
| View | What Agent Outputs | What Human Sees | Status |
|------|--------------------|-----------------|--------|
| `plan` | Steps with order & status | Draggable step list with edit/skip/delete | โ
Done |
### Phase 2 โ Core Views ๐ง
| View | What Agent Outputs | What Human Sees |
|------|--------------------|------------------|
| `graph` | Nodes + edges (services, modules) | Interactive topology โ drag nodes, edit labels, add/remove connections |
| `diff` | File paths + hunks | Side-by-side diff with per-line Accept / Reject / Edit |
| `table` | Rows + columns | Sortable, filterable, editable data grid |
### Phase 3 โ Rich Visual Content ๐ฎ
| View | What Agent Outputs | What Human Sees |
|------|--------------------|------------------|
| `tree` | File/directory structure | Interactive file tree โ rename, move, create, delete |
| `timeline` | Events with timestamps | Gantt-chart-style timeline โ drag to adjust scheduling |
| `kanban` | Cards with columns | Kanban board โ drag cards between columns |
| `form` | Fields + validation rules | Multi-step wizard form โ fill in configs, select options |
| `mindmap` | Hierarchical ideas | Expandable mind map โ restructure by dragging branches |
### Phase 4 โ Advanced Visualization ๐
| View | What Agent Outputs | What Human Sees |
|------|--------------------|------------------|
| `metrics` | Numbers + time series | Live dashboard with charts and gauges |
| `flow` | Pipeline stages + conditions | CI/CD flow diagram โ reorder stages, toggle gates |
| `compare` | Multiple options with pros/cons | Side-by-side comparison cards โ vote & rank |
| `3d-graph` | Complex dependency graphs | 3D force-directed graph โ rotate, zoom, filter |
> **The goal**: Any structured JSON โ one `| avc` โ instant visual interaction. No more reading walls of terminal text.
## Contributing
Contributions welcome! We especially need help with:
- **New view types** โ Pick any from the roadmap above and implement it
- **UI polish** โ Animations, themes, accessibility
- **Platform verification** โ Linux (WebKitGTK) and Windows (WebView2) are unverified;
successful runs (or fixes) would let us turn โ into โ
- **Agent integration examples** โ Show how AVC works with different agents
## License
Apache 2.0
Read the source README