@cjhyy/code-shell 0.5.0-rc.2 → 0.6.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +173 -118
  3. package/package.json +11 -4
package/CHANGELOG.md CHANGED
@@ -28,6 +28,110 @@ breaking.
28
28
  tools). Their `model` is left unset so they reuse the parent model — set
29
29
  `model:` in the frontmatter to route a role to a specific pool key.
30
30
 
31
+ #### Unified model catalog + `EditModelCatalog`
32
+
33
+ - A single catalog drives text/image/video model connections (one template per
34
+ vendor, parameters declared in the catalog drive both the UI controls and the
35
+ tool description). Built-in entries ship in core; user entries live in
36
+ `~/.code-shell/model-catalog.user.json`. The connections page supports
37
+ multiple instances and credential reuse (`apiKeyRef`) with a per-tag default.
38
+ - New `EditModelCatalog` builtin tool lets the agent add/update a user catalog
39
+ entry and echoes a structured summary (every param's options/default) so you
40
+ can verify it against the provider's official docs.
41
+ - Reasoning `effort` is now a free-form, catalog-driven string (e.g. `xhigh`,
42
+ `max`) instead of a closed enum, so a model gaining a new level no longer
43
+ crashes the app on boot.
44
+ - **Generic parameter pass-through**: catalog-declared params (beyond reasoning)
45
+ flow into the request body via `extraBody`, filtered per-provider against
46
+ `rejectedParams` — so a vendor-specific knob can be exposed in the UI and sent
47
+ on the wire without a code change.
48
+ - Connections that require an API key but have no credential now surface a clear
49
+ "credential not configured" error at resolve time instead of an opaque 401
50
+ when the first message is sent.
51
+
52
+ #### Browser automation + built-in browser panel
53
+
54
+ - CDP-driven automation of the built-in browser (no Playwright/JS-injection):
55
+ semantic `browser_observe` / `browser_act` / `browser_navigate` tools, image
56
+ & vision observation, multi-tab support, and link/image URL extraction. The
57
+ whole capability is a single toggle — turning it off removes both the tools
58
+ and their prompt text. Stale snapshots are folded to save tokens.
59
+ - The agent can open the browser panel itself; selections echo back into tool
60
+ cards; screenshots echo to the stream as clickable thumbnails.
61
+
62
+ #### Credentials: cookie login, multi-account, inject
63
+
64
+ - Standalone login window captures session cookies for sites the embedded
65
+ webview can't log into (Google/YouTube/etc.), stored as cookie credentials.
66
+ - Same-domain multi-account cookie credentials with a `UseCredential` tool
67
+ (materializes a temporary Netscape `cookies.txt` for HTTP scraping) and a new
68
+ `InjectCredential` tool (restores cookies into the built-in browser). Both are
69
+ gated by a three-tier approval, with per-credential auto-use/auto-inject opt-in.
70
+
71
+ #### Plugins / MCP / extensions
72
+
73
+ - Local plugin install from a directory or `.zip`, with same-name **overwrite
74
+ upgrade** (using the authoritative manifest name) and **uninstall** that also
75
+ prunes orphaned `disabled` entries from settings.
76
+ - Plugin-bundled MCP servers accept a user supplement layer (extra
77
+ credentials / env vars / forwarded system env) without touching the plugin
78
+ manifest. Extensions page unifies icons and surfaces a marketplace "refresh"
79
+ (git fetch) action and an "official" badge.
80
+
81
+ #### Desktop & engine
82
+
83
+ - Full Chinese/English i18n of the desktop renderer; YAML config read support.
84
+ - SDK-only `settingsJsonSchema()` / `writeSettingsSchemaFile()` exports for
85
+ embedders that want to generate a JSON-Schema for `settings.json` (not wired
86
+ into the desktop/CLI UI — call it explicitly from a host).
87
+ - Step-gap **steering**: guidance injects between turn steps without
88
+ interrupting the current turn by default.
89
+ - A single notification-driven wake path unifies background video / shell /
90
+ sub-agent completion (replaces engine busy-loops).
91
+ - Dedicated sandbox settings tab + per-tool-card sandbox badge.
92
+
93
+ ### Security
94
+
95
+ - `settings.json` (which may hold plaintext API keys) is now written
96
+ owner-only (`0o600`), matching `credentials.json`; pre-existing
97
+ world-readable files are tightened on the next write.
98
+ - Cookie capture filters by a proper registrable-domain match, so a bare
99
+ public-suffix cookie domain (e.g. `.co`) can no longer be captured for an
100
+ unrelated host. Cookie lease files live in an owner-only (`0o700`) directory.
101
+ - Plugin/marketplace update checks pass a git `--` separator on every
102
+ `ls-remote`/`fetch`/`sparse-checkout`, closing an argument-injection vector
103
+ where a crafted git URL could be treated as a git flag.
104
+ - `WebSearch` and `web-fetch` now carry a request timeout and honor the user's
105
+ Stop signal, so a hung provider can no longer block a turn indefinitely.
106
+ - Mobile-remote device authentication compares the device secret in constant
107
+ time (`timingSafeEqual`) instead of `===`, removing a timing side-channel on
108
+ the bearer credential.
109
+ - `GenerateImage` / `GenerateVideo` local file inputs (`referenceImages` /
110
+ `images` / `image`) now go through the path-policy layer like `Read`, so an
111
+ out-of-workspace path (`../../etc/passwd`) prompts for approval instead of
112
+ being read and shipped silently.
113
+ - A credential's masked hint no longer reveals a short secret in full
114
+ (`"ab".slice(-4)` used to return the whole secret).
115
+
116
+ ### Fixed
117
+
118
+ - Step-gap steering no longer leaves a duplicate user bubble: a queued
119
+ steer entry that is interrupted (or that survives into the next turn) is
120
+ withdrawn before the message is re-sent.
121
+ - `AgentSendInput` refuses to resume a sub-agent that is still running,
122
+ preventing two engines from writing the same child transcript concurrently.
123
+ - Non-finite / non-positive numeric guards on several paths: the browser
124
+ `waitForLoad` no longer spins forever on a `NaN` timeout; `scroll` ignores a
125
+ `NaN` amount (and a negative amount no longer flips direction); terminal
126
+ resize clamps `NaN`/`<1` dimensions to 1; a `"0s"` cron interval is rejected
127
+ instead of busy-spinning a 0ms timer; and run-list pagination clamps negative
128
+ `offset`/`limit` instead of returning a surprise tail window.
129
+ - `ListMcpResources` / `ReadMcpResource` forward the run's Stop signal so a
130
+ hung MCP server call can be cancelled promptly.
131
+ - The phone remote no longer white-screens if the host sends a `room.history`
132
+ payload whose `messages` is not an array — the history replay guards the
133
+ shape before mapping.
134
+
31
135
  ## [0.5.0-rc.0] - 2026-05-23
32
136
 
33
137
  > ⚠️ Breaking. The repo is now a monorepo with three published packages.
package/README.md CHANGED
@@ -1,51 +1,130 @@
1
- # CodeShell
1
+ <p align="center">
2
+ <img src="assets/codeshell-dog-icon.png" alt="CodeShell dog mascot" width="120" />
3
+ </p>
2
4
 
3
- CodeShell is a general-purpose AI agent orchestration framework for terminal and headless workflows.
5
+ # CodeShell
4
6
 
5
- It now ships with built-in presets:
7
+ <p align="center">
8
+ <strong>A general-purpose AI agent orchestration framework — terminal, headless, and a full desktop app.</strong>
9
+ </p>
6
10
 
7
- - `general`: a domain-agnostic orchestrator for research, automation, operations, and long-running tasks
8
- - `terminal-coding`: a coding-focused terminal assistant built on top of the same core engine
11
+ <p align="center">
12
+ <img src="assets/codeshell-hero.png" alt="CodeShell terminal agent orchestration hero image" width="860" />
13
+ </p>
9
14
 
10
- The important part is that the core is no longer tied to software engineering. The turn loop, context management, permissions, MCP integration, hooks, tasks, cron, and sub-agents stay generic; coding behavior is expressed as a preset.
15
+ CodeShell is one orchestration engine wearing three faces:
11
16
 
12
- ## Features
17
+ - a **terminal CLI** (`code-shell`) for interactive and headless agent runs,
18
+ - an **Electron desktop app** with chat, file/browser/terminal/diff panels, model & credential management, an extensions marketplace, automation, and a phone remote, and
19
+ - a **programmatic SDK** (`import { Engine } from "@cjhyy/code-shell"`) for embedding the engine in your own product.
13
20
 
14
- ### Core engine
21
+ 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 behavior is just a *preset* layered on top — not baked into the engine. (See `packages/core/CONTRIBUTING.md`: "core only carries mechanism, not policy.")
15
22
 
16
- - Turn-based agent loop with streaming output
17
- - Context compaction and session persistence
18
- - Permission-gated tool execution
19
- - Hook pipeline and MCP integration
20
- - Task tracking, sub-agents, sleep, and cron tools for long-running workflows
23
+ > Status: **0.5.0-rc.2**, preparing for beta. The desktop app is the headline product; the CLI and SDK share the same core engine.
21
24
 
22
- ### Presets
25
+ ---
23
26
 
24
- - `general` for orchestration-heavy work
25
- - `terminal-coding` for terminal-native code editing and code navigation
26
- - Configurable prompt and built-in tool selection through settings or the programmatic API
27
+ ## Why CodeShell
27
28
 
28
- ### Terminal UX
29
+ - **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.
30
+ - **Terminal-first, headless-ready, desktop-complete** — run interactively in the terminal, fire one-shot headless jobs, or use the full visual desktop client.
31
+ - **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.
32
+ - **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.
33
+ - **Local-first & private** — sessions, transcripts, credentials, and memory live under `~/.code-shell/`; credential files are written owner-only (`0o600`).
29
34
 
30
- - Interactive REPL built with Ink
31
- - Headless `run` mode for one-shot execution
32
- - Session resume and cost tracking
35
+ ---
33
36
 
34
37
  ## Quick start
35
38
 
39
+ ### CLI
40
+
36
41
  ```bash
37
- # Default CLI preset: terminal coding assistant
42
+ # Default CLI preset: terminal coding assistant (interactive REPL)
38
43
  npx @cjhyy/code-shell
39
44
 
40
45
  # Run the same framework as a general orchestrator
41
46
  npx @cjhyy/code-shell --preset general
42
47
 
43
- # One-shot execution with the general preset
44
- npx @cjhyy/code-shell run --preset general "Create a long-running research plan and track it with tasks"
48
+ # One-shot / headless execution
49
+ npx @cjhyy/code-shell run --preset general \
50
+ "Create a long-running research plan and track it with tasks"
45
51
  ```
46
52
 
53
+ Requires **Node.js >= 20.10**.
54
+
55
+ ### Desktop app
56
+
57
+ The desktop app (`packages/desktop`) is an Electron client. To run it from source:
58
+
59
+ ```bash
60
+ bun install
61
+ bun run dev # launches the desktop app in dev mode
62
+ ```
63
+
64
+ 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.
65
+
66
+ ---
67
+
68
+ ## Features
69
+
70
+ ### Core engine (`@cjhyy/code-shell-core`)
71
+
72
+ - Turn-based agent loop with streaming output and step-by-step lifecycle events
73
+ - Context compaction (tool-pair-preserving) and durable session persistence on disk
74
+ - Permission-gated tool execution with session/project rule caching and chained-command guards
75
+ - Hook pipeline (user + project + plugin hooks) and full MCP client integration
76
+ - First-class **tasks, sub-agents, cron, and sleep** for long-running and self-pacing workflows
77
+ - **Persistent goals** with a stop-hook judge and explicit `complete_goal` declaration
78
+ - **Memory + Dream**: per-turn memory injection plus an LLM consolidation pass
79
+ - **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
80
+ - Background shell jobs, cost tracking, and turn-level file undo/redo
81
+
82
+ ### Presets
83
+
84
+ | Preset | Purpose | Extra tools |
85
+ |--------|---------|-------------|
86
+ | `general` | General orchestration, research, automation, long-running work | Core orchestration tools only |
87
+ | `terminal-coding` | Terminal-native coding assistant | `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`, `Brief`, `Arena` |
88
+
89
+ Presets select the system prompt, the built-in tool set, and permission defaults. Configure via the SDK, the CLI `--preset` flag, or settings.
90
+
91
+ ### Terminal UX (`@cjhyy/code-shell-tui`)
92
+
93
+ - Interactive REPL (Ink-based) with fullscreen/flow modes, vim-mode input, and input history
94
+ - Headless `run` mode for one-shot execution, plus `repl`, `sessions`, and `runs` subcommands
95
+ - Slash commands, `@`-mention file/skill search, command auto-complete, and in-REPL cron scheduling
96
+ - `Shift+Tab` permission-mode cycling, transcript browsing, session resume, and cost/usage reporting
97
+
98
+ ### Desktop app (`@cjhyy/code-shell-desktop`)
99
+
100
+ - **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)
101
+ - **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
102
+ - **Model catalog & connections**: full CRUD over providers/models, credential reuse by company, and parameter docs surfaced into tool descriptions
103
+ - **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
104
+ - **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
105
+ - **Automation**: cron/scheduled tasks with read-only contract enforcement, per-task transcripts and memory, and a runs view for long tasks
106
+ - **Persistent goals**, **memory management** (pin/edit/clear, manual Dream), **hooks** configuration, and full **i18n** (Chinese / English)
107
+ - **Phone remote**: control a desktop session from a mobile web app over a local WebSocket
108
+ - Onboarding wizard, trust gate, app updater, command palette (⌘K), cross-project session search (⌘P), and in-transcript search (⌘F)
109
+
110
+ ### Built-in tools
111
+
112
+ A broad orchestration toolbox is available across presets:
113
+
114
+ - **File**: `Read`, `Write`, `Edit`, `Glob`, `Grep`
115
+ - **Execution**: `Bash`, `PowerShell`, `REPL`
116
+ - **Coordination**: `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `TaskOutput`, `Agent`, `SendMessage`, `Sleep`
117
+ - **Planning / runtime**: `EnterPlanMode`, `ExitPlanMode`, `CronCreate`, `CronDelete`, `CronList`
118
+ - **Discovery / integration**: `ToolSearch`, `Skill`, `MCPTool`, `ListMcpResources`, `ReadMcpResource`
119
+ - **Generation**: `GenerateImage`, `GenerateVideo` (image/video providers via the unified catalog)
120
+ - **Coding preset extras**: `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`, `Brief`, `Arena`
121
+
122
+ ---
123
+
47
124
  ## Programmatic API
48
125
 
126
+ The meta package re-exports the core engine, so legacy SDK imports keep working:
127
+
49
128
  ```ts
50
129
  import { Engine } from "@cjhyy/code-shell";
51
130
 
@@ -68,15 +147,9 @@ const codingEngine = new Engine({
68
147
  });
69
148
  ```
70
149
 
71
- ### Subpath imports
150
+ 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.
72
151
 
73
- Pull only what you need:
74
-
75
- ```ts
76
- import { RunManager, FileRunStore } from "@cjhyy/code-shell/run";
77
- import { Arena, IterativeArena } from "@cjhyy/code-shell/arena";
78
- import { defineProduct } from "@cjhyy/code-shell/product";
79
- ```
152
+ ---
80
153
 
81
154
  ## Configuration
82
155
 
@@ -87,7 +160,7 @@ npx @cjhyy/code-shell --preset general
87
160
  npx @cjhyy/code-shell --preset terminal-coding
88
161
  ```
89
162
 
90
- Settings-based configuration:
163
+ Settings-based configuration (`~/.code-shell/settings.json`, with project-level overrides):
91
164
 
92
165
  ```json
93
166
  {
@@ -100,119 +173,101 @@ Settings-based configuration:
100
173
  }
101
174
  ```
102
175
 
103
- Supported `agent` settings:
104
-
105
- - `preset`
106
- - `enabledBuiltinTools`
107
- - `disabledBuiltinTools`
108
- - `customSystemPrompt`
109
- - `appendSystemPrompt`
176
+ Supported `agent` settings: `preset`, `enabledBuiltinTools`, `disabledBuiltinTools`, `customSystemPrompt`, `appendSystemPrompt`.
110
177
 
111
- ### Fullscreen Mode
178
+ ### Fullscreen mode (TUI)
112
179
 
113
- Codeshell defaults to **fullscreen** (alt-screen + ScrollBox). This is the
114
- mode where window resize repaints cleanly — flow mode can show duplicate
115
- content in the terminal's scrollback after a resize because the terminal
116
- pushes the old viewport up before codeshell can erase it.
180
+ 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.
117
181
 
118
- Opt out of fullscreen at startup with `CODESHELL_FULLSCREEN=0|false|off`,
119
- or toggle at runtime with `/fullscreen off`. Flow mode lets the transcript
120
- flow into the terminal's native scrollback (useful if you prefer keeping
121
- shell history above codeshell visible).
182
+ 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).
122
183
 
123
- ### Stream Idle Watchdog (opt-in)
184
+ ### Stream idle watchdog (opt-in)
124
185
 
125
- When `CODESHELL_ENABLE_STREAM_WATCHDOG=1`, the openai provider aborts any LLM
126
- stream that has gone `CODESHELL_STREAM_IDLE_TIMEOUT_MS` ms (default `90000`)
127
- without receiving a chunk. The engine then retries via the existing
128
- `withRetry` policy, capped by `CODESHELL_STREAM_WATCHDOG_RETRIES` (default
129
- `2`) attempts with exponential backoff.
186
+ When `CODESHELL_ENABLE_STREAM_WATCHDOG=1`, the openai provider aborts any LLM stream idle for `CODESHELL_STREAM_IDLE_TIMEOUT_MS` ms (default `90000`) without a chunk. The engine 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. User-initiated aborts (Esc / Ctrl+C) are never retried. Disabled by default.
130
187
 
131
- This bounds upstream hangs at ~90 s instead of indefinitely. User-initiated
132
- aborts (Esc / Ctrl+C) are never retried.
188
+ ---
133
189
 
134
- Disabled by default — set the flag explicitly to opt in.
135
-
136
- ## Built-in presets
137
-
138
- | Preset | Purpose | Extra tools |
139
- |------|------|------|
140
- | `general` | General orchestration, research, automation, long-running work | Core orchestration tools only |
141
- | `terminal-coding` | Terminal coding assistant | `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`, `Brief` |
190
+ ## Architecture
142
191
 
143
- ## Built-in tools
192
+ <p align="center">
193
+ <img src="docs/archive/architecture/images/00-framework-overview.png" alt="CodeShell framework overview architecture diagram" width="860" />
194
+ </p>
144
195
 
145
- The framework keeps a broad orchestration toolbox available, including:
196
+ At a high level, CodeShell routes CLI, headless, SDK, and desktop clients through the same engine runtime:
146
197
 
147
- - File tools: `Read`, `Write`, `Edit`, `Glob`, `Grep`
148
- - Execution tools: `Bash`, `PowerShell`, `REPL`
149
- - Coordination tools: `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `TaskOutput`, `Agent`, `SendMessage`, `Sleep`
150
- - Planning/runtime tools: `EnterPlanMode`, `ExitPlanMode`, `CronCreate`, `CronDelete`, `CronList`
151
- - Discovery/integration tools: `ToolSearch`, `Skill`, `MCPTool`, `ListMcpResources`, `ReadMcpResource`
152
- - Coding-only preset extras: `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`
198
+ - **Preset resolution** selects the system prompt, built-in tools, and permission defaults.
199
+ - **TurnLoop** coordinates model streaming, context assembly, tool execution, and lifecycle events.
200
+ - **Tool system** hosts built-ins, MCP tools, permissions, hooks, and cancellation.
201
+ - **Session / run layers** persist transcripts, state, tasks, automation runs, and memories.
153
202
 
154
- ## Architecture
155
-
156
- ```text
157
- User / CLI / SDK
158
- -> Engine
159
- -> Preset resolution (prompt + default tools + default permission shortcuts)
160
- -> TurnLoop
161
- -> ModelFacade
162
- -> ToolExecutor
163
- -> ContextManager
164
- -> Hooks / MCP / Tasks / Sessions
165
- ```
203
+ 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.*`.
166
204
 
167
205
  Design principles:
168
206
 
169
- - Core first: orchestration engine stays domain-agnostic
170
- - Presets over hardcoding: coding behavior lives in configuration
171
- - Secure by default: permission-gated actions and explicit approval flow
172
- - Long-running ready: tasks, cron, sleep, and sub-agents are first-class
207
+ - **Core first** — the orchestration engine stays domain-agnostic.
208
+ - **Presets over hardcoding** — coding behavior lives in configuration.
209
+ - **Secure by default** — permission-gated actions and explicit approval flow; owner-only credential files.
210
+ - **Long-running ready** — tasks, cron, sleep, sub-agents, and persistent goals are first-class.
173
211
 
174
- ## Further Reading
175
-
176
- - [CodeShell architecture documentation set](docs/architecture/README.md)
177
- - [CodeShell architecture diagrams](docs/architecture/10-architecture-diagrams.md)
178
- - [TUI Render 能力规划](docs/architecture/11-render-tui-capability-plan.md)
179
- - [mac 端可视化客户端调研](docs/architecture/12-mac-visual-client-research.md)
180
- - [CodeShell 当前架构与定位说明](docs/codeshell-repo-architecture.md)
212
+ ---
181
213
 
182
214
  ## Project structure
183
215
 
184
216
  ```text
185
- src/
186
- ├── cli/ # CLI entrypoints, commands, onboarding, and output modes
187
- ├── context/ # Context compaction and window management
188
- ├── engine/ # Turn loop orchestration
189
- ├── hooks/ # Hook chain
190
- ├── llm/ # Model providers
191
- ├── preset/ # Built-in agent presets
192
- ├── prompt/ # Prompt composition
193
- ├── protocol/ # Agent client/server protocol
194
- ├── render/ # Custom Ink-like terminal renderer
195
- ├── run/ # Managed run lifecycle
196
- ├── session/ # Session persistence and memory
197
- ├── tool-system/ # Tool registry, execution, permissions, MCP
198
- ├── ui/ # Terminal UI components
199
- └── index.ts # Public API exports
217
+ packages/
218
+ ├── core/ # Engine, context, tools, MCP, hooks, sessions, runs, presets, memory
219
+ ├── tui/ # Terminal CLI, Ink-based UI, renderer, commands, approvals
220
+ ├── desktop/ # Electron desktop client + agent worker bridge + mobile remote app
221
+ └── cdp/ # Environment-agnostic CDP browser-action layer (no Playwright)
222
+
223
+ assets/ # README / product images (mascot, hero)
224
+
225
+ docs/
226
+ ├── architecture/ # System architecture chapters + feature inventory (see architecture/README.md)
227
+ ├── todo/ # Roadmap + forward-looking design docs (see todo/README.md)
228
+ └── archive/ # Superseded design docs, audits, and the prior architecture set
229
+
230
+ scripts/ # Build, release, and repo maintenance scripts
200
231
  ```
201
232
 
233
+ ---
234
+
202
235
  ## Development
203
236
 
204
237
  ```bash
205
238
  bun install
206
- bun run build
207
- bun run tsc --noEmit
239
+ bun run build # build core + tui + meta package
240
+ bun run typecheck # core + tui (tsc --noEmit)
241
+ bun test # core / tui test suites
242
+
243
+ # Desktop has its OWN typecheck and build (the root checks do NOT cover it):
244
+ cd packages/desktop
245
+ bunx tsc --noEmit
246
+ bun run build:renderer
208
247
  ```
209
248
 
210
- `bun run tsc --noEmit` currently reports many pre-existing repo-wide issues outside the preset/framework changes, so treat typecheck as a global health signal rather than a clean gate for just this slice.
249
+ `bun run dev` launches the desktop app. For the TUI in dev: `bun run dev:tui`.
250
+
251
+ > 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.
252
+
253
+ ---
254
+
255
+ ## Further reading
256
+
257
+ - [Architecture & feature inventory](docs/architecture/README.md)
258
+ - [Roadmap & TODO](docs/todo/README.md)
259
+ - [Prior architecture documentation set (archived, pending rewrite)](docs/archive/architecture/README.md)
260
+
261
+ ---
211
262
 
212
263
  ## Acknowledgments
213
264
 
214
- The `ApplyPatch` tool (`src/tool-system/builtin/apply-patch/`) is adapted from
265
+ The `ApplyPatch` tool (`packages/core/src/tool-system/builtin/apply-patch/`) is adapted from
215
266
  [OpenAI Codex `codex-rs/apply-patch`](https://github.com/openai/codex/tree/main/codex-rs/apply-patch),
216
- licensed under the Apache License 2.0. See `NOTICE.md` and `LICENSE-codex` in
217
- that directory for details, including the intentional behavioral divergence
218
- where our applier rolls back partial writes on failure.
267
+ licensed under the Apache License 2.0. See `NOTICE.md` and `LICENSE-codex` in that directory
268
+ for details, including the intentional behavioral divergence where our applier rolls back
269
+ partial writes on failure.
270
+
271
+ ## License
272
+
273
+ MIT — see [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cjhyy/code-shell",
3
- "version": "0.5.0-rc.2",
3
+ "version": "0.6.0-rc.2",
4
4
  "description": "Code Shell — meta package. Installs @cjhyy/code-shell-core and @cjhyy/code-shell-tui.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -17,7 +17,9 @@
17
17
  "scripts": {
18
18
  "preinstall": "node scripts/check-node.cjs",
19
19
  "build": "bun run --filter '@cjhyy/code-shell-core' build && bun run --filter '@cjhyy/code-shell-tui' build && bun run scripts/build-meta.ts",
20
- "dev": "CODE_SHELL_DEV=1 CODESHELL_UI_PERF=1 bun run packages/tui/src/cli/main.ts",
20
+ "dev": "bun run dev:desktop",
21
+ "dev:desktop": "bun run --filter '@cjhyy/code-shell-desktop' dev",
22
+ "dev:tui": "CODE_SHELL_DEV=1 CODESHELL_UI_PERF=1 bun run packages/tui/src/cli/main.ts",
21
23
  "dev:bigtranscript": "bun run scripts/render-bigtranscript-dev.ts",
22
24
  "test": "bun test",
23
25
  "test:watch": "bun test --watch",
@@ -28,12 +30,15 @@
28
30
  "format": "prettier --write 'packages/**/*.ts'"
29
31
  },
30
32
  "dependencies": {
31
- "@cjhyy/code-shell-core": "0.5.0-rc.2",
32
- "@cjhyy/code-shell-tui": "0.5.0-rc.2"
33
+ "@cjhyy/code-shell-core": "0.6.0-rc.2",
34
+ "@cjhyy/code-shell-tui": "0.6.0-rc.2"
33
35
  },
34
36
  "workspaces": [
35
37
  "packages/*"
36
38
  ],
39
+ "overrides": {
40
+ "react": "19.2.6"
41
+ },
37
42
  "repository": {
38
43
  "type": "git",
39
44
  "url": "git+https://github.com/cjhyy/codeshell.git"
@@ -74,6 +79,8 @@
74
79
  "@types/node": "^22.12.0",
75
80
  "@types/react": "^19.2.14",
76
81
  "@types/semver": "^7.7.1",
82
+ "chalk": "^5.4.1",
83
+ "react": "19.2.6",
77
84
  "bun-types": "^1.3.14",
78
85
  "eslint": "^9.19.0",
79
86
  "prettier": "^3.4.2",