Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ CEREBRAS_API_KEY=
# OpenRouter — https://openrouter.ai/keys
OPENROUTER_API_KEY=

# DeepSeek — https://platform.deepseek.com/api_keys
DEEPSEEK_API_KEY=

# Clerk OAuth (phase 9) — https://clerk.com/keys
# Server: CLERK_SECRET_KEY + CLERK_PUBLISHABLE_KEY validate Bearer tokens on /sessions and /chat.
# CLI: CLERK_FRONTEND_API + CLERK_OAUTH_CLIENT_ID drive the browser /login PKCE flow.
Expand Down
11 changes: 9 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ components:
reasoning-block: { ref: "BotMessage.reasoning", role: "quiet-bar block, 'Thinking:' label, dim body" }
tool-block: { ref: "BotMessage.tool", role: "quiet-bar block, info-colored tool label, args, pending/error suffix" }
composer: { ref: InputBar, role: "Multiline textarea inside the mode-tinted accent bar; hosts overlays" }
status-bar: { ref: StatusBar, role: "Single dim row: mode › model · submit · newline hints" }
status-bar: { ref: StatusBar, role: "Single dim row: mode › model · live phase · fallback notice · loop budget · submit · newline hints" }
session-footer: { ref: "SessionShell.footer", role: "Spinner + interrupt hint (left) / tab-agent hint (right)" }
dialog-shell: { ref: "DialogProvider.Dialog", role: "Centered modal overlay card; dim backdrop; title + esc-affordance" }
search-list: { ref: DialogSearchList, role: "Filter input + scrolling single-select list with selection highlight" }
Expand Down Expand Up @@ -171,7 +171,14 @@ Read **bottom-up** — the way the user experiences it. This mirrors Claude Code
multiline `textarea`. Slash-command and @-mention palettes float **above** it
(`position:absolute; bottom:100%`), never pushing the transcript.
- **Status line** (`{components.status-bar}`): exactly one dim row, Codex-style —
`mode {glyph.sep-chevron} model {glyph.sep-dot} submit hint {glyph.sep-dot} newline hint`.
`mode {glyph.sep-chevron} model {glyph.sep-dot} live phase {glyph.sep-dot} loop budget {glyph.sep-dot} submit hint {glyph.sep-dot} newline hint`.
The live-phase segment (`等待首字` / `思考中` / `执行中` / `生成中`, each with an
elapsed timer) answers "what is it doing right now" and is derived from the
streaming message, so it can never disagree with the transcript. It disappears
when the agent is idle.
The loop-budget segment (`turn 3/51`, plus `4 tools` when the current turn has
run tools) is `DIM` meta and renders only once a run has started — it answers
"how much of the agent budget has this message spent" without adding a second row.
- **Footer** (`{components.session-footer}`): spinner + `esc to interrupt` on the
left while streaming; `tab agent` hint pinned right.

Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ MoCode is a Bun monorepo that pairs a rich **TUI client** with a **Hono API serv
|---|---|
| **Dual agent modes** | **Plan** — read-only exploration and architecture. **Build** — full read/write/bash toolset for implementation. |
| **Local tool execution** | The server defines tools; the CLI runs them against `process.cwd()` with path sandboxing. |
| **Multi-provider models** | Anthropic, OpenAI, Google, Groq, Cerebras, and OpenRouter — switch models mid-session with `/models`. |
| **Multi-provider models** | Anthropic, OpenAI, Google, Groq, Cerebras, OpenRouter, and DeepSeek — switch models mid-session with `/models`. |
| **Session persistence & recovery** | PostgreSQL (SaaS) or local JSON (`--local`). Esc keeps partial text; tool Esc marks `Interrupted by user` and stops immediately; auto-resume on user-only tail; partial assistant uses `/resume` (regenerate). See [Session recovery](#session-recovery). |
| **Rich TUI** | Built with [OpenTUI](https://github.com/opentui/opentui) + React 19 — themes, dialogs, keyboard layers, and slash commands. |
| **OAuth sign-in** | Browser-based PKCE flow via Clerk; tokens stored at `~/.mocode/auth.json`. |
Expand Down Expand Up @@ -148,6 +148,7 @@ mocode
| `GROQ_API_KEY` | Server | Groq API key |
| `CEREBRAS_API_KEY` | Server | Cerebras API key |
| `OPENROUTER_API_KEY` | Server | OpenRouter API key |
| `DEEPSEEK_API_KEY` | Server | DeepSeek API key |
| `CLERK_SECRET_KEY` | Server | Clerk secret key (auth) |
| `CLERK_PUBLISHABLE_KEY` | Server | Clerk publishable key |
| `CLERK_FRONTEND_API` | CLI | Clerk frontend API domain |
Expand Down Expand Up @@ -232,16 +233,19 @@ Implementation details: [`doc/harness-phase-03-stream-reliability-notes.md`](./d
| `llama-3.3-70b-versatile` | Groq (free; weak tool calling) |
| `openai/gpt-oss-20b` | Groq (free) |
| `openai/gpt-oss-120b` | Groq (free) |
| `gpt-oss-120b` | Cerebras (default for BYOK; free recommended) |
| `gpt-oss-120b` | Cerebras (free recommended) |
| `openai/gpt-oss-120b:free` | OpenRouter |
| `deepseek-flash` | DeepSeek (**default**; 1M context; reachable from mainland China) |
| `deepseek-v4-pro` | DeepSeek (stronger, ~4x the price) |

The canonical list lives in `packages/shared/src/models.ts`.

### BYOK (`mocode --local`)

- **Default model:** `gpt-oss-120b` (Cerebras). Set provider keys with **`/keys`** → `~/.mocode/keys.json` (local only; never sent to the MoCode server).
- **Default model:** `deepseek-flash` (DeepSeek). Set provider keys with **`/keys`** → `~/.mocode/keys.json` (local only; never sent to the MoCode server).
- **Why not Cerebras/Groq:** those endpoints answer `403 Forbidden` from networks where the provider is region-blocked. DeepSeek is reachable without a proxy; use `/models` to switch.
- **`/models` hints:** *Free recommended* / *Free OK* / *Weak tool calling* — avoid weak-tool models for `/explore` and other multi-tool turns.
- **Free-tier picks:** Cerebras `gpt-oss-120b` or Groq `openai/gpt-oss-120b`. Groq Llama ids often malform tool calls in subagent loops.
- **Free-tier picks:** Cerebras `gpt-oss-120b` or Groq `openai/gpt-oss-120b` (only where those APIs are reachable). Groq Llama ids often malform tool calls in subagent loops.

Smoke-test server `.env` keys: `bun run packages/server/scripts/test-providers.ts`

Expand Down
12 changes: 8 additions & 4 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ MoCode 是一个基于 Bun 的 monorepo,由功能丰富的 **TUI 客户端**
|---|---|
| **双 Agent 模式** | **Plan** — 只读探索与架构分析。**Build** — 完整读写/bash 工具集,用于实现代码。 |
| **本地工具执行** | 服务端定义工具契约,CLI 在 `process.cwd()` 下执行,并做路径沙箱隔离。 |
| **多模型支持** | Anthropic、OpenAI、Google、Groq、Cerebras、OpenRouter — 会话中随时用 `/models` 切换。 |
| **多模型支持** | Anthropic、OpenAI、Google、Groq、Cerebras、OpenRouter、DeepSeek — 会话中随时用 `/models` 切换。 |
| **会话持久化与恢复** | PostgreSQL(SaaS)或本地 JSON(`--local`)。Esc 保留 partial 正文;工具执行中 Esc 标记 `Interrupted by user` 并立即停止;末条 user 重开自动续写;partial 助手需 `/resume`(regenerate)。详见 [会话恢复](#会话恢复)。 |
| **富 TUI 界面** | 基于 [OpenTUI](https://github.com/opentui/opentui) + React 19 — 主题、对话框、键盘层与斜杠命令。 |
| **OAuth 登录** | 通过 Clerk 的浏览器 PKCE 流程;Token 保存在 `~/.mocode/auth.json`。 |
Expand Down Expand Up @@ -148,6 +148,7 @@ mocode
| `GROQ_API_KEY` | 服务端 | Groq API Key |
| `CEREBRAS_API_KEY` | 服务端 | Cerebras API Key |
| `OPENROUTER_API_KEY` | 服务端 | OpenRouter API Key |
| `DEEPSEEK_API_KEY` | 服务端 | DeepSeek API Key |
| `CLERK_SECRET_KEY` | 服务端 | Clerk Secret Key(认证) |
| `CLERK_PUBLISHABLE_KEY` | 服务端 | Clerk Publishable Key |
| `CLERK_FRONTEND_API` | CLI | Clerk Frontend API 域名 |
Expand Down Expand Up @@ -232,16 +233,19 @@ macOS Terminal.app 可运行 `mocode --terminal-setup` 一次,启用 Option-as
| `llama-3.3-70b-versatile` | Groq(免费;工具调用不稳定) |
| `openai/gpt-oss-20b` | Groq(免费) |
| `openai/gpt-oss-120b` | Groq(免费) |
| `gpt-oss-120b` | Cerebras(BYOK 默认;免费推荐) |
| `gpt-oss-120b` | Cerebras(免费推荐) |
| `openai/gpt-oss-120b:free` | OpenRouter |
| `deepseek-flash` | DeepSeek(**默认**;1M 上下文;国内可直连) |
| `deepseek-v4-pro` | DeepSeek(更强,价格约为 4 倍) |

权威列表见 `packages/shared/src/models.ts`。

### BYOK(`mocode --local`)

- **默认模型:** `gpt-oss-120b`(Cerebras)。用 **`/keys`** 写入 `~/.mocode/keys.json`(仅存本机,不上传服务端)。
- **默认模型:** `deepseek-flash`(DeepSeek)。用 **`/keys`** 写入 `~/.mocode/keys.json`(仅存本机,不上传服务端)。
- **为什么不用 Cerebras/Groq:** 在厂商按地区封锁的网络里,这两个端点会返回 `403 Forbidden`。DeepSeek 可直连;用 `/models` 切换。
- **`/models` 标注:** *免费推荐* / *免费可用* / *工具调用不稳定* — `/explore` 等多工具场景请避开不稳定项。
- **免费档推荐:** Cerebras `gpt-oss-120b` 或 Groq `openai/gpt-oss-120b`。Groq Llama 系列在子代理多步 tool loop 中易格式错误。
- **免费档推荐:** Cerebras `gpt-oss-120b` 或 Groq `openai/gpt-oss-120b`(仅在这两家可达的网络下)。Groq Llama 系列在子代理多步 tool loop 中易格式错误。

冒烟测试服务端 `.env` Key:`bun run packages/server/scripts/test-providers.ts`

Expand Down
4 changes: 2 additions & 2 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading