1jehuang/jcode

---

# macOS & Linux
curl -fsSL https://jcode.sh/install | bash

# Windows 11 (PowerShell 5.1+)
irm https://jcode.sh/install.ps1 | iex

Need Homebrew, source builds, provider setup, or want an agent to set it up for you? Jump to detailed installation.

Updating

Run /update in the TUI to download the latest stable release in the background and reload with your session preserved. From a terminal, use jcode update, then restart the client. Both commands use the same update policy, including for dev builds.

Older or equal release versions are skipped. For a development build, Jcode also compares the running binary's Git commit with the release tag. Builds ahead of, identical to, or diverged from the release are preserved. If ancestry cannot be verified locally or through GitHub, the update stops rather than risking a downgrade. The displayed dev patch includes a commit-count offset, so it is not used as a release version comparison.

This is the default features.update_channel = "stable" behavior. An explicit "main" channel still opts into source-branch updates. Use /rebuild or the self-dev build workflow to rebuild your own checkout.

---

jcode is built to be as performant and resource efficient as possible. Every metric is optimized to the bone, which is important for scaling multi-session workflows. Here we sample a few metrics to show the difference: RAM usage and boot up.

RAM comparison

Time to first frame

Measured on this Linux machine across 10 interactive PTY launches.

Time to first input

(time until typed probe text appears on the rendered screen; Antigravity uses its internal input-ready log marker because the sign-in screen suppresses probe echo.)

Measured on this Linux machine across 10 interactive PTY launches. Antigravity CLI was unauthenticated for this run; its sign-in screen rendered normally and emitted an internal CLI ready for user input marker, but did not echo the typed probe.

Additional clients / memory scaling

versions tested for this corrected memory rerun:

• jcode v0.9.1888-dev (be386f2)
• pi 0.62.0
• codex-cli 0.120.0
• opencode 1.0.203
• GitHub Copilot CLI 1.0.24 for the 1-session rerun, GitHub Copilot CLI 1.0.27 for the 10-session rerun
• Cursor Agent 2026.04.08-a41fba1
• Claude Code 2.1.86 (Claude Code)
• Antigravity CLI 1.0.0

---

Memory (Agent memory)

Jcode embeds each turn/response as a semantic vector. Every turn does queries a graph of memories to efficiently find related memory entries via a cosine similarity check. The embedding hits are fed into the conversation, or optionally uses a memory sideagent which verifies the memories are relevant, and potentially does more work for information retreival before injecting into the conversation. This results in a human like memory system which allows the agent to automatically recall relevant information to the conversation without actively calling memory tools or being a token burner. ot To have memories which are retrieved, they must also be extracted and stored. Every so often (semantic drift, K turns since last extraction, session end, etc), memories are extracted via a memory sideagent, and put into the memory graph.

The harness also provides explicit memory tools to allow the agent to actively search or store the memory without relying on a passive background process. The harness also provides session search for traditional RAG on previous sessions.

Memories are automatically consolidated every so often via the ambient mode. This reorganizes, checks for staleness and conflicts, etc

---

UI: Side panels, Diagrams, Info Widgets, rendering, scrolling, alignment

The panel tool opens a new desktop panel from Markdown content or a linked Markdown/PDF file, and supports update, focus, close, and list actions. See Desktop panels for the API, PDF limits, and compatibility details.

The side panel is a place for auxiliary information. Tell your jcode agent to load a file into the side panel and see it update in real time, or tell your agent to write directly to the side panel, or use it as a diff viewer. The side panel (and chat) is able to render mermaid diagrams inline.

To make this possible, I created a new mermaid rendering library to render diagrams 1800x faster. It has no browser or Typescript dependency. See https://github.com/1jehuang/mermaid-rs-renderer

To show you important information without taking space away from the screen that could be used for responses, I developed info widgets. Info widgets will only ever take up the negative space on the screen to show you information, and will get out of the way if there isn't any.

Jcode can render at over a thousand fps. Your monitor will not have the refresh rate to show you, but this means you will not have silly flicker problems.

The custom scrollback implementation of jcode allows it to do much more than a native scrollback. However, it is a terminal-level limitation that I cannot have smooth, partial line scrolling with a custom scrollback. To fix this, I made my own terminal. Handterm https://github.com/1jehuang/handterm implements a native scroll api, and also happens to be very efficient. This is a work in progress. Scrolling is still well implemented for normal terminals.

Jcode is left-aligned by default. You can switch to centered mode with the Alt+C hotkey, with the /alignment command, or in the config.

To disable emoji globally in TUI and CLI output, set emoji = false under [display] in ~/.jcode/config.toml, or launch with JCODE_NO_EMOJI=1. Jcode replaces emoji with compact ASCII markers while preserving other Unicode text.

---

Swarm

Spawn two or more agents in the same repo, and they will automatically be managed by the server to allow native collaboration. When agent A edits a file that agent B has read (code shifting under its feet), the server notifies agent B. Agent B can ignore it if it is not relevant, or it can check the diff to make sure that it doesn't conflict. Each agent has messaging abilities, capable of DMing just one agent, broadcasting to all other agents hosted by the server, or just agents working in that repo. This allows you to spawn multiple sessions in the same repo, and have all conflicts automatically resolved.

Agents are also able to spawn their own swarms autonomously. They have a swarm tool which allows them to spawn in their own teamates to accomplish tasks in parallel. Doing so turns the main agent into a coordinator and the spawned agents into workers. Groups of agents, their messaging channels, their completion statuses, etc are all automatically managed. This can be done headlessly or headed.

---

Swarm modes keep root reasoning separate from worker effort. Configure each mode in ~/.jcode/config.toml:

[agents]
swarm_root_effort = "low"        # /effort swarm
swarm_deep_root_effort = "high"  # /effort swarm-deep

Both default to max. Accepted levels are none, minimal, low, medium, high, xhigh, and max, mapped to the provider's supported range. The effort switcher shows the configured root level. These settings do not change worker swarm_effort. Environment overrides are JCODE_SWARM_ROOT_EFFORT and JCODE_SWARM_DEEP_ROOT_EFFORT.

OAuth and Providers

jcode works with subscription-backed OAuth flows and many provider integrations, so you can use the models you already pay for and still fall back to direct API providers when needed.

Supported built-in login flows

• Claude (jcode login --provider claude)
• OpenAI / ChatGPT / Codex (jcode login --provider openai)
• Google Gemini (jcode login --provider gemini)
• GitHub Copilot (jcode login --provider copilot)
• Azure OpenAI (jcode login --provider azure)
• Alibaba Cloud Coding Plan (jcode login --provider alibaba-coding-plan)
• Fireworks (jcode login --provider fireworks)
• Novita AI (jcode login --provider novita, API key)
• MiniMax (jcode login --provider minimax)
• Meta Model API / Muse (jcode login --provider meta-muse)
• LM Studio (jcode login --provider lmstudio)
• Ollama (jcode login --provider ollama)
• Custom OpenAI-compatible endpoint (jcode login --provider openai-compatible)

For custom OpenAI-compatible endpoints, jcode now prompts for the API base and supports local localhost servers without requiring an API key.

The native OpenAI providers use Responses WebSocket v2 with opportunistic background prewarming and HTTPS fallback. See OpenAI WebSocket transport for behavior, controls, and verification.

Config-file setup for self-hosted endpoints and MCP

If you prefer to configure things by editing files instead of using the login UI, jcode supports both a custom OpenAI-compatible endpoint config and MCP config files.

OpenAI-compatible providers

Many hosted services speak the standard OpenAI /v1/chat/completions API. jcode talks to them through one shared OpenAI-compatible provider, so you can use almost any such endpoint without waiting for a dedicated integration.

There are two ways to set one up:

• Built-in named profiles — jcode ships ready-made profiles for several popular OpenAI-compatible services. Log in by id and jcode fills in the base URL and key environment variable for you:

  jcode login --provider 
  # for example:
  jcode login --provider openrouter
  jcode login --provider orcarouter
  jcode login --provider deepseek
  jcode login --provider opencode      # OpenCode Zen
  jcode login --provider moonshotai
  jcode login --provider meta-muse     # Meta Model API / Muse Spark
  

Built-in OpenAI-compatible profile ids include: openrouter, orcarouter, deepseek, zai, kimi, moonshotai, meta-muse (Meta Model API / Muse Spark), opencode (OpenCode Zen), opencode-go, 302ai, baseten, cortecs, huggingface, nebius, scaleway, stackit, and firmware. Each profile only sets the endpoint and key variable; you still pick the model with /model (or --model). Run jcode login with no provider to see the interactive list.

• Any other endpoint — point jcode at an arbitrary OpenAI-compatible API (hosted or local) with jcode login --provider openai-compatible or the scriptable jcode provider add command described below.

Useful environment overrides for these endpoints:

• JCODE_STREAM_IDLE_TIMEOUT_SECS — raise the base streaming idle timeout (default 180s) for slow reasoning models that think silently before emitting tokens. High reasoning efforts scale this automatically (high 2x, xhigh 3x, max 4x). Also settable as [provider] stream_idle_timeout_secs in config.toml.
• Per-model context_window (alias context_limit) in a [[providers..models]] entry — set the context window when the endpoint has no usable /v1/models response, so jcode does not fall back to the generic 200k default.
• extra_body — inject non-standard top-level fields into every chat/completions request body for backends that require them. See Extra request-body fields below.

For details on self-hosting, local runtimes, and the exact config file shape, see below.

Self-hosted OpenAI-compatible endpoints, including vLLM

For agents and scripts, the preferred path is the one-shot provider profile command. It writes a named profile to ~/.jcode/config.toml, stores secrets in jcode's private app config directory when requested, and prints exact run/validation commands:

# Secret-safe setup for a hosted OpenAI-compatible API.
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 \
  --json
Smoke test the profile.
jcode --provider-profile my-api auth-test --prompt 'Reply exactly JCODE_PROVIDER_SETUP_OK'
Use it directly.
jcode --provider-profile my-api run 'hello'

For local servers that do not require auth:

jcode provider add local-vllm \
  --base-url http://localhost:8000/v1 \
  --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --no-api-key \
  --set-default

Built-in local profiles are available for the common desktop/local runtimes:

# Ollama: start the local server and install a model first.
ollama pull llama3.2
jcode login --provider ollama
jcode --provider ollama --model llama3.2 run 'hello'
LM Studio: start the Local Server, load a chat model, then use the exact
model identifier shown by LM Studio or by curl http://localhost:1234/v1/models.
jcode login --provider lmstudio
jcode --provider lmstudio --model '' run 'hello'

Ollama and LM Studio both expose OpenAI-compatible /v1/models and /v1/chat/completions endpoints. jcode uses streaming chat completions, function/tool calling, and OpenAI-style image content for vision-capable local models. If a local server requires a token, enter it during jcode login or create a named profile with --api-key-stdin.

Useful flags:

• --api-key-env NAME: reference an existing environment variable instead of storing a key.
• --api-key-stdin: read and store a key without putting it in shell history.
• --context-window TOKENS: persist the model context window for model selection and routing.
• --overwrite: replace an existing profile of the same name.
• --model-catalog: use the endpoint's /models response in addition to configured models.

The generated profile can also be edited manually in ~/.jcode/config.toml:

[provider]
default_provider = "my-api"
default_model = "my-model-id"
[providers.my-api]
type = "openai-compatible"
base_url = "https://llm.example.com/v1"
api_key_env = "JCODE_PROVIDER_MY_API_API_KEY"
env_file = "provider-my-api.env"
default_model = "my-model-id"
Optional: prevent model names such as gpt-5-* from automatically enabling
reasoning_effort on gateways that reject it.
disable_reasoning_heuristics = true

[[providers.my-api.models]]
id = "my-model-id"
context_window = 128000
Explicitly enable /effort and select this model's initial effort. Set
reasoning = false on an individual model to disable it instead.
reasoning = true
reasoning_effort = "high"

Anthropic Messages-compatible gateways use the same named-profile surface with type = "anthropic-compatible". The profile can select bearer, custom-header, or no authentication and attach gateway-specif