@cjhyy/code-shell
Advanced tools
Code Shell — meta package. Installs @cjhyy/code-shell-core and @cjhyy/code-shell-tui.
A general-purpose AI agent orchestration framework — terminal, headless, and a full desktop app.
CodeShell is one orchestration engine wearing three faces:
code-shell) for interactive and headless agent runs,import { Engine } from "@cjhyy/code-shell") 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.")
Status: 0.6.x, entering beta. The desktop app is the headline product; the CLI and SDK share the same core engine.
bypass mode for trusted contexts.~/.code-shell/; credential files are written owner-only (0o600).# 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.
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.
@cjhyy/code-shell-core)complete_goal declaration| 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 | Core orchestration tools only |
terminal-coding | Terminal-native coding assistant | EnterWorktree, ExitWorktree, NotebookEdit, LSP, Brief |
Presets select the system prompt, the built-in tool set, and permission defaults. Configure via the SDK, the CLI --preset flag, or settings.
@cjhyy/code-shell-tui)run mode for one-shot execution, plus repl, sessions, and runs subcommands@-mention file/skill search, command auto-complete, and in-REPL cron schedulingShift+Tab permission-mode cycling, transcript browsing, session resume, and cost/usage reporting@cjhyy/code-shell-desktop)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.
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.
Read, Write, Edit, ApplyPatch, Glob, GrepBash, BashOutput, KillShell, ListShells, PowerShell, REPL, Sleepbrowser_observe, browser_act, browser_navigate, WebSearch, WebFetch, GenerateImage, GenerateVideoAskUserQuestion, AskUserQuestionAsync, EnterPlanMode, ExitPlanMode, ToolSearch, TodoWrite, Agent, AgentCancel, DriveAgent, DriveClaudeCode, CheckQuotaCronCreate, CronDelete, CronList, Config, Skill, AddMarketplace, InstallCapability, MCPTool, ListMcpResources, ReadMcpResource, EditModelCatalog, ConfigureModelConnectionMemoryList, MemoryRead, MemorySave, MemoryDelete, UseCredential, InjectCredential, complete_goal, cancel_goalEnterWorktree, ExitWorktree, NotebookEdit, LSP, BriefInstallCapability lets a conversation list, inspect, install, update, enable, disable, and
uninstall marketplace plugins, standalone project Skills, and MCP servers. MCP configuration
supports private-local, shared-project, and user-wide scopes; mutations and external Skill
repository inspection remain approval-gated.
The meta package re-exports the core engine, so legacy SDK imports keep working:
import { Engine } from "@cjhyy/code-shell";
const generalEngine = new Engine({
llm: {
provider: "openai",
model: "gpt-4.1",
apiKey: process.env.OPENAI_API_KEY,
},
preset: "general",
});
const codingEngine = new Engine({
llm: {
provider: "openai",
model: "gpt-4.1",
apiKey: process.env.OPENAI_API_KEY,
},
preset: "terminal-coding",
});
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:
examples/01-minimal-agent.ts — one Engine, one run, streamed outputexamples/02-approval-flow.ts — a custom ApprovalBackend gating tool callsexamples/03-in-process-transport.ts — the recommended createServer / createClient factory pairCLI preset selection:
npx @cjhyy/code-shell --preset general
npx @cjhyy/code-shell --preset terminal-coding
Settings-based configuration (~/.code-shell/settings.json, with project-level overrides):
{
"agent": {
"preset": "general",
"enabledBuiltinTools": ["LSP"],
"disabledBuiltinTools": ["WebSearch"],
"appendSystemPrompt": "Prefer long-horizon planning and keep task state updated."
}
}
Supported agent settings: preset, enabledBuiltinTools, disabledBuiltinTools, customSystemPrompt, appendSystemPrompt.
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).
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.
At a high level, CodeShell routes CLI, headless, SDK, and desktop clients through the same engine runtime:
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:
packages/
├── link/ # Framework-independent Link provider manifests and authorization guides
├── core/ # Domain-agnostic engine, context, MCP, hooks, sessions, runs, memory
├── coding/ # Coding capability pack: tools, git/worktrees, LSP, review, prompt/presets
├── arena/ # Retained private Arena source (not loaded by hosts)
├── pet/ # Mimi behavior, DelegateWork, projection protocol, digital-human teams
├── server/ # Headless HTTP/WebSocket host, rooms, uploads, mobile remote
├── web/ # Browser-safe remote client state and SPA
├── tui/ # Terminal CLI, Ink-based UI, renderer, commands, approvals
├── desktop/ # Electron desktop client + agent worker bridge + mobile remote app
├── cdp/ # Environment-agnostic CDP browser-action layer (no Playwright)
└── chat/ # Standalone multi-channel chat gateway + optional CodeShell adapter
package.json # @cjhyy/code-shell compatibility meta package
assets/ # README / product images (mascot, promo hero, Playwright desktop screenshots)
docs/
├── architecture/ # System architecture chapters + feature inventory (see architecture/README.md)
├── todo/ # Roadmap + forward-looking design docs (see todo/README.md)
└── archive/ # Superseded design docs, audits, and the prior architecture set
scripts/ # Build, release, and repo maintenance scripts
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 typecheckat 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.*. Seepackages/desktop/CLAUDE.mdfor 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.
MIT — see LICENSE.
FAQs
Code Shell — meta package. Installs @cjhyy/code-shell-core and @cjhyy/code-shell-tui.
The npm package @cjhyy/code-shell receives a total of 87 weekly downloads. As such, @cjhyy/code-shell popularity was classified as not popular.
We found that @cjhyy/code-shell demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.