CodeShell is one orchestration engine wearing three faces:
a terminal CLI (code-shell) for interactive and headless agent runs,
an Electron desktop app with chat, file/browser/terminal/diff panels, model & credential management, an extensions marketplace, automation, and a phone remote, and
a () for embedding the engine in your own product.
The core is deliberately domain-agnostic. The turn loop, context management, permissions, MCP integration, hooks, tasks, cron, sub-agents, sessions, and memory all stay generic. Coding tools, git/worktree behavior, LSP, review, quota, and coding prompts live in the physically separate @cjhyy/code-shell-capability-coding package and are composed by the CLI/Desktop hosts. (See packages/core/CONTRIBUTING.md: "core only carries mechanism, not policy.")
One engine, many products — the same runtime drives coding, research, automation, browser tasks, and long-running workflows. Behavior is expressed as presets and tools, not forked codebases.
Terminal-first, headless-ready, desktop-complete — run interactively in the terminal, fire one-shot headless jobs, or use the full visual desktop client.
Permission-aware by default — high-impact actions (writes, shell, git) sit behind explicit approval flows with session/project scoping and a bypass mode for trusted contexts.
Extensible end-to-end — presets, built-in tools, MCP servers, hooks, skills, plugins (CC- and Codex-format), sub-agents, and cron jobs are all first-class, with a desktop UI for discovering and installing them.
Local-first & private — sessions, transcripts, credentials, and memory live under ~/.code-shell/; credential files are written owner-only (0o600).
Quick start
CLI
# Default CLI preset: terminal coding assistant (interactive REPL)
npx @cjhyy/code-shell
# Run the same framework as a general orchestrator
npx @cjhyy/code-shell --preset general
# One-shot / headless execution
npx @cjhyy/code-shell run --preset general \
"Create a long-running research plan and track it with tasks"
Requires Node.js >= 20.10.
Desktop app
The desktop app (packages/desktop) is an Electron client. To run it from source:
bun install
bun run dev # launches the desktop app in dev mode
It gives you chat with streaming output, a side-by-side file / browser / terminal / diff panel dock, model & credential management, an extensions marketplace, automation/cron scheduling, persistent goals, memory, and a phone remote — all driving the same core engine via per-session agent worker processes.
Desktop preview
Features
Core engine (@cjhyy/code-shell-core)
Turn-based agent loop with streaming output and step-by-step lifecycle events
Context compaction (tool-pair-preserving) and durable session persistence on disk
Permission-gated tool execution with session/project rule caching and chained-command guards
Hook pipeline (user + project + plugin hooks) and full MCP client integration
First-class tasks, sub-agents, cron, and sleep for long-running and self-pacing workflows
Persistent goals with a stop-hook judge and explicit complete_goal declaration
Memory + Dream: per-turn memory injection plus an LLM consolidation pass
Unified model catalog: text / image / video providers under one tag-based config, with per-model parameter definitions that drive both UI controls and tool descriptions
Background shell jobs, cost tracking, and turn-level file undo/redo
Presets
Preset
Purpose
Extra tools
harness-min
Domain-neutral core default for embedding
Minimal filesystem, shell, MCP, memory, task and agent mechanisms
general
General orchestration, research, automation, long-running work
Shift+Tab permission-mode cycling, transcript browsing, session resume, and cost/usage reporting
Desktop app (@cjhyy/code-shell-desktop)
Chat with streaming, image attachments (upload/drag/paste), and a run-time steering/queue model (queue = non-interrupting step-gap insertion; "steer" = interrupt-and-resend)
Panel dock alongside the conversation: read-only Files panel, Browser panel (CDP-driven, with selection-anchor sync), interactive Terminal (node-pty), and a Diff/Review panel
Model catalog & connections: full CRUD over providers/models, credential reuse by company, and parameter docs surfaced into tool descriptions
Credentials: API keys, browser-cookie login (with a dedicated login window for sites the embedded webview can't handle), multi-account cookie credentials, and permission token/link gates
Extensions: plugin/skill/MCP management + a marketplace (installs CC- and Codex-format plugins, including from uploaded archives), a capability overview, and sub-agent (Agent role) management
Automation: cron/scheduled tasks with read-only contract enforcement, per-task transcripts and memory, and a runs view for long tasks
Mimi follow-ups: register reminders or explicitly authorized continuation of the original task, inspect the next time, reschedule, and cancel in one Needs follow-up list; recall memories by the current question and actual task objectives
Persistent goals, memory management (pin/edit/clear, manual Dream), hooks configuration, and full i18n (Chinese / English)
Phone remote: control a desktop session from a mobile web app over a local WebSocket
For example, ask Mimi to remind you tomorrow at 10 AM without creating a work Session. Continuing work requires explicit authorization. Wakes run while the desktop app is open; after restart, the default catch-up window is 24 hours after the scheduled time. Expired items retain their failure reason, and uncertain sends or launches are never replayed automatically.
Built-in tools
Core by itself defaults to the minimal harness-min preset. The CLI and Desktop
compose the coding capability package, whose host default is terminal-coding.
Runtime guards may hide tools that
need unavailable providers, credentials, cookies, or an active goal.
Everything is exported from the package root — import { ... } from "@cjhyy/code-shell" (or directly from @cjhyy/code-shell-core). There are no /run, /arena, or /product subpath entry points.
Runnable SDK examples live in examples/ — each runs directly
with bun run <file> and supports --dry-run (scripted mock LLM) when no API
key is configured:
CodeShell's terminal UI defaults to fullscreen (alt-screen + ScrollBox) — the mode where window resize repaints cleanly. Flow mode can show duplicate content in scrollback after a resize because the terminal pushes the old viewport up before CodeShell can erase it.
Opt out at startup with CODESHELL_FULLSCREEN=0|false|off, or toggle at runtime with /fullscreen off. Flow mode lets the transcript flow into the terminal's native scrollback (useful if you prefer keeping shell history above CodeShell visible).
Stream idle watchdog (on by default)
The OpenAI-compatible provider aborts any LLM stream idle for CODESHELL_STREAM_IDLE_TIMEOUT_MS ms (default 90000) without a chunk, then retries via the existing withRetry policy, capped by CODESHELL_STREAM_WATCHDOG_RETRIES (default 2). This bounds upstream hangs at ~90 s instead of indefinitely. Set CODESHELL_ENABLE_STREAM_WATCHDOG=0 to opt out. User-initiated aborts (Esc / Ctrl+C) are never retried.
Architecture
At a high level, CodeShell routes CLI, headless, SDK, and desktop clients through the same engine runtime:
Preset resolution selects the system prompt, built-in tools, and permission defaults.
Capability composition lets products install their own tools, presets, prompt sections, file-history behavior, and session-workspace adapters without putting product policy in core.
TurnLoop coordinates model streaming, context assembly, tool execution, and lifecycle events.
Tool system hosts built-ins, MCP tools, permissions, hooks, and cancellation.
Session / run layers persist transcripts, state, tasks, automation runs, and memories.
In the desktop app, the Electron main process acts as an IPC service layer: it does not run the Engine itself but spawns a per-session core agent worker, streams its stdout back to the renderer, and provides system capabilities (files, terminal, credentials, plugins, browser automation host, memory). The renderer is a thin client that talks to main only through window.codeshell.*.
Design principles:
Core first — the orchestration engine stays domain-agnostic.
Capabilities over hardcoding — coding behavior lives in a separate package composed at the host boundary.
Secure by default — permission-gated actions and explicit approval flow; owner-only credential files.
Long-running ready — tasks, cron, sleep, sub-agents, and persistent goals are first-class.
bun install
bun run build # build link + core + capability/host packages + meta package
bun run typecheck # root core + coding capability + tui + chat check
bun test # core / tui test suites
# Desktop has its OWN typecheck and build (the root checks do NOT cover it):
cd packages/desktop
bun run typecheck
bun run build
Current caveat: bun run typecheck at the repository root still reports pre-existing test-source typing diagnostics. The package builds and Desktop typecheck above are the clean gates for this change.
bun run dev launches the desktop app. For the TUI in dev: bun run dev:tui.
The desktop renderer uses shadcn/ui + Tailwind v4 (zinc theme) and imports no core code — it is a thin client over window.codeshell.*. See packages/desktop/CLAUDE.md for renderer conventions.
The ApplyPatch tool (packages/coding/src/tools/apply-patch/) is adapted from
OpenAI Codex codex-rs/apply-patch,
licensed under the Apache License 2.0. See NOTICE.md and LICENSE-codex in that directory
for details, including the intentional behavioral divergence where our applier rolls back
partial writes on failure.