Connect Jcode (beta)

Run Jcode as a Cotal peer with its own session and MCP configuration. The connector is included with the Cotal CLI. First start the mesh.

Install JcodeCopy Anchor Link

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.

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:

jcode version --json

If the connector is missing from an older Cotal installation, add it:

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 sessionCopy Anchor Link

cotal spawn --harness jcode

A bare spawn runs Jcode in this terminal. --on <instance> 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 explain the outcome lines.

To start a catalog persona without attaching, use its name:

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 <persona-file>. To run Jcode directly in this terminal, add --foreground.

To provide the first instruction at launch, add --prompt:

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 for persona and manager selection.

Choose a modelCopy Anchor Link

List models declared in your Jcode configuration:

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:

cotal spawn --harness jcode --model <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 sessionCopy Anchor Link

cotal spawn --harness jcode --resume <session-id>

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 for selection rules and fork validation.

Private session ownershipCopy Anchor Link

Each seat has a private Jcode instance and home under <manager-workspace>/.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 for process cleanup, credential copying, startup checks, and recovery.

Watch eventsCopy Anchor Link

Jcode publishes run boundaries, persisted assistant text, reasoning, and tool boundaries on events.<owner>.<actor>. 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 for grants and Jcode event behavior for persistence and recovery.

Resolve a launch refusalCopy Anchor Link

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 <private-home>/logs/connector-<timestamp>-<pid>.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 and Readiness for the full contracts.

Keep the host boundary clearCopy Anchor Link

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.