Install

On macOS and Linux, the install script downloads the latest release and puts jcode on your PATH.

curl -fsSL https://jcode.sh/install | bash

Windows 11, PowerShell 5.1 or newer:

irm https://jcode.sh/install.ps1 | iex

Homebrew on macOS:

brew tap 1jehuang/jcode
brew install jcode

From source:

git clone https://github.com/1jehuang/jcode.git
cd jcode
cargo build --release
scripts/install_release.sh

On Termux, run pkg install glibc patchelf before the install script.

Uninstall

Removes the binaries and keeps config, auth, and sessions, so a reinstall picks up where you left off.

curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/uninstall.sh | bash -s -- --yes

Add --purge to also delete config, auth, sessions, logs, and memory, or --dry-run to preview.

First run

Launch jcode in a terminal. On first use, jcode login lists every available login flow.

# Launch the TUI
jcode

# Run a single prompt non-interactively
jcode run "say hello"

# Resume a previous session by memorable name
jcode --resume fox

# Run a persistent background server, then attach clients
jcode serve
jcode connect

Project instructions live in AGENTS.md at the repo root, machine-wide instructions in ~/AGENTS.md. Both load into every session in that scope.

Providers and login

Subscription OAuth and direct API providers both work. Built-in login flows:

jcode login --provider claude     # Claude subscription
jcode login --provider openai     # OpenAI / ChatGPT / Codex
jcode login --provider gemini     # Google Gemini
jcode login --provider copilot    # GitHub Copilot
jcode login --provider azure      # Azure OpenAI
jcode login --provider ollama     # local Ollama server
jcode login --provider lmstudio   # local LM Studio server

Named profiles cover popular OpenAI-compatible services, including openrouter, deepseek, moonshotai, huggingface, and nebius. Pick the model with /model or --model.

Any OpenAI-compatible endpoint

jcode provider add writes a named profile to ~/.jcode/config.toml without putting the key in shell history.

printf '%s' "$MY_API_KEY" | jcode provider add my-api \
  --base-url https://llm.example.com/v1 \
  --model my-model-id \
  --api-key-stdin \
  --set-default

# Smoke test, then use it
jcode --provider-profile my-api auth-test
jcode --provider-profile my-api run 'hello'

Local servers without auth: pass --no-api-key and a localhost base URL.

Headless and remote logins

jcode login --provider <provider> --no-browser prints the auth URL instead of opening a browser. The claude, openai, gemini, and copilot flows also support --print-auth-url now and --callback-url or --auth-code later.

Verify everything configured with jcode auth-test --all-configured. In the TUI, /account switches between accounts on one provider.

Configuration

Config lives at ~/.jcode/config.toml, or $JCODE_HOME/config.toml.

[provider]
default_provider = "openai"

[display]
centered = true

[keybindings]
side_panel_toggle = "alt+m"
new_terminal = "alt+enter"

[features]
memory = true
swarm = true

Other files jcode reads

MCP servers

MCP config is separate from config.toml: ~/.jcode/mcp.json for global servers, .jcode/mcp.json for project-local ones. jcode also reads Claude Code's ~/.claude.json and .mcp.json, and imports Claude Code and Codex servers on first run.

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-server",
      "args": ["--root", "/workspace"],
      "env": {}
    }
  }
}

Only stdio servers are supported today. HTTP and SSE entries are recognized and skipped. Tools are advertised the moment a session starts, from an on-disk schema cache, so a slow handshake never blocks startup or invalidates the prompt cache.

Skills

Skills are markdown instruction packs, one directory per skill with a SKILL.md, under ~/.jcode/skills/. Claude Code plugin skills load unchanged.

Skills are not all loaded on startup. The conversation is embedded as a vector, and a skill is injected when the conversation matches it, the same mechanism memory recall uses. Activate one directly with its slash command, /skillname, or ask the agent to load it. /skills shows what is loaded.

SSH

The simplest setup: run jcode inside an SSH session, under tmux or zellij so it survives disconnects.

ssh mybox
tmux new -A -s jcode
jcode

If the connection drops mid-turn, the daemon keeps working and jcode --resume picks the session back up.

Local client, remote server

Run a persistent server remotely and forward its Unix socket over SSH.

# on the remote machine
jcode serve --server-name mybox

# on your laptop: forward the remote socket to a local path
ssh -N -L /tmp/jcode-mybox.sock:/run/user/1000/jcode.sock mybox &

# connect the local client to it
jcode --socket /tmp/jcode-mybox.sock

The socket lives in the server's runtime directory, typically $XDG_RUNTIME_DIR/jcode.sock. Point the session at the remote checkout explicitly:

jcode --socket /tmp/jcode-mybox.sock -C /local/checkout --remote-working-dir /remote/checkout

-C must exist locally. --remote-working-dir must be an absolute path on the server, where every tool, git operation, and edit runs.

Phone and web clients

The daemon can expose a WebSocket gateway for paired thin clients over Tailscale or LAN. It is off by default.

[gateway]
enabled = true   # listens on port 7643

jcode pair            # prints a 6-digit code and QR (5 minute TTL)
jcode pair --list     # show paired devices
jcode pair --revoke <device>

Paired clients speak the same protocol as the TUI: streaming, tool cards, interrupts, session switching, and model picking. Tokens are stored hashed.

Scripted automation

The TypeScript SDK launches a private jcode or attaches to a running one through jcode api-bridge. With socket forwarding, that includes a remote daemon.

Slash commands

Type / in the TUI for fuzzy-matched suggestions. /help lists everything for your installed version.

Every command, grouped by task

Keybindings

Defaults on Windows and Linux, with macOS differences. Everything except Enter and Shift+Enter is configurable under [keybindings]. Set a binding to "" to disable it.

macOS terminals encode some chords differently, so jcode keeps per-platform defaults and accepts the characters Option inserts.

Config keys and troubleshooting