CLI Bridge

Overview

The cli_bridge tool enables Superagent to offload tasks to external AI CLI assistants (such as Antigravity/AGY, Claude Code, OpenAI Codex, or any custom executable) in two execution modes:

1. One-Shot Task Delegation (action: "delegate") [RECOMMENDED]:

   • Executes the external CLI in print mode (-p / --print), passes the prompt, sends EOF on stdin, auto-handles --dangerously-skip-permissions, streams output in real-time, waits for execution to complete, and returns the full output.
   • Best for: Autonomous coding, file reading/editing, code analysis, bug fixing, test running, building, and script generation.

2. Interactive Subprocess Sessions (action: "session.*"):

   • Spawns the CLI as a long-lived subprocess with stdio streaming, event buffering, automatic prompt detection, and multi-turn message exchange.
   • Best for: Interactive human-in-the-loop dialogs, step-by-step interactive sessions, or when responding to TUI choice menus via session.respond.

---

Quick Action Reference

Action	Purpose	Key Parameters
list	Discover installed CLI binaries on system PATH	None
profile.list	List built-in and user-configured CLI profiles	None
delegate	Execute a one-shot prompt against a CLI tool (auto-skips permissions, streams real-time output)	cli, prompt, cwd, skills, timeoutMs, system, args
session.create	Start an interactive subprocess session	cli, sessionId, message / initialMessage, skills, autoDetect, cwd, idleTimeoutMs, maxBufferLines
session.send	Send a new prompt to an existing session	sessionId, prompt / message, timeoutMs
session.respond	Answer an interactive prompt (yes/no, choices)	sessionId, answer
session.tail	Read recent live events or extend session idle TTL	sessionId, since, tailLimit, setIdleTimeoutMs
session.get	Retrieve session status and recent stdout/stderr	sessionId
session.list	List all active and detached sessions	None
session.export	Export session history and output log as markdown	sessionId
session.config	Read or modify session configuration parameters	sessionId
session.resume	Resume session using profile-specific resume flags	cli, sessionId, conversationId
session.detach	Detach session from active management	sessionId
session.kill	Terminate session subprocess and free resources	sessionId

---

Core Usage Patterns

1. Discover Available CLIs

Before delegating, check which CLI assistants are installed:

{
  "action": "list"
}

Returns detected binaries, version info, and path availability for agy, claude, codex, etc.

---

2. Autonomous Task Delegation (delegate) [PRIMARY PATTERN]

Use action: "delegate" for all standalone coding, research, refactoring, and test execution tasks.

Example: Delegating code analysis & rewrite with multiple reference directories attached:

{
  "action": "delegate",
  "cli": "agy",
  "prompt": "Read G:\\project\\qwen\\_ref\\llama_cpp_ref\\models\\qwen35.cpp and rewrite the inference engine in G:\\project\\rudy-lang\\src\\gguf.c to match the Qwen3.5 GDN architecture.",
  "cwd": "G:\\project\\qwen",
  "skills": [
    "G:\\project\\qwen\\_ref\\llama_cpp_ref\\models",
    "G:\\project\\qwen\\_ref",
    "G:\\project\\rudy-lang\\src"
  ],
  "timeoutMs": 600000
}

Why delegate is preferred for coding tasks:

• Headless execution automatically passes --dangerously-skip-permissions, preventing tool execution blocks.
• The process receives the full prompt and begins execution immediately without waiting for stdin EOF.
• Real-time streaming output is captured and displayed in the terminal UI.

---

3. Multi-Turn Interactive Sessions (session.*)

Use session.create when you specifically require persistent multi-turn conversations with step-by-step confirmation.

Step 1: Create Session with Initial Prompt

{
  "action": "session.create",
  "cli": "claude",
  "sessionId": "refactor-auth-service",
  "initialMessage": "Analyze src/auth/jwt.ts and list potential token expiration bugs.",
  "skills": ["src/auth"],
  "idleTimeoutMs": 1800000
}

Step 2: Send Follow-up

{
  "action": "session.send",
  "sessionId": "refactor-auth-service",
  "prompt": "Proceed with refactoring the refresh token rotation logic."
}

Step 3: Respond to Interactive Prompts

If the CLI asks for confirmation:

{
  "action": "session.respond",
  "sessionId": "refactor-auth-service",
  "answer": "y"
}

Step 4: Clean Up Session

Always kill sessions when done to free system resources:

{
  "action": "session.kill",
  "sessionId": "refactor-auth-service"
}

---

4. Artifact Path Injection & Task Synchronization (v1.5.40)

By default (injectArtifacts: true), CLI Bridge automatically resolves active project artifacts and injects their absolute paths and update instructions into the prompt sent to the external CLI:

• Task Checklist: _task.md or task.md
• Implementation Plan: _plan.md, plan.md, or _implementation_plan.md
• Walkthrough Document: _walkthrough.md or walkthrough.md

This enables the external CLI to:

1. Inspect the implementation plan before making modifications.
2. Update checklist tasks in real-time (- [ ] to - [/] for in-progress, - [x] for completed).
3. Document verification command outputs in the walkthrough document.

Example delegating with custom artifact path:

{
  "action": "delegate",
  "cli": "agy",
  "prompt": "Implement the auth token rotation feature according to the plan.",
  "injectArtifacts": true,
  "taskPath": "tasks/auth_tasks.md"
}

To disable automatic artifact context injection for simple queries:

{
  "action": "delegate",
  "cli": "claude",
  "prompt": "Quick explanation of this regex pattern.",
  "injectArtifacts": false
}

---

Critical Rules & Invariants

1. Always Prefer delegate for Autonomous Coding: When delegating codebase modifications, builds, test execution, or file generation, ALWAYS use action: "delegate".
2. Attach Reference Directories via skills: Pass an array of directory paths in skills: [...] to attach context (automatically converted to --add-dir for AGY/Claude Code).
3. Always Clean Up Multi-Turn Sessions: When using session.create, always call session.kill once work is complete to release subprocesses and memory.
4. Appropriate Timeouts: Set timeoutMs (e.g. 300000 to 600000 ms) for long-running compilation or multi-file edits.