1jehuang--jcode/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/1jehuang/jcode) · [上游 README](https://github.com/1jehuang/jcode/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<div align="center">

# jcode

[![Latest Release](https://badgen.net/github/release/1jehuang/jcode?icon=github)](https://github.com/1jehuang/jcode/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
[![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)](https://github.com/1jehuang/jcode/releases)
[![Last Commit](https://badgen.net/github/last-commit/1jehuang/jcode/master?icon=github)](https://github.com/1jehuang/jcode/commits/master)
[![GitHub Stars](https://badgen.net/github/stars/1jehuang/jcode?icon=github)](https://github.com/1jehuang/jcode/stargazers)
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/nBe9vGyK9a)

新一代编程智能体（coding agent）运行时框架，用于突破技能上限。<br>
专为多会话工作流、无限可定制性与高性能而打造。

<br>

<a href="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-memory-demo.mp4">
  <img src="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-memory-demo.webp" alt="jcode 记忆演示" width="800">
</a>

<br>

[官网](https://jcode.sh) · [功能](#features) · [安装](#installation) · [快速入门](#quick-start) · [延伸阅读](#further-reading) · [贡献](CONTRIBUTING.md)

</div>

---

<div align="center">

## 安装

</div>

```bash
# macOS & Linux
curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash
```

需要 Windows、Homebrew、源码构建、提供商（provider）配置，或让智能体帮你安装？
[跳转到详细安装说明](#detailed-installation)。

---


<div align="center">

## 性能与资源效率

</div>

jcode 在设计上尽可能做到高性能与资源高效。每一项指标都经过极致优化，这对扩展多会话工作流尤为重要。下面我们抽样展示几项指标以说明差异：RAM 占用与启动时间。

### RAM 对比

<div align="center">

<table>
  <tr>
    <td valign="top" align="center" width="50%">
      <strong>1 个活跃会话</strong>
      <table>
        <thead>
          <tr>
            <th>工具</th>
            <th>PSS</th>
            <th>对比</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><strong>jcode（关闭本地 embedding）</strong></td>
            <td align="right"><strong>27.8 MB</strong></td>
            <td align="right">基线</td>
          </tr>
          <tr>
            <td><strong>jcode</strong></td>
            <td align="right"><strong>167.1 MB</strong></td>
            <td align="right"><strong>6.0× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>pi</strong></td>
            <td align="right"><strong>144.4 MB</strong></td>
            <td align="right"><strong>5.2× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Codex CLI</strong></td>
            <td align="right"><strong>140.0 MB</strong></td>
            <td align="right"><strong>5.0× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>OpenCode</strong></td>
            <td align="right"><strong>371.5 MB</strong></td>
            <td align="right"><strong>13.4× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>GitHub Copilot CLI</strong></td>
            <td align="right"><strong>333.3 MB</strong></td>
            <td align="right"><strong>12.0× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Cursor Agent</strong></td>
            <td align="right"><strong>214.9 MB</strong></td>
            <td align="right"><strong>7.7× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Claude Code</strong></td>
            <td align="right"><strong>386.6 MB</strong></td>
            <td align="right"><strong>13.9× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Antigravity CLI</strong></td>
            <td align="right"><strong>243.7 MB</strong></td>
            <td align="right"><strong>8.8× 更多 RAM</strong></td>
          </tr>
        </tbody>
      </table>
    </td>
    <td width="24"></td>
    <td valign="top" align="center" width="50%">
      <strong>10 个活跃会话</strong>
      <table>
        <thead>
          <tr>
            <th>工具</th>
            <th>PSS</th>
            <th>对比</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><strong>jcode（关闭本地 embedding）</strong></td>
            <td align="right"><strong>117.0 MB</strong></td>
            <td align="right">基线</td>
          </tr>
          <tr>
            <td><strong>jcode</strong></td>
            <td align="right"><strong>260.8 MB</strong></td>
            <td align="right"><strong>2.2× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>pi</strong></td>
            <td align="right"><strong>833.0 MB</strong></td>
            <td align="right"><strong>7.1× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Codex CLI</strong></td>
            <td align="right"><strong>334.8 MB</strong></td>
            <td align="right"><strong>2.9× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>OpenCode</strong></td>
            <td align="right"><strong>3237.2 MB</strong></td>
            <td align="right"><strong>27.7× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>GitHub Copilot CLI</strong></td>
            <td align="right"><strong>1756.5 MB</strong></td>
            <td align="right"><strong>15.0× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Cursor Agent</strong></td>
            <td align="right"><strong>1632.4 MB</strong></td>
            <td align="right"><strong>14.0× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Claude Code</strong></td>
            <td align="right"><strong>2300.6 MB</strong></td>
            <td align="right"><strong>19.7× 更多 RAM</strong></td>
          </tr>
          <tr>
            <td><strong>Antigravity CLI</strong></td>
            <td align="right"><strong>1021.2 MB</strong></td>
            <td align="right"><strong>8.7× 更多 RAM</strong></td>
          </tr>
        </tbody>
      </table>
    </td>
  </tr>
</table>

</div>

### 首帧时间

<div align="center">

| 工具 | 首帧时间 | 范围 | 对比 |
|---|---:|---:|---:|
| **jcode** | **14.0 ms** | 10.1–19.3 ms | 基线 |
| **Antigravity CLI** | **383.5 ms** | 363.1–415.4 ms | **慢 27.4×** |
| **pi** | **590.7 ms** | 369.6–934.8 ms | **慢 42.2×** |
| **Codex CLI** | **882.8 ms** | 742.3–1640.9 ms | **慢 63.1×** |
| **OpenCode** | **1035.9 ms** | 922.5–1104.4 ms | **慢 74.0×** |
| **GitHub Copilot CLI** | **1518.6 ms** | 1357.4–1826.8 ms | **慢 108.5×** |
| **Cursor Agent** | **1949.7 ms** | 1711.0–2104.8 ms | **慢 139.3×** |
| **Claude Code** | **3436.9 ms** | 2032.7–8927.2 ms | **慢 245.5×** |

</div>

在本台 Linux 机器上，通过 10 次交互式 PTY 启动测得。

### 首次可输入时间
（从输入探测文本到其在渲染屏幕上出现为止的时间；Antigravity 使用其内部 input-ready 日志标记，因为登录界面会抑制探测回显。）
<div align="center">

| 工具 | 首次可输入时间 | 范围 | 对比 |
|---|---:|---:|---:|
| **jcode** | **48.7 ms** | 30.3–62.7 ms | 基线 |
| **Antigravity CLI** | **383.7 ms** | 363.4–415.7 ms | **慢 7.9×** |
| **pi** | **596.4 ms** | 373.9–955.2 ms | **慢 12.2×** |
| **Codex CLI** | **905.8 ms** | 760.1–1675.7 ms | **慢 18.6×** |
| **OpenCode** | **1047.9 ms** | 931.1–1116.9 ms | **慢 21.5×** |
| **GitHub Copilot CLI** | **1583.4 ms** | 1422.8–1880.0 ms | **慢 32.5×** |
| **Cursor Agent** | **1978.7 ms** | 1727.3–2130.0 ms | **慢 40.6×** |
| **Claude Code** | **3512.8 ms** | 2137.4–9002.0 ms | **慢 72.2×** |

</div>

在本台 Linux 机器上，通过 10 次交互式 PTY 启动进行测量。本次运行中 Antigravity CLI 未认证；其登录界面正常渲染并输出了内部标记 `CLI ready for user input`，但未回显输入的探测字符。

### 其他客户端 / 内存扩展

<div align="center">

| Tool | 每新增会话额外 PSS | 对比 |
|---|---:|---:|
| **jcode (local embedding off)** | **~9.9 MB** | baseline |
| **jcode** | **~10.4 MB** | **1.1× more RAM** |
| **pi** | **~76.5 MB** | **7.7× more RAM** |
| **Codex CLI** | **~21.6 MB** | **2.2× more RAM** |
| **OpenCode** | **~318.4 MB** | **32.2× more RAM** |
| **GitHub Copilot CLI** | **~158.1 MB** | **16.0× more RAM** |
| **Cursor Agent** | **~157.5 MB** | **15.9× more RAM** |
| **Claude Code** | **~212.7 MB** | **21.5× more RAM** |
| **Antigravity CLI** | **~86.4 MB** | **8.7× more RAM** |

</div>

本次修正后的内存重跑所测试的版本：

- `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` 用于 1 会话重跑，`GitHub Copilot CLI 1.0.27` 用于 10 会话重跑
- `Cursor Agent 2026.04.08-a41fba1`
- `Claude Code 2.1.86 (Claude Code)`
- `Antigravity CLI 1.0.0`

<div align="center">

  <a href="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-performance-demo.mp4">
    <img src="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-performance-demo.webp" alt="jcode performance demonstration" width="900">
  </a>

  <p><em>jcode performance demonstration</em></p>

</div>


---

## Memory（Agent memory）

Jcode 将每一轮对话/响应嵌入为语义向量（semantic vector）。每一轮都会对记忆图（graph of memories）进行查询，通过余弦相似度（cosine similarity）检查高效找到相关记忆条目。嵌入命中结果会注入对话，或可选地使用 memory sideagent，由其验证记忆是否相关，并可能在注入对话前执行更多信息检索工作。这形成类人的记忆系统，使 agent 能自动回忆与对话相关的信息，而无需主动调用记忆工具或成为 token 消耗大户。
ot 
要让记忆可被检索，它们也必须被提取并存储。每隔一段时间（语义漂移、距上次提取已过 K 轮、会话结束等），会通过 memory sideagent 提取记忆，并写入记忆图。

该 harness 还提供显式记忆工具，使 agent 能主动搜索或存储记忆，而不依赖被动后台进程。该 harness 还提供会话搜索，用于对以往会话进行传统 RAG。

记忆会通过 ambient mode 定期自动整合。这会重新组织、检查陈旧与冲突等。

<div align="center">

  <a href="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-memory-demo.mp4">
    <img src="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-memory-demo.webp" alt="jcode memory demonstration" width="900">
  </a>

  <p><em>jcode memory demonstration</em></p>

</div>

<!-- Memory demo media is hosted in the readme-assets release. -->

---

## UI：侧边栏、图表、信息组件、渲染、滚动、对齐

侧边栏用于展示辅助信息。告诉你的 jcode agent 将文件加载到侧边栏即可实时看到更新，或让 agent 直接写入侧边栏，或将其用作 diff 查看器。侧边栏（以及聊天区）能够内联渲染 mermaid 图表。
<img width="2877" height="1762" alt="image" src="https://github.com/user-attachments/assets/6c7bec81-ef3f-434d-8a7b-d55f8a54e5cf" />

为实现这一点，我创建了一个新的 mermaid 渲染库，渲染图表速度提升 1800 倍。它不依赖浏览器或 Typescript。参见 https://github.com/1jehuang/mermaid-rs-renderer

为在不占用本可用于回复的屏幕空间的情况下展示重要信息，我开发了 info widgets（信息组件）。信息组件只会占用屏幕上的负空间来展示信息，没有内容时会自动让出位置。

Jcode 渲染帧率可超过一千 fps。你的显示器刷新率跟不上，但这意味着不会出现恼人的闪烁问题。

jcode 的自定义 scrollback 实现使其能力远超原生 scrollback。然而，在终端层面存在限制，无法在使用自定义 scrollback 时实现平滑的部分行滚动。为解决此问题，我开发了自己的终端。Handterm https://github.com/1jehuang/handterm 实现了原生滚动 API，同时也非常高效。此项工作仍在进行中。在普通终端上，滚动仍实现得很好。

Jcode 默认左对齐。你可以通过 `Alt+C` 快捷键、`/alignment` 命令或在配置中切换到居中模式。

---

## Swarm

在同一仓库中启动两个或更多 agent，服务器会自动管理它们以实现原生协作。当 agent A 编辑了 agent B 已读取的文件（代码在其脚下变动）时，服务器会通知 agent B。若无关，agent B 可忽略；也可查看 diff 以确保不发生冲突。每个 agent 都具备消息能力，可向单个 agent 私信、向服务器托管的所有其他 agent 广播，或仅向在该仓库中工作的 agent 广播。这样你可以在同一仓库中启动多个会话，并自动解决所有冲突。

<div align="center">

  <a href="https://github.com/1jehuang/jcode/releases/download/readme-assets/swarm-demo.mp4">
    <img src="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-swarm-demonstration.webp" alt="jcode swarm demonstration" width="900">
  </a>

  <p><em>jcode swarm demonstration</em></p>

</div>

Agent 还能自主孵化自己的 swarm。它们提供 swarm 工具，可孵化自己的队友以并行完成任务。这样做会将主 agent 变为协调者，将孵化的 agent 变为工作者。agent 群组、消息通道、完成状态等均由系统自动管理。可无头（headless）或有头（headed）运行。

---

## OAuth and Providers

jcode 支持基于订阅的 OAuth 流程和多种提供商集成，因此你可以使用已付费的模型，并在需要时仍回退到直接 API 提供商。

### 支持的内置登录流程

- **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`)

对于自定义 OpenAI 兼容端点，jcode 现在会提示输入 API base，并支持本地 localhost 服务器，无需 API key。

### 自托管端点与 MCP 的配置文件设置

如果你更喜欢通过编辑文件而非使用登录 UI 来配置，jcode 同时支持自定义 OpenAI 兼容端点配置和 MCP 配置文件。

#### OpenAI-compatible providers

许多托管服务使用标准 OpenAI `/v1/chat/completions` API。jcode 通过统一的 OpenAI 兼容提供商与它们通信，因此你几乎可以使用任何此类端点，而无需等待专用集成。

有两种设置方式：

- **Built-in named profiles** — jcode 内置了多个热门 OpenAI 兼容服务的即用型配置。按 id 登录后，jcode 会为你填入 base URL 和 key 环境变量：

```bash
  jcode login --provider <profile-id>
  # 例如：
  jcode login --provider openrouter
  jcode login --provider deepseek
  jcode login --provider opencode      # OpenCode Zen
  jcode login --provider moonshotai
  ```

  内置的 OpenAI 兼容（OpenAI-compatible）profile id 包括：`openrouter`、`deepseek`、`zai`、`kimi`、`moonshotai`、`opencode`（OpenCode Zen）、`opencode-go`、`302ai`、`baseten`、`cortecs`、`huggingface`、`nebius`、`scaleway`、`stackit` 以及 `firmware`。每个 profile 仅设置 endpoint 和 key 变量；你仍需通过 `/model`（或 `--model`）选择模型。不带 provider 运行 `jcode login` 可查看交互式列表。

- **任何其他 endpoint** — 使用 `jcode login --provider openai-compatible` 或下文所述的可脚本化 `jcode provider add` 命令，将 jcode 指向任意 OpenAI 兼容 API（托管或本地）。

这些 endpoint 的实用环境变量覆盖项：

- `JCODE_STREAM_IDLE_TIMEOUT_SECS` — 为在输出 token 前静默思考的慢速推理模型提高流式空闲超时（默认 180s）。也可在 `config.toml` 中设置为 `[provider] stream_idle_timeout_secs`。
- 在 `[[providers.<name>.models]]` 条目中按模型设置 `context_window`（别名 `context_limit`）— 当 endpoint 没有可用的 `/v1/models` 响应时设置上下文窗口，以免 jcode 回退到通用的 200k 默认值。
- `extra_body` — 为需要这些字段的后端，向每个 chat/completions 请求体注入非标准顶层字段。详见下文 [Extra request-body fields](#extra-request-body-fields-extra_body)。

有关自托管、本地运行时以及确切配置文件格式的详情，见下文。

#### 自托管 OpenAI 兼容 endpoint，包括 vLLM

对于 agent 和脚本，首选路径是一次性 provider profile 命令。它会将命名 profile 写入 `~/.jcode/config.toml`，在需要时将密钥存入 jcode 的私有应用配置目录，并打印确切的运行/验证命令：

```bash
# 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'
```

对于无需认证的本地服务器：

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

常见桌面/本地运行时有内置本地 profile：

```bash
# 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 和 LM Studio 均暴露 OpenAI 兼容的 `/v1/models` 与 `/v1/chat/completions` endpoint。jcode 使用流式 chat completions、function/tool calling，以及面向支持视觉的本地模型的 OpenAI 风格图像内容。若本地服务器需要 token，可在 `jcode login` 时输入，或使用 `--api-key-stdin` 创建命名 profile。

实用标志：

- `--api-key-env NAME`：引用已有环境变量，而非存储密钥。
- `--api-key-stdin`：读取并存储密钥，且不写入 shell 历史。
- `--context-window TOKENS`：持久化模型上下文窗口，用于模型选择与路由。
- `--overwrite`：替换同名的已有 profile。
- `--model-catalog`：除已配置模型外，还使用 endpoint 的 `/models` 响应。

生成的 profile 也可在 `~/.jcode/config.toml` 中手动编辑：

```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_body`）

部分 OpenAI 兼容后端需要非标准顶层请求字段。例如，NVIDIA NIM DeepSeek-V4 推理模型（`deepseek-ai/deepseek-v4-flash`、`deepseek-ai/deepseek-v4-pro`）仅在请求包含 `chat_template_kwargs` 时才启用 thinking；否则它们会无推理地回复（或在某些部署中会挂起）。jcode 提供两种方式注入任意顶层字段。

1. 按命名 profile，通过 `config.toml` 中的 `extra_body`（原样合并进 JSON 请求体的 TOML 表）：

   ```toml
   [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. 对于内置 profile（例如 `nvidia-nim`）或任意 endpoint，通过 `JCODE_OPENAI_EXTRA_BODY` 环境变量（JSON 对象字符串）。可放在 provider 的 env 文件（`~/.config/jcode/nvidia-nim.env`）中，与 API key 并列：

   ```bash
   JCODE_OPENAI_EXTRA_BODY={"chat_template_kwargs":{"thinking":true,"reasoning_effort":"high"}}
   ```

`extra_body` 的键最后合并，并覆盖同名的 jcode 生成请求体字段（键冲突时 `JCODE_OPENAI_EXTRA_BODY` 优先于配置中的 `extra_body`）。无效值会记录日志并忽略，而不会导致请求失败。

自定义 OpenAI 兼容 provider 从环境变量或 jcode 应用配置目录中的 env 文件读取覆盖项。在 Linux 上通常为 `~/.config/jcode/`，因此默认文件通常为：

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

本地或局域网 vLLM 服务器示例：

```bash
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
```

说明：

- `jcode login --provider openai-compatible` 可为你创建或更新此配置。
- 对于 `localhost` 和私有局域网 IP，接受纯 `http://`。公共远程 HTTP 仍会被拒绝。
- HTTPS endpoint 照常可用。

#### MCP 配置文件

MCP 配置与 `config.toml` 相互独立。

主要配置文件：

- `~/.jcode/mcp.json` 用于全局 MCP 服务器
- `.jcode/mcp.json` 用于项目本地 MCP 服务器

Claude Code 兼容性：

- `~/.claude.json`（Claude Code 用户配置）：顶层 `mcpServers`，以及当前目录下 `projects.<abs_path>.mcpServers` 中的按项目服务器
- 仓库根目录的 `.mcp.json`（Claude Code 项目配置）
- `.claude/mcp.json`（旧版回退）

规范键 `mcpServers` 与 jcode 历史键 `servers` 均可接受。jcode 目前仅支持 stdio（基于命令）服务器；HTTP/SSE 条目（`"type": "http"`/`"sse"`）会被识别并跳过，同时输出一行日志。

MCP 配置示例：

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

首次运行时，若 `~/.jcode/mcp.json` 尚不存在，jcode 还会尝试从 `~/.claude.json`（回退到旧版 `~/.claude/mcp.json`）和 `~/.codex/config.toml` 导入 MCP 服务器。

对于无头或 SSH 会话，OAuth 风格 provider 支持 `jcode login --provider <provider> --no-browser`（别名：`--headless`），以便 jcode 打印认证 URL/二维码，并回退到手动输入 code 或粘贴回调，而不是尝试启动本地浏览器。

对于更可脚本化的远程流程，`claude`、`openai`、`gemini` 和 `antigravity` 也支持两步模式：

```bash
# 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 '...'
```

其他可脚本化场景：

```bash
# 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?...'
```

待处理的 scriptable 登录状态保存在 `~/.jcode/pending-login/` 下，会自动过期；当新的 scriptable 登录启动或恢复时，会清理过期条目。

对于内置的 OpenAI 登录流程，jcode 默认会在 `http://localhost:1455/auth/callback` 上打开本地回调。

<img width="2877" height="1762" alt="Screenshot from 2026-04-02 14-28-51" src="https://github.com/user-attachments/assets/530684c0-9d12-4363-aa0e-1b39a0d4e1be" />
上图是各提供商登录的第一页

### 支持的提供商

- **原生 / 第一方风格提供商：** `claude`, `openai`, `copilot`, `gemini`, `azure`, `alibaba-coding-plan`
- **聚合 / 兼容层提供商：** `openrouter`, `openai-compatible`
- **更多提供商集成：** `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 也支持便捷的多账号切换。第一个 ChatGPT Pro 订阅的 token 用完了？使用 /account 快速切换到第二个。

---

## 可定制性 / 自研（Self-Dev）

Jcode 正在开创一种新的可定制性形式——不再把你限制在插件或扩展能做的事范围内。告诉你的 jcode agent 进入 self dev 模式，它就会开始修改自己的源代码。Jcode 针对自我迭代进行了优化。围绕自研（self development）有大量基础设施，使其能够编辑、构建并测试自己的源代码，然后重新加载自己的二进制文件，在你的（可能很多个）会话中全自动地继续工作。

建议使用前沿（frontier）模型来完成这类任务。jcode 代码库并不简单，较弱的模型可能会做出细微却破坏性的改动。GPT 5.5 或最新可用的前沿模型效果较好。

<!-- Add self-dev demo thumbnail/video and fuller writeup here. -->

---

## 杂项

细节决定成败。jcode 实现了许多未写入文档的优化与贴心设计。例如：

Anthropic 的 Claude 缓存会在 5 分钟后失效。若在这 5 分钟之后再启动 Claude，就会发生缓存未命中（cache miss），可能让你消耗大量 token。UI 会在缓存失效时提醒你，并在出现意外缓存未命中时通知你。

jcode 附带如何配置 Firefox Agent Bridge 的说明。让你的 agent 去配置，之后你就能在 jcode 中使用浏览器自动化。

Agent grep 是我为 jcode agent 制作的 grep 工具。它会在 grep 返回结果中加入文件结构信息（例如函数列表、偏移位置等），让 agent 在不实际读取文件的情况下也能推断文件在做什么。它还实现了 harness 层集成，能根据 agent 已经看到的内容自适应截断返回，从而大幅节省上下文。

输入默认会与工作中的 agent 交错发送。它会在不破坏 KV 缓存的前提下尽快发送输入。改用 Shift+Enter 提交，则会进行队列发送，并等待 agent 完全结束当前轮次后再发送。

可从不同 harness 恢复会话。Claude Code 崩了？从 jcode 恢复该会话，从上次中断处继续。会话恢复支持 codex、claude code、opencode 和 pi。

<img width="2877" height="1762" alt="Screenshot from 2026-04-11 16-28-52" src="https://github.com/user-attachments/assets/c2b383cf-2531-4217-85ae-6a863354dc97" />
Codex 会话 /Resume 界面截图


Skills 不会在启动时全部加载。对话会被嵌入为语义向量，若出现与记忆（memories）类似的嵌入命中，会自动注入对应 skill。agent 提供 skill 工具，供你随时手动激活 skill。也可通过斜杠命令激活。

---

## iOS 应用 / 原生 OpenClaw

jcode 的原生 iOS 应用版本即将推出。届时你可通过手机经 Tailscale 连接个人机器上的环境来使用 jcode。类似 OpenClaw 的功能将随该 iOS 应用一并提供。

---

## 其他规划功能

Agent 不喜欢在存在未提交改动的脏 git 状态下提交。Git 显然不是为多 agent 工作流而设计的，git worktrees 也不是好方案。鉴于此，我认为诞生一种类似 git 的新原语（primitive）是一个机会。

构建速度改进：在我机器上，启用缓存的增量 debug cargo 构建大约需要 1 分钟。目标是 5–20 秒。通过重构和 crate 边界调整应能实现这一目标。

<!-- Add iOS / native OpenClaw preview and fuller writeup here. -->

---

<div align="center">

## 快速开始

</div>

```bash
# 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 支持交互式 TUI 使用、非交互式运行、持久化 server/client 工作流，
以及无需捆绑语音转文字（speech-to-text）栈的热键友好听写输入。

<div align="center">

  <a href="https://github.com/1jehuang/jcode/releases/download/readme-assets/workflow.mp4">
    <img src="https://github.com/1jehuang/jcode/releases/download/readme-assets/jcode-workflow-demonstration.webp" alt="jcode workflow demonstration" width="900">
  </a>

  <p><em>jcode workflow demonstration</em></p>

</div>

---

## 浏览器自动化

jcode 在 agent 会话中内置了一流的 `browser` 工具，用于浏览器控制。

当前内置后端：
- 通过 Firefox Agent Bridge 使用 Firefox

当前内置工具操作包括：
- `status`
- `setup`
- `open`
- `snapshot`
- `get_content`
- `interactables`
- `click`
- `type`
- `fill_form`
- `select`
- `wait`
- `screenshot`
- `eval`
- `scroll`
- `upload`
- `press`

快速配置：

```bash
jcode browser status
jcode browser setup
```

配置完成后，模型可直接使用内置的 `browser` 工具。UI 也会紧凑汇总浏览器工具调用，例如打开 URL、点击选择器或在字段中输入，且不会回显敏感的输入文本。

说明：
- provider/tool 架构已就位，可接入更多后端
- 目前内置并接好线的是 Firefox
- 后续可在同一浏览器工具之上添加 Chrome bridge / 远程调试风格的提供商

---

## 延伸阅读

- [Ambient Mode / OpenClaw](docs/AMBIENT_MODE.md)
- [Browser Provider Protocol](docs/BROWSER_PROVIDER_PROTOCOL.md)
- [Memory Architecture](docs/MEMORY_ARCHITECTURE.md)
- [Swarm Architecture](docs/SWARM_ARCHITECTURE.md)
- [Server Architecture](docs/SERVER_ARCHITECTURE.md)
- [Safety System](docs/SAFETY_SYSTEM.md)
- [Sponsored Discovery Sponsor Onboarding](docs/SPONSORED_DISCOVERY_SPONSOR_ONBOARDING.md)
- [Windows Notes](docs/WINDOWS.md)
- [Wrappers and Shell Integration](docs/WRAPPERS.md)
- [Refactoring Notes](docs/REFACTORING.md)

---

## 详细安装

### 安装

若想让另一个 agent 帮你安装 jcode，把下面这段提示词交给它：

```text
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://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash

   - Windows PowerShell:
     irm https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/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.
```

本文旨在作为可直接复制粘贴的引导提示（bootstrap prompt），供 jcode 本身或任何其他编程智能体使用。

### 快速安装

```bash
# macOS & Linux
curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash
```

在 Termux 上，请先安装 glibc 运行时和 `patchelf`，以便安装程序能将下载的 Linux 二进制文件修补为 Termux 的 glibc 动态链接器，并创建一个可避开 Termux `LD_PRELOAD` 垫片（shim）的启动器：

```bash
pkg install glibc patchelf
curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash
```

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.ps1 | iex
```

### 通过 Homebrew 在 macOS 上安装

```bash
brew tap 1jehuang/jcode
brew install jcode
```

### 从源码构建（全平台）

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

若在 Linux x86_64 上进行本地自研 / 重构工作，建议使用：

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

该封装脚本会在可用时自动使用 `sccache`，优先采用快速的本地链接器配置（`clang + lld`），而非假定每台机器上的 `mold` 配置均有效；还可通过 `--print-setup` 打印当前链接器/缓存配置，便于诊断慢速构建路径。

然后将其符号链接到你的 PATH：

```bash
scripts/install_release.sh
```

### 卸载

会移除已安装的二进制文件和启动器，但保留你的配置、认证信息和会话，以便干净重装后可从上次状态继续：

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

若要彻底清除所有内容（包括配置、认证信息、会话、日志和内存，适用于从损坏的安装中恢复）：

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

添加 `--dry-run` 可预览将被移除的内容，而不会实际删除任何数据。

### 平台支持

| 平台 | 状态 |
|---|---|
| **Linux** x86_64 / aarch64 | 完全支持 |
| **macOS** Apple Silicon & Intel | 支持 |
| **Windows** x86_64 | 支持（原生 + WSL2）|
| **Termux** aarch64 / x86_64 | 支持（需 `pkg install glibc patchelf`）|

</div>