1jehuang/jcode

jcode

The most RAM efficient harness The most most intelligent harness

Website · Docs · Benchmarks · Features · Install · Quick Start · Further Reading · Contributing

Installation

# 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.

Performance & Resource Efficiency

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

• 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 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 effiecent. 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.

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)
• MiniMax (jcode login --provider minimax)
• 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.

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 <profile-id> # for example: jcode login --provider openrouter jcode login --provider deepseek jcode login --provider opencode # OpenCode Zen jcode login --provider moonshotai Built-in OpenAI-compatible profile ids include: `openrouter`, `deepseek`, `zai`, `kimi`, `moonshotai`, `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.<name>.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 '<model-id>' 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"

[[providers.my-api.models]]
id = "my-model-id"
context_window = 128000

Extra request-body fields (extra_body)

Some OpenAI-compatible backends require non-standard top-level request fields. For example, NVIDIA NIM DeepSeek-V4 reasoning models (deepseek-ai/deepseek-v4-flash, deepseek-ai/deepseek-v4-pro) only enable thinking when the request includes chat_template_kwargs; without it they reply without reasoning (or, for some deployments, hang). jcode lets you inject arbitrary top-level fields two ways.

1. 1Per named profile, via `extra_body` in `config.toml` (a TOML table merged verbatim into the JSON body): [providers.my-nim] type = "openai-compatible" base_url = "https://integrate.api.nvidia.com/v1" api_key_env = "NVIDIA_API_KEY" default_model = "deepseek-ai/deepseek-v4-flash" [providers.my-nim.extra_body.chat_template_kwargs] thinking = true reasoning_effort = "high"
2. 2For built-in profiles (e.g. `nvidia-nim`) or any endpoint, via the `JCODE_OPENAI_EXTRA_BODY` environment variable (a JSON object string). It can live in the provider's env file (`~/.config/jcode/nvidia-nim.env`) next to the API key: JCODE_OPENAI_EXTRA_BODY={"chat_template_kwargs":{"thinking":true,"reasoning_effort":"high"}}

Keys from extra_body are merged last and override any jcode-generated body field with the same name (JCODE_OPENAI_EXTRA_BODY wins over the config extra_body on key collisions). Invalid values are logged and ignored rather than failing the request.

The custom OpenAI-compatible provider reads overrides from environment variables or from an env file in jcode's app config directory. On Linux this is usually ~/.config/jcode/, so the default file is usually:

~/.config/jcode/openai-compatible.env

Example for a local or LAN vLLM server:

JCODE_OPENAI_COMPAT_API_BASE=http://192.168.1.50:8000/v1
JCODE_OPENAI_COMPAT_DEFAULT_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
# Optional if your server expects auth
OPENAI_COMPAT_API_KEY=your-token-here

Notes:

• jcode login --provider openai-compatible can create or update this for you.
• Plain http:// is accepted for localhost and private LAN IPs. Public remote HTTP is still rejected.
• HTTPS endpoints work as usual.

MCP config files

MCP config is separate from config.toml.

Primary config files:

• ~/.jcode/mcp.json for global MCP servers
• .jcode/mcp.json for project-local MCP servers

Claude Code compatibility:

• ~/.claude.json (Claude Code's user config): top-level mcpServers, plus per-project servers under projects.<abs_path>.mcpServers for the current directory
• .mcp.json at the repo root (Claude Code's project config)
• .claude/mcp.json (legacy fallback)

Both the canonical mcpServers key and jcode's historical servers key are accepted. jcode currently supports stdio (command-based) servers only; HTTP/SSE entries ("type": "http"/"sse") are recognized and skipped with a log line.

Example MCP config:

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

On first run, jcode also tries to import MCP servers from ~/.claude.json (falling back to the legacy ~/.claude/mcp.json) and ~/.codex/config.toml if ~/.jcode/mcp.json does not exist yet.

For headless or SSH sessions, OAuth-style providers support jcode login --provider <provider> --no-browser (alias: --headless) so jcode prints the auth URL/QR and falls back to manual code or callback paste instead of trying to launch a local browser.

For more scriptable remote flows, claude, openai, gemini, and antigravity also support a two-step pattern:

# Step 1: print a resumable auth URL
jcode login --provider openai --print-auth-url --json

# Step 2: complete later with the callback URL or auth code
jcode login --provider openai --callback-url 'http://localhost:1455/auth/callback?...'
jcode login --provider gemini --auth-code '...'

Additional scriptable cases:

# Copilot device flow: print URL + user code, then complete later
jcode login --provider copilot --print-auth-url --json
jcode login --provider copilot --complete

# Gmail/Google OAuth after credentials are already configured
jcode login --provider google --print-auth-url --google-access-tier readonly
jcode login --provider google --callback-url 'http://127.0.0.1:8456?...'

Pending scriptable login state is stored under ~/.jcode/pending-login/, automatically expires, and stale entries are cleaned up when new scriptable logins start or resume.

For the built-in OpenAI login flow, jcode opens a local callback on http://localhost:1455/auth/callback by default.

Supported provider

• Native / first-party style providers: claude, openai, copilot, gemini, azure, alibaba-coding-plan
• Aggregator / compatibility providers: openrouter, openai-compatible
• Additional provider integrations: opencode, opencode-go, zai / kimi, 302ai, baseten, cortecs, deepseek, firmware, huggingface, moonshotai, nebius, scaleway, stackit, groq, mistral, perplexity, togetherai, deepinfra, fireworks, minimax, xai, lmstudio, ollama, chutes, cerebras, cursor, antigravity, google

Jcode also supports easy multi-account switching. Ran out of tokens on your first ChatGPT Pro subscription? /account and quickly switch to your second.

Customizability / Self-Dev

Jcode is inventing a new form of customizability. One that doesn't limit you to what a plugin or extension can do. Tell your jcode agent to enter self dev mode, and it will start modifying its own source code. Jcode is optimized to iterate on itself. There is significant infrastructure around self developement, which allows it to edit, build, and test its own source code, then reload its own binary and continue work in your (potentially many) sessions, fully automatically.

It is reccomended that you use a frontier model for this. The jcode codebase is not a simple one, and weaker models can make subtle, breaking changes. GPT 5.5 or the latest available frontier model works well.

Misc.

The devil is in the details. There are many undocumented optimizations and niceties that jcode implements. Some examples:

Anthropic's Claude cache goes cold after 5 minutes. If you initiate Claude after these 5 minutes, you have a cache miss, potentially costing you lots of tokens. The ui warns you when the cache went cold, and notfies you if there was an unexpected cache miss.

jcode comes with instructions on how to set up Firefox Agent Bridge. Ask you agent to set it up, and then you will have browser automation in jcode as well.

Agent grep is a grep tool I made for the jcode agent. It adds file strucuture information (ie the list of functions, their displacement, etc) to the grep return, so that the agent can infer more of what the file doesn without actually reading the file. It also implements a harness-level integration that adaptively truncates returns based on what the agent has already seen. This saves on context a lot.

Inputs are by default interleaved with the working agent. It sends the input as soon as it safely can without breaking the KV cache. Submit with shift enter instead, and it will send a queue send, and wait for the agent to fully finish its turn before sending.

Resume sessions from different harnesses. Claude code broke on you? Resume the session from jcode and continue where you left off. Session resume is supported for codex, claude code, opencode, and pi.

Skills are not all loaded on startup. The conversation is embedded as a semantic vector, and will automatically inject a skill if there is an embedding hit similar to memories. The agent has a skill tool for you to manually activate a skill at anytime. You may also activate via slash commands.

iOS Application / Native OpenClaw

A native iOS application version of jcode is coming soon. This will allow you to work with jcode on your personal machine's environment from your phone, via Tailscale. Openclaw like features will be bundled with this iOS application.

Other planned features

Agents dont like to commit in dirty git state with active changes. Git was clearly not built for multi-agent workflows, and git worktrees is not a good solution. Given this, I believe that is an opporunity for a new git like primitive to be born.

Build speed improvements: An incremental debug cargo build with cache enabled takes about 1 minute on my machine. The goal is 5-20 seconds. Refactors and crates seams should be able to make this happen.

Quick Start

# Launch the TUI
jcode

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

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

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

# Send voice input from your configured STT command
jcode dictate

jcode supports interactive TUI use, non-interactive runs, persistent server/client workflows, and hotkey-friendly dictation without requiring a bundled speech-to-text stack.

Browser Automation

jcode includes a first-class built-in browser tool for browser control inside agent sessions.

Current built-in backend:

• Firefox via Firefox Agent Bridge

Current built-in tool actions include:

• status
• setup
• open
• snapshot
• get_content
• interactables
• click
• type
• fill_form
• select
• wait
• screenshot
• eval
• scroll
• upload
• press

Quick setup:

jcode browser status
jcode browser setup

Once setup is complete, the model can use the built-in browser tool directly. The UI also summarizes browser tool calls compactly, for example opening a URL, clicking a selector, or typing into a field without echoing sensitive typed text.

Notes:

• the provider/tool architecture is in place for additional backends
• Firefox is the wired built-in backend today
• Chrome bridge / remote debugging style providers can be added on top of the same browser tool later

Further Reading

• jcode.sh/docs — install, providers, configuration, keybindings
• jcode.sh/swarm — many coding agents in one repository
• jcode.sh/bench — benchmark methodology and results
• Ambient Mode / OpenClaw
• Browser Provider Protocol
• Memory Architecture
• Swarm Architecture
• Server Architecture
• Safety System
• Sponsored Discovery Sponsor Onboarding
• Windows Notes
• Wrappers and Shell Integration
• Refactoring Notes

Detailed Installation

Setup

If you want another agent to set up jcode for you, give it this prompt:

Set up jcode on this machine for me.

1. Detect the operating system, available package managers, and shell environment, then install jcode using the best matching command below instead of referring me somewhere else:

   - macOS with Homebrew available:
     brew tap 1jehuang/jcode
     brew install jcode

   - macOS or Linux via install script:
     curl -fsSL https://jcode.sh/install | bash

   - Windows PowerShell:
     irm https://jcode.sh/install.ps1 | iex

   - From source if the above paths are not appropriate:
     git clone https://github.com/1jehuang/jcode.git
     cd jcode
     cargo build --release
     scripts/install_release.sh

   - For local self-dev / refactor work on Linux x86_64, prefer:
     scripts/dev_cargo.sh build --release -p jcode --bin jcode
     scripts/dev_cargo.sh --print-setup
     scripts/install_release.sh

2. Verify that `jcode` is on my `PATH`.
3. Launch `jcode` once in a new terminal window/session to confirm it starts successfully.
4. Before attempting any interactive login flow, assess which providers are already available non-interactively and prefer those first. Check existing local credentials, config files, CLI sessions, and environment variables such as:
   - Claude: `~/.jcode/auth.json`, `~/.claude/.credentials.json`, `~/.local/share/opencode/auth.json`, `ANTHROPIC_API_KEY`
   - OpenAI: `~/.jcode/openai-auth.json`, `~/.codex/auth.json`, `OPENAI_API_KEY`
   - Gemini: `~/.jcode/gemini_oauth.json`, `~/.gemini/oauth_creds.json`
   - GitHub Copilot: existing auth under `~/.config/github-copilot/`
   - Azure OpenAI: `~/.config/jcode/azure-openai.env`, `AZURE_OPENAI_*`, or an existing `az login`
   - OpenRouter: `OPENROUTER_API_KEY`
   - Fireworks: `~/.config/jcode/fireworks.env`, `FIREWORKS_API_KEY`
   - MiniMax: `~/.config/jcode/minimax.env`, `MINIMAX_API_KEY`
   - NVIDIA NIM: `~/.config/jcode/nvidia-nim.env`, `NVIDIA_API_KEY`
   - Alibaba Cloud Coding Plan: existing jcode config/env if present
5. Prefer whichever provider is already configured and verify it with `jcode auth-test --all-configured` or a provider-specific auth test when appropriate.
6. Only if no usable provider is already configured, guide me through the minimal manual step needed:
   - Claude: `jcode login --provider claude`
   - GitHub Copilot: `jcode login --provider copilot`
   - OpenAI: `jcode login --provider openai`
   - Gemini: `jcode login --provider gemini`
   - Azure OpenAI: `jcode login --provider azure`
   - Fireworks: `jcode login --provider fireworks`
   - MiniMax: `jcode login --provider minimax`
   - NVIDIA NIM: `jcode login --provider nvidia-nim`
   - Alibaba Cloud Coding Plan: `jcode login --provider alibaba-coding-plan`
   - OpenRouter: help me set `OPENROUTER_API_KEY`
   - Anthropic direct API: help me set `ANTHROPIC_API_KEY`
7. After setup, run a simple smoke test with `jcode run "say hello"` and confirm it works.
8. If I want browser automation, also check `jcode browser status`. If browser automation is not ready, run `jcode browser setup`, verify the built-in `browser` tool works, and explain any remaining manual step.
9. Explain any manual step that still needs me, especially browser OAuth, device login, API key entry, or browser extension approval.

This is intended to be a copy-paste bootstrap prompt for jcode itself or any other coding agent.

Quick Install

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

On Termux, install the glibc runtime and patchelf first so the installer can patch the downloaded Linux binary to Termux's glibc dynamic linker and create a launcher that avoids Termux's LD_PRELOAD shim:

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

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

The Windows installer selects the correct architecture and verifies the download against the release's SHA256SUMS. Alacritty and the optional global launch hotkey require explicit consent and are not installed by default. See Windows support, security, Defender, and SmartScreen notes.

If a release does not contain a matching Windows asset, the installer stops instead of unexpectedly starting a long compilation. An explicit source build is available with -BuildFromSource and requires Git, Rust, and Visual Studio 2022 Build Tools with the Desktop development with C++ workload.

macOS via Homebrew

brew tap 1jehuang/jcode
brew install jcode

From Source (all platforms)

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

For local self-dev / refactor work on Linux x86_64, prefer:

scripts/dev_cargo.sh build --release -p jcode --bin jcode
scripts/dev_cargo.sh --print-setup

That wrapper automatically uses sccache when available, prefers a fast working local linker setup (clang + lld) instead of assuming every machine's mold configuration is valid, and can print the active linker/cache setup via --print-setup so slow-path builds are easier to diagnose.

Then symlink to your PATH:

scripts/install_release.sh

Uninstall

Removes installed binaries and the launcher but keeps your config, auth, and sessions so a clean reinstall picks up where you left off:

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

For a full wipe of everything including config, auth, sessions, logs, and memory (useful for recovering from a broken install):

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

Add --dry-run to preview what would be removed without deleting anything.

Platform Support