OpenCode Agent Client

Give a coding agent access to an existing OpenCode server through MCP or a JSON command-line interface. Discover projects, models and sessions; delegate work; inspect progress, tool results and diffs; answer authorized permission requests; and interrupt or redirect a task.

The same client works with Codex, Claude Code and other hosts that support local MCP servers. It does not start an OpenCode server or install model providers.

Quick start

Requires Node.js 22 or later and an accessible OpenCode server implementing the documented HTTP API. The client detects the documented v1 API or the v2 API used by OpenCode 2.2.0. Both share the same MCP tools; pagination and question replies differ as described in usage.

Before connecting, the user must run opencode serve manually (or confirm an existing server), provide the actual server URL, and supply the server password securely through OPENCODE_SERVER_PASSWORD or the host's secret mechanism. An installing agent must ask for these steps and wait for them; it must not start the server or assume it is unauthenticated. See user-run server and password setup. The password must reach the host-launched MCP process; a separate terminal export does not update an already-running app.

Once those steps are complete, clone this repository into a persistent directory, then:

git clone https://github.com/theapurvapawar/opencode-client.git
cd opencode-client
npm ci
node bin/opencode-client.js doctor --url http://127.0.0.1:4096
node bin/opencode-client.js call projects --url http://127.0.0.1:4096
node bin/opencode-client.js call models '{"connectedOnly":true}'
node bin/opencode-client.js call sessions '{"allProjects":true}'

The default URL is http://127.0.0.1:4096. Set OPENCODE_URL or supply --url for a different host, port or API prefix. A web UI URL is not necessarily an API URL: doctor requires a JSON health response and reports HTML responses as a configuration error.

Install once across projects for your user account:

# Preview the app-wide configuration and skill.
node bin/opencode-client.js install --agent codex --scope user --url http://127.0.0.1:4096
# Apply the reviewed installation.
node bin/opencode-client.js install --agent codex --scope user --url http://127.0.0.1:4096 --apply

Use --agent claude for Claude Code. For project scope, use --scope project --target /path/to/project instead of --scope user; scope must always be supplied explicitly. Reload the host and trust the project/MCP server when requested. The installer records absolute executable paths, so keep this checkout and Node installation in place. No build step is required.

User scope registers both MCP and the skill in the host's user locations. Codex uses ~/.codex/config.toml plus ~/.agents/skills; Claude Code uses ~/.claude.json plus ~/.claude/skills. Existing project entries can override user settings; migration instructions explain how to remove duplicates safely. “App-wide” applies to the current account, not other users or cloud machines.

Related MCP server: opencode-mcp

Agent integrations

The paths in the table are for project scope. Codex, Claude Code, Cursor, Gemini and OpenCode also resolve native user paths with --scope user; VS Code and other profile-dependent hosts use an explicit absolute --config path. Adapters generate the hosts' documented formats. Automated protocol/configuration tests do not establish that every host/version has been tested interactively. See installation for setup, credentials, upgrades and agent-driven installation.

Delegation workflow

Ask your host agent:

Inspect the available OpenCode projects, connected models and running sessions. Delegate a review of the selected project, keep it read-only, and return the findings with the session ID. Supervise any permission requests rather than approving them automatically.

The agent should discover a server-side directory, choose a model, delegate a bounded task, save the returned IDs, then use wait and inspect. A task being accepted is not evidence that it completed. A connected model is not a guarantee of available credits or provider access.

redirect aborts the current execution and sends a new prompt. It does not roll back edits or provide token-level steering. The server retains the session history; this client keeps no separate task database.

Tools

Discovery: health, projects, models, agents, sessions, status.

Supervision: inspect, messages, wait, permissions, questions.

Actions: delegate, send, abort, redirect, permission_reply, question_reply, question_reject.

MCP names have the opencode_ prefix. The CLI accepts either name form. Run node bin/opencode-client.js tools for exact input schemas, or see usage examples.

Development and contributing

npm ci
npm test
npm run check

Tests use temporary files and local HTTP fixtures; they do not require a paid model or mutate your existing sessions. See validation coverage, architecture, contributing and security. This project is MIT licensed and is not affiliated with OpenCode, Anthropic or OpenAI.