diff --git a/README.md b/README.md
index 77e98097..cce863e3 100644
--- a/README.md
+++ b/README.md
@@ -7,47 +7,56 @@
### **Think it. Code it.**
+
- 
+
-**The AI coding agent that lives in your terminal.**
+**The AI coding agent that lives in your terminal โ and now on your desktop.**
-Describe tasks in plain language. [J]CODE reads your codebase, writes surgical edits,
-runs commands, and shows every step โ no black boxes.
+Describe a task in plain language. [J]CODE reads your codebase, writes surgical edits,
+runs commands, and shows every step โ no black boxes. Use it in your terminal, a
+browser, or a native desktop app. Work locally or on a remote box over SSH or Docker.
+Bring any OpenAI-compatible model.
-Works locally and on remote servers over SSH. Supports any OpenAI-compatible model.
+
+ 
+ 
+ 
+ 
+ 
+
-[๐ Documentation](https://cnjack.github.io/jcode) ยท [Install](#install) ยท [Features](#features) ยท [Configuration](#configuration) ยท [Changelog](#changelog)
+[๐ Documentation](https://cnjack.github.io/jcode) ยท [Install](#install) ยท [Features](#features) ยท [Interfaces](#interfaces) ยท [Configuration](#configuration) ยท [Changelog](#changelog)
---
-
- 
+
## Why jcode?
-| | |
-| ------------------------- | ------------------------------------------------------------------------------ |
-| **Transparent by design** | Every tool call is visible. Approve or reject edits before they happen. |
-| **Plan before you act** | Plan Mode explores read-only and presents a structured plan for your review. |
-| **Parallel teams** | Spawn multiple AI teammates that work simultaneously on different tasks. |
-| **SSH anywhere** | All tools work seamlessly on remote machines โ same experience, zero friction. |
-| **Bring your own model** | Any OpenAI-compatible API. Switch models mid-session with one keystroke. |
+| | |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| **Transparent by design** | Every tool call is visible. Approve or reject edits before they happen. |
+| **Plan before you act** | Plan Mode explores read-only and presents a structured plan for your review. |
+| **Parallel teams** | Spawn multiple AI teammates that work simultaneously on different tasks. |
+| **Runs anywhere** | Terminal, browser, or native desktop app โ one engine, same experience. |
+| **Local or remote** | Every tool works identically over SSH or inside a Docker container. |
+| **Bring your own model** | Any OpenAI-compatible API. Switch models mid-session with one keystroke. |
## Install
-### Quick Install (recommended)
+### Quick install (recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/cnjack/jcode/main/script/install.sh | sh
```
-### From Source
+### From source
Requires **Go 1.22+** and **Node.js + pnpm**.
@@ -57,39 +66,81 @@ cd jcode
make install
```
+First launch creates `~/.jcode/config.json` with a setup wizard. Run `jcode doctor`
+to verify model & MCP connectivity.
+
+### First commands
+
+```bash
+jcode # start an interactive session
+jcode -p "fix the failing test in ./auth" # one-shot, non-interactive
+jcode --resume # pick up a previous session
+jcode web # browser UI at http://localhost:8080
+```
+
### Update
```bash
jcode update
```
-> **Windows users:** Windows locks the running `.exe` and prevents any file operation on it (including rename). `jcode update` will download the new version to `.new` instead. Follow the printed instructions to exit jcode and manually replace the binary (e.g. `move /Y "jcode.exe.new" "jcode.exe"`).
-
-First launch creates `~/.jcode/config.json` with a setup wizard. Run `jcode doctor` to verify model & MCP connectivity.
+> **Windows users:** Windows locks the running `.exe` and blocks any file operation on it (including rename). `jcode update` downloads the new version to `.new` instead โ follow the printed instructions to exit jcode and swap the binary (e.g. `move /Y "jcode.exe.new" "jcode.exe"`).
## Features
-### Core Agent Loop
+### Core agent loop
-Describe a task in plain English. The agent reads your codebase, writes surgical edits, runs commands, and reports every step โ no black boxes.
+Describe a task in plain English. The agent reads your codebase, writes surgical edits, runs commands, and reports every step.
-| Capability | How it works |
-| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| Capability | How it works |
+| ------------------- | ----------------------------------------------------------------------------------------------------- |
| **File operations** | Read, edit (string-level diffs), and write files with inline before/after display |
-| **Shell execution** | Run any command; output shown in a bordered box. Safe commands (`ls`, `git status`, โฆ) auto-approved |
-| **Regex search** | `grep` tool with ripgrep fallback โ search across entire codebases in seconds |
-| **Todo tracking** | Live `๐ Todo (2/5)` bar above the input area; agent updates progress automatically |
-| **Ask user** | Agent can prompt you with questions and choices mid-task when it needs clarification |
+| **Shell execution** | Run any command; output shown in a bordered box. Safe commands (`ls`, `git status`, โฆ) auto-approved |
+| **Regex search** | `grep` tool with ripgrep fallback โ search across entire codebases in seconds |
+| **Todo tracking** | Live `๐ Todo (2/5)` bar above the input; the agent updates progress automatically |
+| **Ask user** | The agent can stop and ask you a question with choices mid-task when it needs clarification |
-### ๐ค Agent Teams
+### ๐ Modes โ Ask for approval ยท Plan ยท Full access
+
+Press **Shift+Tab** to cycle the session mode:
+
+- **Ask for approval** (default) โ full tools, but you approve each non-trivial tool call.
+- **Plan** โ the agent explores your codebase **read-only** and presents a structured plan before touching any file. Approve or reject with feedback โ then it executes step by step.
+- **Full access** โ full tools, every call auto-approved, end-to-end with no interruptions.
+
+```
+ Plan โ Model: openai / gpt-4o โ [โโโโโโโโโโ] 12%
+```
+
+### ๐ค Agent teams
Spawn multiple AI teammates that work **in parallel**, each with independent tools, conversation history, and environment. The lead agent coordinates; teammates idle until they receive an explicit message.
- 
+
-### ๐ SSH โ work on any machine
+### ๐ฏ Session goals
+
+Set a persistent objective and let the agent keep working toward it across turns โ it auto-continues until the goal verifiably completes, marks itself blocked, or hits a safety cap. A ๐ฏ indicator shows an active goal.
+
+```
+ You โบ /goal ship the new /export endpoint with tests and docs
+
+ ๐ฏ Goal set ยท the agent will keep going until it's done
+
+ You โบ /goal status # check progress
+ You โบ /goal clear # drop the goal
+```
+
+### ๐จ Themes
+
+Seven built-in color themes, defined once and rendered identically in the terminal **and** the web UI. Type `/theme` in the TUI for a live-preview picker (arrow keys repaint the whole UI, Enter persists); the web Appearance tab adds a System (follow-OS) option.
+
+- **Dark:** jcode Dark (default), Midnight, Dracula, Nord
+- **Light:** jcode Light, GitHub Light, Solarized Light
+
+### ๐ SSH & Docker โ work on any machine
Type `/ssh user@host` and every tool runs transparently on the remote host. No agents, no tunnels, no extra setup.
@@ -103,8 +154,8 @@ Type `/ssh user@host` and every tool runs transparently on the remote host. No a
โ Tool execute [deploy@10.0.1.5] docker logs app-nginx-1 --tail 20
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
- โ nginx: [emerg] bind() to 0.0.0.0:80 failed โ
- โ (98: Address already in use) โ
+ โ nginx: [emerg] bind() to 0.0.0.0:80 failed โ
+ โ (98: Address already in use) โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ Port 80 is already taken. Let me find what's holding it.
@@ -114,27 +165,21 @@ Save connections as named aliases and jump between hosts with `/ssh`:
```
โโโโโโโโ /ssh โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ > ๐ prod deploy@10.0.1.5:/var/www/app โ
- โ ๐ staging ci@10.0.1.8:/srv/staging โ
- โ โ Connect New SSH โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ โ > ๐ prod deploy@10.0.1.5:/var/www/app โ
+ โ ๐ staging ci@10.0.1.8:/srv/staging โ
+ โ โ Connect New SSH โ
+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
-### ๐ Modes โ Ask for approval ยท Plan ยท Full access
+In the web UI you can also bind a task to a **Docker container** โ every file and command runs inside it via `docker exec`, and the embedded terminal opens a real TTY in the container. Saved Docker aliases live in `docker_aliases`.
-Press **Shift+Tab** to cycle the session mode:
+### โฑ Automations
-- **Ask for approval** (default) โ full tools, but you approve each non-trivial tool call.
-- **Plan** โ the agent explores your codebase **read-only** and presents a structured plan before touching any file. Review, approve or reject with feedback โ then it executes step by step.
-- **Full access** โ full tools, every call auto-approved, end-to-end with no interruptions.
+Schedule agent tasks to run on a **cron schedule** or fire them **manually** from the web UI. Each run is a normal jcode session, just tagged and tracked โ so you get the full transcript, tool calls, and approvals for every run.
-```
- Plan โ Model: openai / gpt-4o โ [โโโโโโโโโโ] 12%
-```
-
-### ๐ MCP Integration
+### ๐ MCP integration
-Connect any [MCP](https://modelcontextprotocol.io/)-compatible server โ stdio, HTTP, or SSE โ and its tools merge with the built-ins. Auto-reconnect with exponential backoff. Status shown live in the status bar.
+Connect any [MCP](https://modelcontextprotocol.io/)-compatible server โ stdio, HTTP, or SSE โ and its tools merge with the built-ins. OAuth-protected servers are supported (built-in login flow). Auto-reconnect with exponential backoff; status shown live in the status bar.
```json
{
@@ -149,7 +194,11 @@ Connect any [MCP](https://modelcontextprotocol.io/)-compatible server โ stdio,
Ask for approval โ Model: openai / gpt-4o โ [โโโโโโโโโโ] 2% โ MCP: 2/5
```
-### ๐ฐ Token Usage & Budget Control
+### ๐ Skills
+
+Domain-specific skills loaded on demand and exposed as slash commands. Built-in skills include **PR review** (`/review-pr`), **security review** (`/security-review`), **PR comments** (`/pr-comments`), and **submit PR** (`/submit-pr`). Drop your own skill packs in `~/.jcode/skills/` or `/.jcode/skills/` and they register automatically.
+
+### ๐ฐ Token usage & budget control
Real-time context window tracking with a **color-coded progress bar** in the status bar:
@@ -170,28 +219,23 @@ Set cost guardrails in `config.json`:
}
```
-The agent receives in-context warnings when nearing limits and stops if the budget is exceeded. Model pricing is auto-fetched from [models.dev](https://models.dev).
+The agent receives in-context warnings near limits and stops if the budget is exceeded. Model pricing is auto-fetched from [models.dev](https://models.dev).
-### ๐ง Context Management
+### ๐ง Context management
- **Auto-compaction** โ when the context window fills up, older conversation is summarized while preserving the most recent messages
- **Manual compaction** โ type `/compact` anytime to free up context
+- **1M-context support** โ per-model context windows resolve from config โ registry โ fallback, so large-window models aren't capped at 200K
- **Smart prompt caching** โ reduces redundant prompt computation across turns
-- **AGENTS.md support** โ global (`~/.jcode/AGENTS.md`), project-level, and local (`.local.md`, git-ignored) agent instructions with `@include` directives
-
-### ๐ Skills
+- **AGENTS.md support** โ global (`~/.jcode/AGENTS.md`), project-level, and local (`.local.md`, git-ignored) instructions with `@include` directives
-Domain-specific skills loaded on demand. Built-in skills include **PR review** and **security review**. Add your own skill packs to `~/.jcode/skills/` or `/.jcode/skills/`.
-
-Skills register as slash commands โ type `/review-pr` or `/security-review` to activate.
-
-### โก Subagents & Background Tasks
+### โก Subagents & background tasks
- **Subagents** โ delegate subtasks to independent child agents (`explore`, `general`, or `coordinator` type) with up to 3 levels of nesting
- **Background commands** โ long-running builds/tests run async; check with `/bg` or the `check_background` tool
-- **Status tracking** โ `Bg: 3 running` shown in status bar; task IDs for programmatic access
+- **Status tracking** โ `Bg: 3 running` shown in the status bar; task IDs for programmatic access
-### ๐ผ Session Resume
+### ๐ผ Session resume
Every conversation is recorded as JSONL. Resume any past session:
@@ -199,8 +243,8 @@ Every conversation is recorded as JSONL. Resume any past session:
โโโโโโโโโโโโโโโโโ Resume Session โโโโโโโโโโโโโโโโโโ
โ > 2026-03-12 gpt-4o fix nginx crash โ
โ 2026-03-11 gpt-4o refactor auth module โ
- โ 2026-03-10 claude-3.5 add pagination logic โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ โ 2026-03-10 o4-mini add pagination logic โ
+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
```bash
@@ -208,79 +252,128 @@ jcode sessions # list sessions
jcode --resume # pick up where you left off
```
-### ๐ Web Interface
+### ๐งญ Context awareness
+
+At startup the agent automatically detects your Git branch, dirty status and last commit, the project type (Go, Python, JS, Rust, Java, โฆ), the directory structure, the SSH/Docker environment, and available skills โ no manual configuration needed.
+
+## Interfaces
+
+Same engine, four front ends โ pick whatever fits the moment.
+
+### Terminal (default)
+
+The full TUI: `jcode`. Everything above lives here.
-Start a browser-based UI with `jcode web`. Chat interface, file browser, built-in terminal, and full agent control โ all accessible from `http://localhost:8080`.
+### ๐ Web
+
+Start a browser-based UI with `jcode web`. Chat, file browser, built-in terminal, and full agent control at `http://localhost:8080`. Light and dark themes; remote-connect wizard for SSH and Docker.
- 
+
-### ๐ฅ Desktop App
+### ๐ฅ Desktop
+
+A native desktop app (built with [Tauri](https://tauri.app)) wraps the **same** web UI in a real OS window with native integration: OS notifications, a menu-bar tray, close-to-tray, single-instance focus, window-state memory, a global show/hide shortcut, and a native folder picker. The Go backend runs as an embedded sidecar โ no separate server to start.
-A native desktop app (built with [Tauri](https://tauri.app)) wraps the same web UI in a real OS window with native integration: OS notifications, a menu-bar tray, close-to-tray, single-instance focus, window-state memory, and a native folder picker. The Go backend runs as an embedded sidecar โ no separate server to start.
+
+ 
+
```bash
-make desktop-dev # run the app in development
+make desktop-dev # run the app in development (rebuilds the sidecar first)
make desktop-build # build a distributable bundle (.app/.dmg/.msi)
```
-See the [Desktop App guide](https://cnjack.github.io/jcode/desktop) for the architecture and details.
+> Building the desktop app additionally needs the [Rust toolchain](https://rustup.rs) (and, on Linux, the [Tauri system dependencies](https://v2.tauri.app/start/prerequisites/)).
-### ๐งญ Context Awareness
+See the [Desktop App guide](https://cnjack.github.io/jcode/desktop) for the architecture and security model.
-At startup the agent automatically detects:
+### Editor (ACP)
-- Git branch, dirty status, last commit
-- Project type (Go, Python, JS, Rust, Java, โฆ)
-- Directory structure
-- SSH environment labels
-- Available skills
+jcode also speaks the Agent Client Protocol (ACP), so it runs inside ACP-compatible editors like [Zed](https://zed.dev) via `jcode acp`.
-No manual configuration needed โ the agent adapts to your project.
+## Reference
-## Keyboard Shortcuts
+### CLI commands
-| Key | Action |
-| ------------- | --------------------------------- |
-| **Enter** | Submit prompt / select option |
-| **Ctrl+C** | Press once to warn, twice to exit |
-| **Shift+Tab** | Cycle mode (Ask for approval โ Plan โ Full access) |
-| **Ctrl+L** | Model picker |
-| **Ctrl+T** | Toggle team panel |
-| **Shift+โ/โ** | Switch between teammates |
-| **Esc** | Return to leader view |
-| **/** | Start slash command |
-
-## Slash Commands
+```bash
+jcode # interactive session (root command)
+jcode -p "" # one-shot, non-interactive
+jcode --resume # resume a session by UUID
+jcode web # browser UI
+jcode acp # run as an ACP agent for editors
+jcode mcp # manage MCP servers
+jcode automation # manage automations
+jcode sessions # list saved sessions
+jcode doctor # verify model + MCP connectivity
+jcode version # version, commit, build time
+jcode update # update to the latest release
+```
-| Command | Action |
-| ---------- | ---------------------------- |
-| `/model` | Switch model mid-session |
-| `/setting` | Open settings menu |
-| `/ssh` | Connect to SSH host |
-| `/resume` | Resume a previous session |
-| `/compact` | Compact conversation context |
-| `/bg` | Check background tasks |
-| `/` | Activate a loaded skill |
+### Slash commands
+
+| Command | Action |
+| ----------------- | ------------------------------------------------------- |
+| `/model` | Switch model mid-session |
+| `/setting` | Open the settings menu |
+| `/theme` | Open the theme picker (live preview) |
+| `/goal` | Set, check (`status`), or `clear` the session goal |
+| `/ssh` | Connect to an SSH host |
+| `/mcp` | Manage MCP server connections |
+| `/resume` | Resume a previous session |
+| `/compact` | Compact the conversation context |
+| `/bg` | Check background tasks |
+| `/channel` | Manage messaging channel connections |
+| `/help` | Show keyboard shortcuts and command help |
+| `/` | Run a loaded skill (e.g. `/review-pr`, `/security-review`) |
+
+
+Keyboard shortcuts
+
+| Key | Action |
+| -------------- | --------------------------------------------------- |
+| **Enter** | Submit prompt / select option |
+| **Shift+Enter**| Insert a newline |
+| **Ctrl+C** | Press once to warn, twice to exit |
+| **Shift+Tab** | Cycle mode (Ask for approval โ Plan โ Full access) |
+| **Ctrl+L** | Model picker |
+| **Ctrl+T** | Toggle the team panel |
+| **Shift+โ / โ**| Switch between teammates |
+| **Esc** | Dismiss command suggestions / return to leader view |
+| **Ctrl+E** | Expand / collapse subagent output |
+| **Ctrl+Y** | Copy the last assistant message |
+| **Ctrl+โ / โ** | Scroll the sidebar todo list |
+| **/** | Start a slash command |
+| **? / F1** | Open the keyboard-shortcuts help |
+
+
## Configuration
Config lives at `~/.jcode/config.json`. Key sections:
-| Section | What it controls |
-| ----------------------- | ------------------------------------------------- |
-| `providers` | API keys and base URLs for each model provider |
-| `model` / `small_model` | Active model and lightweight model for summaries |
-| `fallback_model` | Fallback when primary model fails |
-| `ssh_aliases` | Named SSH connections |
-| `mcp_servers` | MCP server definitions (stdio / HTTP / SSE) |
-| `budget` | Token and cost limits per session |
-| `compaction` | Auto-compaction threshold, recent message count |
-| `prompt` | Memory size, cache, async env timeout |
-| `subagent` | Parallel limit, nesting depth |
-| `team` | Max teammates, mailbox poll interval |
-| `telemetry` | Optional [Langfuse](https://langfuse.com) tracing |
+| Section | What it controls |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `providers` | API keys, base URLs, headers, and custom models per provider |
+| `model` / `small_model` | Active model and the lightweight model used for summaries/compaction |
+| `fallback_model` | Model to fall back to when the primary fails |
+| `default_mode` | Startup session mode: `approval` (default), `plan`, or `full_access` |
+| `theme` | Built-in color theme name; empty auto-selects from the terminal background |
+| `context_limits` | Per-model context-window overrides (tokens) |
+| `default_context_limit` | Fallback context window for unknown models (default `200000`) |
+| `max_iterations` | Maximum agent-loop iterations per turn |
+| `ssh_aliases` | Named SSH connections |
+| `docker_aliases` | Named Docker container workspaces |
+| `mcp_servers` | MCP server definitions (stdio / HTTP / SSE, headers, OAuth) |
+| `budget` | Token and cost limits per session |
+| `compaction` | Auto-compaction threshold and recent-message count |
+| `prompt` | Memory size, prompt cache, async env timeout |
+| `subagent` | Parallel limit and nesting depth |
+| `team` | Max teammates and mailbox poll interval |
+| `channel` | External messaging channel settings |
+| `disabled_providers` / `disabled_skills` | Providers / skills to exclude |
+| `telemetry` | Optional [Langfuse](https://langfuse.com) tracing |
```bash
jcode doctor # verify model + MCP connectivity
@@ -290,7 +383,7 @@ jcode update # update to latest version
## Documentation
-๐ Full documentation is available at [cnjack.github.io/jcode](https://cnjack.github.io/jcode)
+๐ Full documentation is available at [cnjack.github.io/jcode](https://cnjack.github.io/jcode).
## Changelog
diff --git a/docs/asset/agent-team-screnshot.png b/docs/asset/agent-team-screnshot.png
index 10778bdc..fd7caf34 100644
Binary files a/docs/asset/agent-team-screnshot.png and b/docs/asset/agent-team-screnshot.png differ
diff --git a/docs/asset/desktop-screenshot.png b/docs/asset/desktop-screenshot.png
new file mode 100644
index 00000000..e475bde8
Binary files /dev/null and b/docs/asset/desktop-screenshot.png differ
diff --git a/docs/changelog.md b/docs/changelog.md
index 526aa402..855fd558 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -12,8 +12,19 @@ For the **full changelog**, see [CHANGELOG.md](../CHANGELOG.md) in the repositor
## Unreleased
#### Added
-- **CI quality gate** (`.github/workflows/ci.yml`): Go `build`/`vet`/`test` + golangci-lint (new-issue gating) and web type-check/lint/build run on every push to `main` and every pull request.
-- **Desktop bundles in the release pipeline.** `release.yml` now builds the Tauri desktop app for **macOS (Intel + Apple Silicon), Windows, and Linux** on native runners and attaches the `.dmg` / `.msi` / `.exe` / `.deb` / `.AppImage` installers (with checksums) to each GitHub Release alongside the CLI binaries. macOS code-signing/notarization is wired through optional `APPLE_*` secrets (unset โ unsigned build). See [Release & CI](release.html).
+- **Built-in color themes, unified across terminal and web.** A new single source of truth (`internal/theme`) defines 7 themes โ 4 dark (jcode Dark, Midnight, Dracula, Nord) and 3 light (jcode Light, GitHub Light, Solarized Light) โ as a typed semantic palette. `go generate` emits the web CSS (`[data-theme]` blocks) and the picker registry from that one Go file, so the two renderers can never drift.
+- **`/theme` command** in the TUI opens a live-preview selector: arrow keys repaint the whole UI, Enter applies and persists to `config.theme`, Esc reverts. When no theme is persisted, the startup default is auto-selected from the terminal background. New `theme` config field.
+- **Appearance settings tab** in the web UI: a System (follow-OS) option plus dark/light swatch grids that render a true mini-preview of each theme. Themes apply via `html[data-theme]`; the legacy light/dark/system localStorage values migrate automatically.
+- **Docker container workspaces (web).** The remote-connect wizard can now bind a task to a Docker container, alongside SSH. A new `DockerExecutor` (Docker Go SDK, `client.FromEnv` โ honors `DOCKER_HOST`) runs all agent file/command operations inside the container via `docker exec`, mirroring the SSH executor. A stopped container is started on connect and stopped again (ref-counted) once no task is using it; a one-shot container that exits immediately is reported with its logs rather than failing silently. The embedded terminal opens a real TTY *inside* the bound container (`docker exec`, bashโsh). Container-bound tasks are keyed `docker:///`, and the `switch_env` tool plus saved Docker aliases (`docker_aliases` in config) cover reconnects.
+
+#### Changed
+- Renamed the session modes to **Ask for approval / Plan / Full access** across the web UI, terminal UI, and ACP. Their canonical IDs are now `approval` / `plan` / `full_access`; the old `ask`, `agent`, and `autopilot` IDs are no longer accepted.
+- The terminal palette was de-frozen: the ~50 lipgloss styles that were baked in at import time are now rebuilt from the active theme by `ApplyTheme`, and previously-hardcoded colors (subagent purple, on-primary text, team-panel and context-bar colors) are now semantic tokens. Markdown (glamour) follows the theme's light/dark appearance.
+
+#### Fixed
+- TUI: pressing **Esc** while viewing a teammate now returns to the leader (the handler matched a key string that bubbletea never emits, so it was dead code).
+- TUI: the Cancel-agent confirmation now defaults to the non-destructive **Wait** button, matching the Quit dialog โ `Ctrl+C` then `Enter` no longer aborts a running agent by reflex.
+- TUI: **`?`** opens the keyboard-shortcuts help when the input is empty, and the help panel's slash-command list is now generated from the command registry (so `/goal`, skill commands, and `/theme` always appear).
---
@@ -589,4 +600,4 @@ All releases maintain backward compatibility with existing configurations and wo
---
-*Last updated: May 23, 2026*
+*Last updated: June 13, 2026*
diff --git a/docs/commands.md b/docs/commands.md
index 5914f5df..23d998c0 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -20,6 +20,16 @@ nav_order: 8
| `jcode sessions` | List recorded sessions for this project |
| `jcode mcp add ` | Add an MCP server |
| `jcode mcp list` | List configured MCP servers |
+| `jcode mcp login ` | Authenticate an existing http/sse MCP server via OAuth |
+| `jcode automation list` | List all automations |
+| `jcode automation show ` | Show an automation's definition and last run state |
+| `jcode automation templates` | List built-in automation templates |
+| `jcode automation enable ` | Enable an automation |
+| `jcode automation disable ` | Disable an automation |
+| `jcode automation delete ` | Delete an automation |
+
+{: .note }
+> `jcode automation` is also available as `jcode automations` or `jcode auto`. Definition management works standalone; periodic firing is owned by a running `jcode web` process.
### Flags
@@ -28,8 +38,6 @@ nav_order: 8
| `--prompt ` | `-p` | One-shot mode: run a single prompt and exit |
| `--resume ` | | Resume a previous session |
| `--unsafe` | | Auto-approve all tool calls |
-| `--doctor` | | Run system health check |
-| `--version` | | Print version info |
### Web Server Flags
@@ -37,6 +45,7 @@ nav_order: 8
|---|---|---|
| `--port` | 8080 | HTTP port for web interface |
| `--host` | 127.0.0.1 | Server bind address |
+| `--open` | true | Open browser after server starts |
### MCP Add Flags
@@ -45,6 +54,11 @@ nav_order: 8
| `--type` | `-t` | Server type: `sse`, `http`, or `stdio` (auto-detected) |
| `--header` | | HTTP header in `Key: Value` format (repeatable) |
| `--env` | | Environment variable in `KEY=VALUE` format (repeatable) |
+| `--scope` | `-s` | Config scope (`user`) |
+| `--oauth` | | Authenticate via OAuth after adding (http/sse only) |
+| `--client-id` | | OAuth client id (manual fallback when dynamic registration is unsupported) |
+| `--client-secret` | | OAuth client secret (confidential clients) |
+| `--scope-oauth` | | OAuth scope to request (repeatable) |
## Keyboard Shortcuts (TUI)
@@ -77,9 +91,13 @@ Type these in the TUI input area:
| `/compact` | Compact conversation context |
| `/goal` | Set a persistent objective the agent works toward ([Goals](goal.html)) |
| `/bg` | Show background tasks |
+| `/channel` | Open the channel management panel (WeChat push/messaging) |
+| `/mcp` | List MCP servers and status; `/mcp login ` to authenticate via OAuth |
+| `/help` | Show keyboard shortcuts help |
| `/review-pr` | Run PR review skill |
| `/pr-comments` | Fetch PR comments |
| `/security-review` | Run security review |
+| `/submit-pr` | Commit, push the branch, and open a GitHub pull request |
| `/` | Any skill with a slash command |
## One-Shot Mode
diff --git a/docs/configuration.md b/docs/configuration.md
index b01ef391..5633e81d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -55,12 +55,22 @@ jcode stores all configuration in a single JSON file at `~/.jcode/config.json`.
"small_model": "openai/gpt-4o-mini",
"fallback_model": "anthropic/claude-3-5-sonnet",
"max_iterations": 1000,
- "auto_approve": false,
+ "default_mode": "approval",
+
+ "context_limits": {
+ "openai/gpt-4o": 128000,
+ "my-custom-model": 256000
+ },
+ "default_context_limit": 200000,
"ssh_aliases": [
{ "name": "prod", "addr": "deploy@10.0.1.5", "path": "/var/www/app" }
],
+ "docker_aliases": [
+ { "name": "devbox", "container": "my-dev-container", "path": "/workspace" }
+ ],
+
"mcp_servers": {
"github": { "type": "stdio", "command": "gh-mcp" },
"db": { "type": "http", "url": "http://localhost:3001/mcp" }
@@ -137,6 +147,36 @@ Active model in `"provider/model"` format.
| `fallback_model` | Used when the primary model fails |
| `max_iterations` | Maximum agent iterations per turn (default: 1000) |
+### context_limits
+
+Per-model overrides for the context window size (in tokens). Use this to teach
+jcode the window of a brand-new or custom model the registry doesn't know yet.
+Keys may be `"provider/model"` (preferred) or a bare model id; the
+`"provider/model"` form is checked first.
+
+```json
+{
+ "context_limits": {
+ "openai/gpt-4o": 128000,
+ "my-custom-model": 256000
+ }
+}
+```
+
+An explicit `context_limits` entry takes precedence over the models.dev registry
+and built-in tables. When no override matches and the limit is still unknown,
+jcode falls back to [`default_context_limit`](#default_context_limit).
+
+### default_context_limit
+
+Fallback context window (in tokens) assumed when a model's limit can't be
+determined from `context_limits`, the models.dev registry, or the built-in
+tables. Default: `200000`.
+
+```json
+{ "default_context_limit": 200000 }
+```
+
### ssh_aliases
Named SSH connections for quick access.
@@ -147,6 +187,17 @@ Named SSH connections for quick access.
| `addr` | Connection address (`user@host[:port]`) |
| `path` | Remote working directory |
+### docker_aliases
+
+Named Docker container workspaces for quick access. Fields mirror
+[`ssh_aliases`](#ssh_aliases).
+
+| Field | Description |
+|---|---|
+| `name` | Alias name shown in the picker |
+| `container` | Container name or id |
+| `path` | Working directory inside the container |
+
### mcp_servers
MCP server definitions. See [MCP Integration](mcp).
@@ -200,10 +251,13 @@ The session mode jcode starts in: `"approval"` (default), `"plan"`, or `"full_ac
{ "default_mode": "approval" }
```
+{: .note }
+**Migration:** the old mode IDs `ask`, `agent`, and `autopilot` are no longer accepted โ use `approval`, `plan`, and `full_access` respectively. An unrecognized value falls back to `approval`.
+
### auto_approve
-{: .note }
-Deprecated โ superseded by [`default_mode`](#default_mode). Still honored as a fallback when `default_mode` is unset: `true` maps to `full_access`.
+{: .warning }
+Deprecated โ superseded by [`default_mode`](#default_mode) (`approval` / `plan` / `full_access`). Still honored only as a fallback when `default_mode` is unset: `true` maps to `full_access`. The old mode IDs `ask` / `agent` / `autopilot` are no longer accepted.
Set to `true` to auto-approve all tool calls. Equivalent to running with the `--unsafe` flag.
diff --git a/docs/overview.md b/docs/overview.md
index 52c24101..e2b2a1dc 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -26,6 +26,7 @@ jcode is an AI-powered coding agent that runs in your terminal. You describe tas
| **Interactive Questions** | The agent can ask you for clarification mid-task |
| **Plan Mode** | Explore read-only and present a plan before making changes |
| **SSH Remote** | Work on any machine over SSH โ same tools, same experience |
+| **Docker Workspaces** | Work inside a Docker container with the same tool coverage |
| **Agent Teams** | Spawn parallel AI teammates for complex tasks |
| **Subagents** | Delegate subtasks to independent child agents |
| **MCP Integration** | Connect any MCP-compatible server for extended capabilities |
@@ -34,6 +35,7 @@ jcode is an AI-powered coding agent that runs in your terminal. You describe tas
| **Channels** | Push notifications to WeChat when approval is needed or tasks complete |
| **JCode Buddy** | Physical desktop companion with pixel cat that reacts to your coding activity |
| **Skills** | Domain-specific skill packs loaded on demand |
+| **Color Themes** | 7 built-in themes (4 dark / 3 light) with live preview via `/theme` |
## Design Philosophy
diff --git a/docs/overview/models.md b/docs/overview/models.md
index 5bb84678..4ccd89fd 100644
--- a/docs/overview/models.md
+++ b/docs/overview/models.md
@@ -78,10 +78,46 @@ jcode supports different models for different purposes:
}
```
+## Reasoning & Extended Thinking
+
+For reasoning-capable models, jcode can control thinking depth via the OpenAI-compatible `reasoning_effort` parameter. Set it per provider in `~/.jcode/config.json`:
+
+```json
+{
+ "providers": {
+ "openai": {
+ "api_key": "sk-...",
+ "reasoning_effort": "medium"
+ }
+ }
+}
+```
+
+Accepted values are `"low"`, `"medium"`, and `"high"`. An empty string (or omitting the key) sends no effort parameter. The value is forwarded on every request; reasoning models honor it and others ignore it.
+
+For gateways that gate reasoning behind a chat-template flag (for example qwen3), set `thinking` to explicitly toggle extended reasoning. It is sent as the `chat_template_kwargs` `{"enable_thinking": }` extension:
+
+```json
+{
+ "providers": {
+ "my-gateway": {
+ "api_key": "...",
+ "base_url": "https://gateway.example.com/v1",
+ "thinking": true
+ }
+ }
+}
+```
+
+{: .note }
+Reasoning effort can also be chosen **per model** from the chat model picker. That choice is stored in `~/.jcode/model_state.json` (`effort_overrides`) and takes precedence over the provider-level `reasoning_effort`. It is applied consistently across the TUI, web, and ACP.
+
## Add a Provider at Runtime
jcode includes a setup wizard. Run it from the TUI with `/setting` โ "Add Model", or press Ctrl+L and select "Add new provider".
+In the web UI, providers and models are managed from a card-based **Settings** view: each provider is a card showing its brand, name, base URL, and a catalog of its models (built-in registry models toggle show/hide; custom models are editable or removable). Editing a provider or authoring a custom model opens a dedicated dialog. A custom model's editor exposes its ID, display name, context window, image-input toggle, and a reasoning-effort tier editor โ when a custom model is flagged as reasoning, the standard `minimal` / `low` / `medium` / `high` effort levels are offered, or you can define your own tiers. Models advertising effort levels then expose the per-model reasoning-effort control in the chat input.
+
## Verify Model Connectivity
```bash
diff --git a/docs/overview/skills.md b/docs/overview/skills.md
index b781ad21..8684f461 100644
--- a/docs/overview/skills.md
+++ b/docs/overview/skills.md
@@ -17,7 +17,7 @@ Skills use a **two-layer** loading system:
## Built-in Skills
-jcode includes three built-in skills:
+jcode includes four built-in skills:
### PR Review (`/review-pr`)
@@ -42,6 +42,17 @@ Performs a security-focused code review of pending changes on the current branch
- Remote code execution
- Data exposure
+### Submit PR (`/submit-pr`)
+
+Commits the current working changes, pushes the branch, and opens a GitHub pull request. It:
+
+- Checks for changes to submit and stops if there are none
+- Creates a feature branch first if you are on the default branch (`main`/`master`)
+- Commits with a Conventional Commit message and pushes the branch
+- Opens the PR with `gh pr create` and reports the PR URL
+
+It never force-pushes or pushes directly to the default branch.
+
{: .note }
The PR-related skills require the `gh` CLI tool to be installed and authenticated. Run `gh auth login` if you haven't already.
diff --git a/docs/tools.md b/docs/tools.md
index 0b17f406..c3d73627 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -34,12 +34,12 @@ Not all tool calls require your approval. jcode categorizes tools by risk:
| Category | Tools | Approval |
|---|---|---|
| **Read-only** | `read`, `grep`, `glob` | Auto-approved (within project) |
-| **Safe commands** | `ls`, `pwd`, `git status`, `git log` | Auto-approved |
+| **Safe commands** | `ls`, `pwd`, `cat`, `echo`, `which`, bare `env`, `git status`, `git log`, `git diff`, `git show` | Auto-approved (foreground only, no shell operators) |
| **Management** | `todowrite`, `todoread`, `ask_user` | Auto-approved |
-| **Delegation** | `subagent`, `check_background` | Auto-approved |
+| **Delegation** | `subagent`, `check_background`, `webfetch` | Auto-approved |
| **Team** | `team_create`, `team_spawn`, `team_send_message`, `team_list`, `team_delete` | Auto-approved |
| **File edits** | `edit`, `write` | **Require approval** |
-| **Commands** | `execute` (non-safe) | **Require approval** |
+| **Commands** | `execute` (non-safe, or any [background]({% link tools/execute.md %}) command) | **Require approval** |
| **Environment** | `switch_env` | **Require approval** |
When a tool requires approval (in **Ask for approval** mode), you see a dialog with the tool name and arguments. You can:
diff --git a/docs/tools/execute.md b/docs/tools/execute.md
index c4133394..e1422cbf 100644
--- a/docs/tools/execute.md
+++ b/docs/tools/execute.md
@@ -12,10 +12,16 @@ Run shell commands on your machine (or remote SSH host).
| Command Type | Approval |
|---|---|
-| Safe commands (`ls`, `pwd`, `env`, `cat`, `echo`, `which`, `git status`, `git log`) | Auto-approved |
-| Background tasks | Auto-approved |
+| Safe commands (`ls`, `pwd`, `cat`, `echo`, `which`, bare `env`, `git status`, `git log`, `git diff`, `git show`) | Auto-approved |
+| Background tasks | **Requires approval** |
| All other commands | **Requires approval** |
+{: .note }
+Safe commands are matched on the whole command word with no shell operators (`;`, `&`, `|`, `<`, `>`, `` ` ``, `$()`, `${}`, `()`). A "safe" prefix cannot smuggle a payload โ e.g. `git status && rm -rf /` is **not** auto-approved. Bare `env` (printing the environment) is safe, but `env CMD ...` runs `CMD` and is **not** safe.
+
+{: .warning }
+Background tasks always require approval. The `background` flag is agent-controlled, so auto-approving it would let any command bypass the gate by setting `background=true`.
+
## Basic Usage
```
diff --git a/docs/tools/task-management.md b/docs/tools/task-management.md
index df82bd47..55ad1df9 100644
--- a/docs/tools/task-management.md
+++ b/docs/tools/task-management.md
@@ -36,6 +36,29 @@ Read the current task list.
Returns the current todos with a summary count.
+## Goals
+
+A goal is a persistent, cross-turn objective. Once set, the agent keeps working
+toward it across turns โ when it would otherwise stop, it is automatically
+reminded to continue until the objective is verifiably complete or it hits the
+continuation cap. See [Goals]({% link goal.md %}) for the full workflow and the
+`/goal` command.
+
+These tools back the goal feature in every frontend (TUI, web, ACP):
+
+| Tool | What It Does |
+|---|---|
+| `goal_set` | Set or replace the session goal. Takes `objective` (a clear, self-contained description of the desired end state, max 4000 chars). Replacing a goal resets accounting. |
+| `goal_get` | Read the current goal โ its objective, status, and token usage. Takes no parameters. Returns `No goal set.` when none exists. |
+| `goal_update` | Mark the goal `complete` (objective verifiably done) or `blocked` (cannot proceed). Takes `status`. Either value stops the automatic continuation. |
+
+**Approval:** Require approval (in **Ask for approval** mode).
+
+A goal carries one of three statuses: `active` (the agent keeps working),
+`complete`, or `blocked`. The agent is instructed to mark `complete` only when
+the objective is verified against the real state of files, command output, or
+tests โ not its intent.
+
## Ask User
The agent can ask you questions when it needs clarification or a decision.
diff --git a/docs/automations-prd.md b/internal-doc/automations-prd.md
similarity index 99%
rename from docs/automations-prd.md
rename to internal-doc/automations-prd.md
index da658a3b..464b4db1 100644
--- a/docs/automations-prd.md
+++ b/internal-doc/automations-prd.md
@@ -2,7 +2,7 @@
> ็ถๆ๏ผ่ๆก **v2**๏ผ2026-06-23๏ผๅ
ณ้ฎๅณ็ญๅทฒๅฎ๏ผๅพ
ๅฎ็ฐ๏ผ
> ๅฏนๆ ๅฝขๆ๏ผAnthropic Claude Code ็ **Automations** โโ ็จ agent ๅค็ใๆ่ๅฅ / ๆๅจ่งฆๅใ็้ๅคๆงๅทฅไฝใ
-> ๅ
ณ่๏ผ[[web ไปปๅกๅๆถๆ]]๏ผ`docs/web-task-architecture.md`๏ผใGoal๏ผ`docs/goal.md`๏ผใMode ้ๆฉๅจ๏ผAsk/Plan/Autopilot๏ผใSkillsใMCPใ
+> ๅ
ณ่๏ผ[[web ไปปๅกๅๆถๆ]]๏ผ`internal-doc/web-task-architecture.md`๏ผใGoal๏ผ`docs/goal.md`๏ผใMode ้ๆฉๅจ๏ผAsk/Plan/Autopilot๏ผใSkillsใMCPใ
>
> v1โv2 ๅๆด๏ผโ ๅปๆไบไปถ/GitHub ่งฆๅ๏ผๅ
ไธ็ขฐ gh๏ผโกๅปๆ Effort/ๆจ็ๅๅบฆ โขๆฐๅข agent ๅฏ่ฐ็จ็ `automation_create` ๅทฅๅ
ท + ๆธฒๆๅก็ โฃ่ฐๅบฆๅจๅฎไธบใๆไปถ้้ไธปใโคๅญๅจๅฎไธบใflock ๅ้ + ๆๅๆๅ็ฆปใโฅ่ฟ่กๆถไธๅ ๆคๆ ๏ผๆฒฟ็จๆขๆๅฒๅญฆ๏ผใ
diff --git a/docs/web-task-architecture.md b/internal-doc/web-task-architecture.md
similarity index 100%
rename from docs/web-task-architecture.md
rename to internal-doc/web-task-architecture.md