CUGA LogoCUGA AGENT
Run

CUGA over ACP

Run CUGA from an ACP editor or delegate to a local ACP coding agent over stdio.

CUGA over Agent Client Protocol

CUGA supports both local sides of Agent Client Protocol (ACP): an editor can launch CUGA, and a CUGA supervisor can launch an ACP coding agent. Both use newline-delimited JSON-RPC over stdin/stdout without opening a port.

Install

pip install "cuga[acp]"

From a source checkout, use uv sync --extra acp. Configure the LLM connection before launching CUGA as an ACP agent.

Use CUGA from an editor

An ACP editor such as Zed can launch cuga-acp as a custom agent. Find its absolute path with command -v cuga-acp (Windows: where cuga-acp) and adapt the editor configuration:

{
  "agent_servers": {
    "CUGA": {
      "type": "custom",
      "command": "/absolute/path/to/cuga-acp",
      "args": [],
      "env": {}
    }
  }
}

Send a text prompt, then try cancelling a long-running prompt from the editor. Consult the editor's ACP logs for diagnostics. cuga-acp reserves stdout for protocol frames; wrappers must not print banners there.

Delegate to an ACP agent

Add an external agent to your supervisor YAML:

supervisor:
  description: "Delegate coding tasks to a local ACP process."

agents:
  - name: coding-agent
    description: "Local coding agent over ACP stdio."
    acp_protocol:
      enabled: true
      command: your-acp-agent
      args: ["--acp"]
      cwd: .
      env: [YOUR_API_KEY]
      startup_timeout: 15
      prompt_timeout: 120
      shutdown_grace_period: 5

Replace the command/args with those of the installed ACP agent. env is an allowlist of environment variable names, not secret values. Export the values in CUGA's environment. cwd must resolve inside the configured CUGA workspace.

Save the YAML as consumer.supervisor.yaml, export the credential variables listed in env, and load it directly through the SDK:

import asyncio
from cuga import CugaSupervisor

async def main():
    supervisor = await CugaSupervisor.from_yaml("consumer.supervisor.yaml")
    result = await supervisor.invoke("Inspect the workspace and summarize the project")
    print(result.answer)

asyncio.run(main())

Use an absolute YAML path if the script runs from another directory. cuga start demo_supervisor selects the bundled CRM/email configuration, so it is not the launch command for this custom ACP YAML. The ACP examples contain the editor settings and supervisor YAML.

Permissions and supported features

Supervisor plan approval and an ACP agent's operation permission are separate. Interactive runs pause for a CUGA tool-approval action when the ACP child requests permission. Headless runs deny the operation and clean up the child process.

CapabilityCurrent support
Text prompts and text response chunksSupported
Cancellation and bounded subprocess lifecycleSupported
Image/audio/embedded-context inputsNot supported
Advertised filesystem/terminal/ACP-over-MCP capabilitiesNot supported
Session load/resumeNot supported
Remote HTTP/WebSocket ACP transportsNot supported

Troubleshooting

ProblemAction
Agent cannot startInstall the ACP extra and use an executable path available to the editor/CUGA process.
Protocol parse errorRemove stdout logs/banners from the child and wrappers.
TimeoutCheck for interactive login first; tune startup_timeout or prompt_timeout for the relevant phase.
Stale permission resumeStart a new delegation: the original process may have exited, the permission expired, or another resume consumed it.
Missing credentialAdd its variable name to env, export its value in the parent environment, and restart.

See A2A for HTTP agent-to-agent delegation and MCP for exposing CUGA to MCP clients.