# Local Claude runtime bridge

A small, unofficial stdio MCP server built on the Claude Agent SDK. It starts local sessions, streams progress, returns results, resumes follow-ups and cancels active work. It has no built-in roles, UI, scheduler or task catalog.

The caller provides the task, working directory, exact model ID and instructions. Optional **external presets** keep reusable instructions outside this repository. Only preset IDs and their descriptions appear in tool discovery; instructions are resolved locally once and stored with the session. Follow-ups retain that snapshot, avoiding repeated prompts or another routing agent.

## Requirements and authentication

- Node.js 24 or later, npm, and an official Claude Code executable on `PATH`.
- Existing authentication configured through the official runtime. This project does not log users in, read credential files, manufacture tokens or store credentials.
- Access to the exact model ID you request. There is no fallback model; a different reported model or session ID fails the job.

Claude Code itself supports Pro/Max subscription sign-in, Console access and supported cloud providers. Subscription access is local to the signed-in user's official runtime and remains subject to account eligibility and limits. This repository does **not** offer subscription sign-in, pooled access or a hosted subscription-backed service. Anthropic states that third-party developers may not offer claude.ai login or rate limits in their products without prior approval; product integrations should use the documented API/provider authentication methods. A successful local invocation is not authorization to redistribute subscription access. See [Claude Code authentication](https://code.claude.com/docs/en/authentication) and [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview).

Set `CLAUDE_CODE_BRIDGE_EXECUTABLE` to an absolute official executable path if it is not on `PATH`. Authentication and provider environment variables already supplied to the process are inherited, never copied into the repository or bridge state. Do not place credentials in tasks, instructions or tool inputs: normal session output and approval blockers can contain the text you supply.

## Build and local MCP setup

```sh
npm ci --ignore-scripts --no-audit --no-fund
npm run check
```

Start the server with `node /absolute/path/claude-code-bridge/dist/src/server.js`. It uses stdout exclusively for MCP; diagnostics go to stderr. Node may print an experimental SQLite warning on some supported releases.

For Codex, back up your configuration, then register:

```sh
codex mcp add claude_code_bridge -- node /absolute/path/claude-code-bridge/dist/src/server.js
```

Equivalent TOML:

```toml
[mcp_servers.claude_code_bridge]
command = "node"
args = ["/absolute/path/claude-code-bridge/dist/src/server.js"]
```

Use an absolute script path and a `PATH` that includes Node and the official runtime. Open a fresh client thread after changing configuration. No restart of the application is required by this project.

## Tools

| Tool | Input | Behavior |
| --- | --- | --- |
| `start` | `task`, absolute `cwd`, plus `model` + `instructions` or `preset`; optional `effort`, `synthetic` | Starts a detached worker and returns its durable job ID. |
| `progress` | `jobId` | Reads status, recent text, final result, model evidence or an approval blocker. |
| `followup` | `jobId`, `task` | Resumes the saved session with the same directory, model and instructions. |
| `cancel` | `jobId` | Requests interruption of the active generation. Confirm `cancelled` with `progress`. |

Inline example, using an exact model ID available to your account:

```json
{
  "task": "Remember the imaginary project Lumen and color amber. Answer in one sentence.",
  "cwd": "/absolute/path/to/synthetic-workspace",
  "model": "claude-opus-5-5",
  "instructions": "Work only from supplied text. Do not use tools or delegate.",
  "effort": "low",
  "synthetic": true
}
```

Tasks and instructions are limited to 100,000 characters each. Supply canonical model IDs rather than aliases. Progress retains the latest 16,000 characters; final results are kept in full. Terminal statuses are `completed`, `failed`, `cancelled`, `interrupted` and `approval_required`. Cancellation is asynchronous. Wait for acknowledgement before assigning overlapping edits. MCP disconnection does not cancel a worker.

## Optional local presets

Keep a JSON file outside the source tree, for example:

```json
{
  "concise": {
    "description": "Summarize supplied text when a compact answer is needed.",
    "model": "claude-opus-5-5",
    "instructions": "Summarize the supplied text in three bullets. Follow the requested scope.",
    "effort": "low"
  }
}
```

Configure the process:

```toml
[mcp_servers.claude_code_bridge.env]
CLAUDE_CODE_BRIDGE_PRESETS = "/absolute/path/to/local-presets.json"
# Optional subset of the file; arbitrary IDs, no built-in semantics:
CLAUDE_CODE_BRIDGE_PRESET_IDS = "concise"
```

Then call `start` with only `task`, `cwd`, `preset: "concise"` and optional `synthetic`. Preset configuration cannot be overridden in that call; use an inline task for a different configuration. At most 32 presets are exposed. Invalid selected presets fail startup. Presets are loaded at server startup; open a new connection after edits. Other configuration consumers may use the same external source file and select their own subset. This bridge does not generate or manage native client agents.

## Permissions, privacy and state

Normal execution loads existing user/project/local Claude settings and uses `permissionMode: "default"`. This project does not grant permissions, use bypass mode, enable auto-edit approvals or rewrite security settings. If the runtime requests permission, the callback denies that request, interrupts the job and reports `approval_required` with the tool/action. Obtain approval through the official runtime's supported flow before resuming. There is no approval tool in this bridge.

This is a **trusted local execution tool**, not a sandbox or a hosted multi-tenant service. Claude can use tools already permitted by its own runtime settings. The MCP client's shell sandbox is not an additional sandbox around Claude's worker. Do not expose the server to untrusted clients; instructions and directory selection must be authorized by the operator. Inputs and outputs can be sensitive.

Bridge state is one SQLite table at `~/.local/state/claude-code-bridge/bridge.sqlite`. Override its absolute directory with `CLAUDE_CODE_BRIDGE_STATE_DIR`. Keep it outside repositories; it contains instruction snapshots, results and requested approval actions. New state directories/files use owner-only permissions on POSIX. Official Claude transcripts remain in the runtime's own storage. No state or transcript belongs in a public source tree.

SQLite transactions serialize follow-ups and prevent old generations from overwriting newer ones. A missing worker with an expired heartbeat is resumable as `interrupted`. A process that remains alive is conservatively considered active. If a worker has exited unexpectedly, wait at least 30 seconds before trying to resume. Cancel never signals a stored PID; the active worker acknowledges the request and interrupts its own runtime.

## Tests and limitations

`npm run check` runs lint, strict type checking, build and credential-free unit/MCP tests. CI runs these on Linux with Node 24. Tests cover external preset validation, atomic generation changes, overlapping follow-ups, durable results, cancellation, startup failures, model/session mismatches, bounded streaming and fail-closed permission handling through mocks. They do not need an account or send real tasks to Claude.

`npm run smoke -- /absolute/path/to/output-directory MODEL_ID` runs a bounded, opt-in real-runtime test. It sends synthetic text only, disables tools/external MCP, and checks start, fresh-connection follow-up, cancellation and resume. It consumes your existing account usage and saves evidence outside the repository. It does not log in or grant permissions.

Local macOS runtime testing and Linux credential-free CI do not prove production edits, visual validation, Windows support or every authentication provider. Ancillary runtime requests may use other models even when the main session uses the requested model. No browser UI or public hosting is included.

## Maintenance and rollback

Keep dependencies locked and rerun `npm run check` after changes. Preserve state and external preset files during upgrades. Existing jobs retain their instruction/model snapshots, so changing presets affects new jobs only.

For rollback, cancel and wait for active work, remove only the MCP entry you added, and restore your backed-up client configuration if no later edits would be lost. Switch its script path back to a retained known-good build if needed. Remove source/build files only after workers stop; keep the state directory and official transcripts unless you deliberately intend to remove that history.

Licensed under [MIT](LICENSE). Dependency licenses and Anthropic's applicable terms remain their own; this license does not grant access to any model or subscription service.