Connect Jcode (beta)

Guide (informative) · For: operators · Prereqs: Quickstart

Jcode joins a Cotal mesh as a lateral peer. The connector creates one private Jcode Harness API instance per seat, one Jcode session inside it, and exposes the normal cotal_* tool surface through Jcode’s documented stdio MCP configuration.

Beta means the supported path is deliberately narrow: a fresh private session, prompt injection, presence, managed start/stop, and an attached TUI work. Features that do not preserve that private session’s mesh surface fail loud: --resume, exact-session continuation, --variant, --share-tools, --events, and connector --opt values are not supported.

Install

The connector is seeded with the Cotal CLI. It currently supports macOS and Linux only: Jcode’s released Harness API bridge is a Unix-socket surface. Install Jcode 0.78.1 or later from its GitHub release and make the binary available as jcode on PATH:

jcode version --json
cotal spawn --agent jcode

If an older Cotal installation is missing the connector, run cotal ext seed --repair (or cotal ext add @cotal-ai/connector-jcode). This connector intentionally uses the released binary’s api-bridge command; it does not require a Rust checkout.

Spawn it

cotal spawn --agent jcode
cotal spawn reviewer --agent jcode -d
cotal spawn --agent jcode --model gpt-5.6-sol --prompt "Review the current change."
COTAL_DEFAULT_AGENT=jcode cotal spawn

A detached seat is managed normally: cotal ps, cotal attach, and cotal stop control the same process the connector starts. In a terminal, Jcode opens on the managed session. With piped output it stays headless; set COTAL_JCODE_TUI=1 or COTAL_JCODE_TUI=0 in the environment of the process building the launch to override that choice. For a detached spawn, that is the manager’s environment.

How it binds

Jcode’s stable integration surface is the Harness API: protocol-v1 NDJSON over a Unix socket. The connector uses @1jehuang/jcode-sdk’s launch() API, not connect():

• launch() starts a private JCODE_HOME, runtime directory, daemon, and api-bridge; closing the Cotal seat closes that instance. This gives each managed Cotal peer one owned session and prevents it from seeing or changing the operator’s live Jcode sessions.
• connect() attaches to an operator-run jcode api-bridge and shares the operator’s live session inventory. That is appropriate for a dashboard or editor integration, but not a managed Cotal seat: stop, prompt injection, and session selection could act on the operator’s work. The connector therefore does not use it.

The private Jcode home lives under <manager-workspace>/.cotal/jcode/. It is unique per space/name and is owner-only. Jcode’s own credential inheritance is used for the private instance, so provider logins work without copying its transcript/config tree into the seat. The spawned Jcode process does not inherit COTAL_* values or the Cotal launch-material pointer.

Jcode currently supports stdio MCP servers. The connector writes only its own cotal entry to the private JCODE_HOME/mcp.json; it starts a stdio MCP bridge for that entry and relays its calls to the host’s one MeshAgent. The Jcode/MCP child receives a per-launch relay capability, but not the Cotal broker credential or its launch-material pointer. Jcode also overlays project .jcode/mcp.json, .mcp.json, and .claude/mcp.json; a managed launch refuses a workspace containing any of those files, because one could replace the cotal bridge or add tools that were not explicitly shared. Operator MCP configuration is isolated in the private home and project MCP configuration is not supported yet.

Before the seat joins the mesh, the host runs a mandatory Jcode turn that calls cotal_orientation. Jcode loads MCP tools asynchronously; this readiness turn makes a bridge that never came up a launch failure, rather than an agent that is present but mute. An inbound peer message then wakes a Harness API turn. The host marks presence working while the turn runs, acknowledges exactly the delivered inbox ids only after the SDK turn succeeds, and leaves a failed turn unacknowledged for mesh redelivery. Jcode’s stable Harness API has no measured mid-turn steer surface here, so traffic arriving during a turn waits for the next turn rather than being silently treated as an interrupt.

Models and limits

--model is passed to Jcode’s session-level Harness API model selector. Jcode validates the model against the active provider, then the connector reads runtime identity back and refuses startup if it is not the requested model; a seat is never allowed to join under a model label it did not receive. The connector does not currently offer a Cotal model catalog because the Harness API’s listModels() is session-scoped and provider-specific.

The following fail loud before a new session is provisioned where the manager can preflight them, or at connector launch as a backstop:

• Resume / continuation: a Cotal seat owns a new private Jcode instance. Reusing a session from an operator or another seat would violate that ownership boundary.
• Variants: Jcode reasoning effort is an API operation but has no Cotal variant mapping yet.
• Tool sharing: Jcode resolves its MCP configuration from several global and project sources. The connector owns a private configuration containing only cotal, rather than claim a chosen subset can be safely merged.
• Events: Jcode’s Harness API does not provide the durable structured rollout surface required by Cotal’s event plane.
• Launch options: the connector does not map arbitrary flags/config into the Harness API.
• Containers: the current deploy image does not bundle Jcode, so there is no containerized Jcode connector today.

Security limits

The private home protects against accidental sharing and stale session selection; it is not an OS-user isolation boundary. A hostile process running as the same user can still read that user’s files or inspect another same-user process. Use OS/container isolation where peers must be mutually hostile.

The model can receive remote peer messages and Jcode is an autonomous coding harness. Treat its provider credentials, filesystem access, and network capability as the privileges of the OS user running the seat. Cotal’s spawn capability governs who may create a seat; it is not a sandbox for what a model can be persuaded to do after creation.