Chat with Claude Code or Codex
Connect a local coding agent to Busabase, choose its model, and run the first chat safely.
Use this flow when you want to open Agents in Busabase and chat with Claude Code or Codex from the Busabase interface. Busabase acts as the ACP client and starts the coding agent on the same machine.
This is a local-agent connection
Claude Code and Codex run on the computer hosting Busabase Desktop or the open-source Busabase server. Busabase Cloud cannot start a program on your computer directly. To let a Cloud workspace use a local agent, connect your machine with the Local↔Cloud Tunnel first.
This is the opposite direction from Bring Your Own Agent, where an agent calls Busabase through a skill, API, or MCP server.
Before you begin
- Install a current Node.js release and confirm
npx --versionworks in your terminal. - Install and authenticate the coding agent you plan to use.
- Use the agent's persistent login for a normally launched Desktop app. For an environment-only custom gateway, run the open-source Busabase server from a dedicated terminal instead.
For the standard hosted providers, verify the CLI first:
claude --version
claude auth status
codex --version
codex login statusConfigure the model provider
If Claude Code already works in the terminal, no additional Busabase setting is required. For an Anthropic-compatible gateway, export its variables before starting Busabase:
export ANTHROPIC_BASE_URL="https://your-anthropic-compatible.example/v1"
export ANTHROPIC_AUTH_TOKEN="your-token"For Codex, put durable provider settings in the user-level ~/.codex/config.toml. model_provider names the provider table; model is the exact model ID that provider accepts.
model = "gpt-5.6"
model_provider = "OpenAI1"
[model_providers.OpenAI1]
name = "OpenAI1"
base_url = "https://your-openai-compatible.example/v1"
env_key = "CUSTOM_OPENAI_API_KEY"
wire_api = "responses"Export the named key in the shell that will start Busabase:
export CUSTOM_OPENAI_API_KEY="your-token"Keep credentials in environment variables or the agent's own login store. Do not put tokens in repository files, screenshots, or WebSocket URLs.
Use a dedicated shell for custom providers
The local ACP adapter inherits the Busabase server process environment, not only the provider variables shown above. Do not start Busabase from a deployment or administration shell that contains unrelated GitHub, cloud, database, or production secrets. A GUI-launched Desktop app also does not reliably inherit variables exported in a terminal; use the shell-launched server for environment-only provider setups.
Start Busabase
If Claude Code or Codex uses its persistent login store, open Busabase Desktop normally. If you exported custom-provider variables above, start the open-source server from that same dedicated terminal:
npx busabase serverWhen working from this repository instead, run:
pnpm --filter busabase devKeep the server and its terminal open. The pinned ACP adapter runs as a child of Busabase and inherits that process environment.
Connect Claude Code or Codex
- Open Dashboard → Agents.
- Select Add agent.
- Find Claude Code or Codex CLI and select Connect.
- Wait for the new chat to show
idle.
The first connection can take longer because npx downloads the pinned ACP adapter. Busabase owns this launch command; you do not need to paste an ACP WebSocket URL or run acpremote mirror.
Choose a model before the first prompt
If the agent advertises model choices through ACP, a Model menu appears beside the attachment button. Select a model and wait until the chosen name remains visible. Busabase confirms the change with the agent before it enables prompt submission.
An agent that does not advertise a model option has no model menu. Busabase does not invent a second model catalog.
Send the first message
Type a message and submit it. Your message should appear immediately, the status should change while the agent works, and the reply should render in the same conversation. When the turn completes, the status returns to idle and the selected model remains unchanged.
If the agent asks to run a command or edit a file, Busabase shows a permission card. Review the requested action and choose one of the options shown by the agent.
Troubleshooting
The card says npx was not found
Install Node.js on the machine running Busabase, restart Busabase, and return to Agents → Add agent.
Local agents are unavailable in Busabase Cloud
Cloud cannot spawn Claude Code or Codex on shared infrastructure. Use Busabase Desktop, run the open-source server locally, or connect your machine through the Local↔Cloud Tunnel.
The agent exits during connection
Run claude auth status or codex login status in the same account and shell environment. If you use a custom provider, confirm its key is exported before Busabase starts, then restart Busabase.
The model menu is missing
The connected ACP adapter did not advertise a model configuration option. Update the agent and Busabase, reconnect, and check again. You can still send a prompt using the agent's configured default model.