Codebuddy acp bridge

CodeBuddy ACP Bridge

Use this skill to make the current AI agent act as planner/reviewer while local CodeBuddy acts as executor.

Current public version: 0.2.0.

Core Workflow

1. Clarify the user's goal and define acceptance criteria.
2. Run a local environment preflight before the first delegation in a session:

PYTHONPYCACHEPREFIX=/tmp/codebuddy-acp-pycache \
python3 scripts/codebuddy_acp_bridge.py \
  --doctor \
  --cwd /path/to/project

3. If --doctor reports server failure, ask the user to start CodeBuddy:

codebuddy --serve --port 8080 --session-id my-session

4. If --doctor reports auth failure, stop and tell the user:

请打开 http://127.0.0.1:8080/ ，按页面提示扫码/授权登录。
看到“登录成功，返回 CLI 继续使用”后告诉我，我再继续。

5. Split the work into:
   • planner work for the current agent: reasoning, scope control, task packaging, final validation.
   • executor work for CodeBuddy: bounded implementation, inspection, file processing, or tool work.
6. Send only the bounded executor task to CodeBuddy with scripts/codebuddy_acp_bridge.py.
7. Read CodeBuddy's returned visible text.
8. Validate the result against the acceptance criteria.
9. If the result is incomplete, refine the executor prompt and rerun, or finish the missing work locally when safer.

Role Boundary

The current AI agent is responsible for planning, task decomposition, acceptance criteria, safety boundaries, final validation, focused fixes, tests, and deciding whether work is ready to submit.

CodeBuddy is responsible for bounded executor work such as bulk inspection, code generation, documentation generation, or command/tool execution inside the approved scope.

Executor Prompt Contract

Make CodeBuddy prompts narrow and explicit. Include:

• role: executor only.
• exact subtask.
• repository or working directory context.
• allowed actions and forbidden actions.
• expected output format.
• acceptance criteria.

Template:

你是执行器，不要扩大任务范围。

任务：
<bounded subtask>

约束：
- 只处理上述任务。
- 不要改动无关文件。
- 如果需要登录、权限或用户确认，请直接说明并停止。

输出：
- 简短说明你做了什么。
- 列出修改文件或关键发现。
- 说明如何验证。

验收标准：
<criteria>

Run The Bridge

Resolve the script path relative to this skill folder:

PYTHONPYCACHEPREFIX=/tmp/codebuddy-acp-pycache \
python3 scripts/codebuddy_acp_bridge.py \
  --cwd /path/to/project \
  --json \
  "<executor prompt>"

Use these options when helpful:

--base-url http://127.0.0.1:8080   local CodeBuddy server URL
--cwd /path/to/project             working directory for the CodeBuddy session
--session-id <uuid>                reuse an existing ACP session
--model deepseek-v4-flash          choose a cheaper executor model
--mode plan                        analyze only; no edits or commands
--mode acceptEdits                 allow file edits after the plan is trusted
--doctor                           check Python, CLI, server, cwd, and auth
--wait-login                       wait while the user scans/logs in
--open-login                       open the local CodeBuddy login page
--show-events                      print ACP event kinds to stderr
--event-log /tmp/codebuddy-acp-events.jsonl
                                   write raw ACP session/update events as JSON Lines
--max-wall-seconds 120             stop waiting after the wall-clock budget and return collected text

Prefer --mode plan for first passes and risky tasks. Use edit-capable modes only when the user requested implementation and the subtask is clearly bounded.

Never use --mode bypassPermissions or --mode fullAccess unless the user explicitly approved that risk. The script blocks these modes unless --allow-risky-mode is provided.

For tool-heavy tasks, use --event-log and --max-wall-seconds so the planner can inspect partial progress and diagnose stuck runs:

PYTHONPYCACHEPREFIX=/tmp/codebuddy-acp-pycache \
python3 scripts/codebuddy_acp_bridge.py \
  --cwd /path/to/project \
  --json \
  --event-log /tmp/codebuddy-acp-events.jsonl \
  --max-wall-seconds 120 \
  "<bounded executor prompt>"

ACP Capability Boundary

Do not add terminal or fs entries to ACP clientCapabilities unless the bridge also implements server-to-client JSON-RPC request handling and replies to those requests.

This bridge intentionally leaves clientCapabilities empty. CodeBuddy should execute Bash and file tools on the server side. If the bridge declares terminal/file capabilities without implementing the matching RPC handlers, CodeBuddy can delegate tool execution to the bridge and wait forever in tool_executing.

Login Handling

The bundled script runs a preflight check:

• If http://127.0.0.1:8080 is unreachable, tell the user to start CodeBuddy with codebuddy --serve --port 8080 --session-id my-session.
• If /api/v1/auth/status says authenticated: false, do not continue. Tell the user to open http://127.0.0.1:8080/ and scan/authorize login.
• After the user reports login success, rerun the same bridge command.
• If the user wants a smoother first-run flow, run with --wait-login --open-login; still tell the user what page was opened and why.

Do not try to solve login by editing files or guessing tokens.

Defensive Handling

• Run --doctor once at the start of a new environment, after installs, or when a delegation fails unexpectedly.
• Treat missing codebuddy CLI as a setup blocker; explain the install requirement instead of continuing.
• Treat invalid --cwd as a blocker; ask for the correct project directory or use the current workspace root.
• Keep executor prompts scoped. Do not send secrets, tokens, payment details, or unrelated private data to CodeBuddy.
• Keep --base-url pointed at the user's trusted local CodeBuddy server unless they explicitly approve another endpoint.
• If CodeBuddy asks for permissions or user input, report that back to the user instead of guessing.
• If Bash or file tools appear stuck, check that the bridge is version 0.2.0 or newer and that ACP clientCapabilities remains empty.

Model Selection

If the user says "cheap model", prefer:

--model deepseek-v4-flash

If the user says "default" or does not care, omit --model and let CodeBuddy use its current default.

If CodeBuddy returns an invalid model error, rerun without --model or ask the user which model is available in their CodeBuddy UI.

Compatibility

For installation paths and non-native agent fallbacks, read references/installation-targets.md only when the user asks to install, share, or port this skill across tools.