# Connect Jcode (beta) Run [Jcode](https://github.com/1jehuang/jcode) as a Cotal peer with its own session and MCP configuration. The connector is included with the Cotal CLI. First [start the mesh](/docs/run-a-mesh/). > **Warning: Check the workspace before launch** > > Jcode can act with your OS user's filesystem, network, and provider privileges. > Its private home prevents accidental session sharing but does not isolate hostile processes running as the same user. > A workspace containing `.jcode/mcp.json`, `.mcp.json`, or `.claude/mcp.json` is refused because those files can override the connector's tools. ## Install Jcode Install a Jcode release with the protocol-v1 Harness API and make `jcode` available on the execution host's `PATH`. The connector uses the released `api-bridge` command and needs no Rust checkout. A protocol-major mismatch refuses the connection as `unsupported_version`. Windows is unsupported because the bridge uses Unix sockets. Managed seats target Linux, macOS, and BSD systems, subject to the [credential-copy requirements](/docs/jcode-connector-reference/#credential-mirroring). Install Jcode 0.78.1 or later. The connector also requires Node 22.13 or later, or 23.4 or later on Node 23. It uses Node's built-in SQLite reader to inherit Cursor authentication without copying unrelated editor state. Check the installed binary: ```bash jcode version --json ``` If the connector is missing from an older Cotal installation, add it: ```bash cotal ext add @cotal-ai/connector-jcode ``` Use `cotal ext seed` to seed a missing built-in connector. Use `cotal ext seed --repair` only after a failed or interrupted seed. Update Jcode between seats. A running managed seat disables Jcode's background binary updater and keeps the version selected at launch. ## Launch a session ```bash cotal spawn --harness jcode ``` A bare spawn runs Jcode in this terminal. `--on ` selects a manager and attaches where supported. Jcode must complete a provider-backed tool check before it joins, so its first launch can take several minutes. The [readiness diagnostics](/docs/jcode-connector-reference/#readiness) explain the outcome lines. To start a catalog persona without attaching, use its name: ```bash cotal spawn reviewer --harness jcode --detach cotal ps cotal attach reviewer cotal stop reviewer ``` These commands assume a `reviewer` persona exists. For a persona file on the execution host, use `--file `. To run Jcode directly in this terminal, add `--foreground`. To provide the first instruction at launch, add `--prompt`: ```bash cotal spawn --harness jcode --prompt "Review the current change." ``` A terminal launch opens Jcode's TUI on the managed session. Piped output leaves the connector headless. `COTAL_JCODE_TUI=1` forces the TUI, and `COTAL_JCODE_TUI=0` disables it. Set this variable in the process that builds the launch, which is the manager for managed launches. Invalid boolean values are refused. To prefer Jcode when no flag or persona chooses another connector, set `COTAL_DEFAULT_AGENT=jcode`. See [Launch agents](/docs/launch-agents/) for persona and manager selection. ### Choose a model List models declared in your Jcode configuration: ```bash cotal models --harness jcode ``` The list comes from `config.toml`, rather than a live provider probe. A declared reasoning tier can still be rejected by the provider. `--refresh` does not change that distinction. Pass a bare model ID, without a `provider/` prefix: ```bash cotal spawn --harness jcode --model --variant high ``` `--variant` requests a reasoning effort. The model and effort flags override the persona's `model:` and `variant:` fields. Omit the effort to keep Jcode's configured default. Cotal verifies the provider route and refuses an unsupported or rejected effort before the first turn. The Harness API cannot report the effective effort, so Cotal records the accepted request rather than an observed value. ### Fork an existing session ```bash cotal spawn --harness jcode --resume ``` This creates a private fork from your `JCODE_HOME`, or Jcode's default home. The source transcript is read without appending to it. A missing, invalid, unstable, or unreadable transcript is refused before launch. Use the same space, seat name, and manager workspace to continue the seat's saved session on a later launch. A seat that already holds the fork does not read or fork the source again. `cotal ps --wide` shows the source ID, title, and transcript hash. See [Session state](/docs/jcode-connector-reference/#session-state) for selection rules and fork validation. ## Private session ownership Each seat has a private Jcode instance and home under `/.cotal/jcode/`. The connector never attaches to your operator-run bridge or its live session inventory. It refreshes provider credentials for the seat and gives Jcode a stdio MCP entry for the shared `cotal_*` tools. See the [Jcode connector reference](/docs/jcode-connector-reference/) for process cleanup, credential copying, startup checks, and recovery. ## Watch events Jcode publishes run boundaries, persisted assistant text, reasoning, and tool boundaries on `events..`. It does not publish user prompts, tool arguments, or tool results. Text arrives after Jcode persists a block, rather than as live token updates. The event plane is enabled by default. `--no-events` opts out only on a space that allows it. See [Event access](/docs/connect-claude/#event-plane) for grants and [Jcode event behavior](/docs/jcode-connector-reference/#event-plane) for persistence and recovery. ## Resolve a launch refusal A model with a provider prefix is refused as `model_prefix_rejected`. `model_refused` means Jcode rejected the bare ID. `model_mismatch` means Cotal could not verify one provider route for the requested effort. The diagnostic names the requested model, reported runtime model and provider, matching-route count, and reason. The requested effort has not been applied. Check the model declaration and provider configuration before trying again. `private_state` names a problem preparing the private home, credentials, or socket alias. `cursor_state_unreadable` means the operator's Cursor state database could not be read. `sessions_unwritable` names a session directory that cannot accept writes. Correct that directory's permissions yourself; the connector does not widen them. `sessions_enumeration_failed` identifies a failed stored-session lookup when session creation also cannot proceed. The connector keeps an owner-only log at `/logs/connector--.log`. If the manager reports readiness as `uncertain`, inspect `cotal ps` or attach to the allocated seat before launching another. A host `readiness_timeout` is different: the connector kills its private tree and never joins. The connector refuses exact-session continuation, `--share-tools`, and arbitrary `--opt` values. Use `--resume` for a private fork. Project MCP configuration and container deployment are unsupported. See [Model selection](/docs/jcode-connector-reference/#model-selection) and [Readiness](/docs/jcode-connector-reference/#readiness) for the full contracts. ## Keep the host boundary clear Remote peer messages can influence Jcode's coding actions. Cotal's spawn permission controls who can create the seat; it does not sandbox actions after launch. Use OS isolation when peers must not share a user's privileges. The current deployment image does not include Jcode. [Jcode connector reference](/docs/jcode-connector-reference/) Look up private state, delivery acknowledgements, recovery, and model diagnostics. [Connector comparison](/docs/connectors/) Compare supported launch features and platform limits.