{"id":50438140,"url":"https://github.com/cjhyy/codeshell","last_synced_at":"2026-05-31T18:01:35.665Z","repository":{"id":351242552,"uuid":"1179436195","full_name":"cjhyy/codeshell","owner":"cjhyy","description":"An open-source AI coding assistant for your terminal, inspired by Claude Code. Interact with your codebase directly from the command line.","archived":false,"fork":false,"pushed_at":"2026-05-29T16:45:04.000Z","size":18378,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T18:18:24.365Z","etag":null,"topics":["claude","claude-code"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjhyy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T02:55:36.000Z","updated_at":"2026-05-29T16:45:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cjhyy/codeshell","commit_stats":null,"previous_names":["cjhyy/codeshell"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/cjhyy/codeshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjhyy%2Fcodeshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjhyy%2Fcodeshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjhyy%2Fcodeshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjhyy%2Fcodeshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjhyy","download_url":"https://codeload.github.com/cjhyy/codeshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjhyy%2Fcodeshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33742187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code"],"created_at":"2026-05-31T18:01:30.147Z","updated_at":"2026-05-31T18:01:33.303Z","avatar_url":"https://github.com/cjhyy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeShell\n\nCodeShell is a general-purpose AI agent orchestration framework for terminal and headless workflows.\n\nIt now ships with built-in presets:\n\n- `general`: a domain-agnostic orchestrator for research, automation, operations, and long-running tasks\n- `terminal-coding`: a coding-focused terminal assistant built on top of the same core engine\n\nThe 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.\n\n## Features\n\n### Core engine\n\n- Turn-based agent loop with streaming output\n- Context compaction and session persistence\n- Permission-gated tool execution\n- Hook pipeline and MCP integration\n- Task tracking, sub-agents, sleep, and cron tools for long-running workflows\n\n### Presets\n\n- `general` for orchestration-heavy work\n- `terminal-coding` for terminal-native code editing and code navigation\n- Configurable prompt and built-in tool selection through settings or the programmatic API\n\n### Terminal UX\n\n- Interactive REPL built with Ink\n- Headless `run` mode for one-shot execution\n- Session resume and cost tracking\n\n## Quick start\n\n```bash\n# Default CLI preset: terminal coding assistant\nnpx @cjhyy/code-shell\n\n# Run the same framework as a general orchestrator\nnpx @cjhyy/code-shell --preset general\n\n# One-shot execution with the general preset\nnpx @cjhyy/code-shell run --preset general \"Create a long-running research plan and track it with tasks\"\n```\n\n## Programmatic API\n\n```ts\nimport { Engine } from \"@cjhyy/code-shell\";\n\nconst generalEngine = new Engine({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4.1\",\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  preset: \"general\",\n});\n\nconst codingEngine = new Engine({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4.1\",\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  preset: \"terminal-coding\",\n});\n```\n\n### Subpath imports\n\nPull only what you need:\n\n```ts\nimport { RunManager, FileRunStore } from \"@cjhyy/code-shell/run\";\nimport { Arena, IterativeArena }     from \"@cjhyy/code-shell/arena\";\nimport { defineProduct }             from \"@cjhyy/code-shell/product\";\n```\n\n## Configuration\n\nCLI preset selection:\n\n```bash\nnpx @cjhyy/code-shell --preset general\nnpx @cjhyy/code-shell --preset terminal-coding\n```\n\nSettings-based configuration:\n\n```json\n{\n  \"agent\": {\n    \"preset\": \"general\",\n    \"enabledBuiltinTools\": [\"LSP\"],\n    \"disabledBuiltinTools\": [\"WebSearch\"],\n    \"appendSystemPrompt\": \"Prefer long-horizon planning and keep task state updated.\"\n  }\n}\n```\n\nSupported `agent` settings:\n\n- `preset`\n- `enabledBuiltinTools`\n- `disabledBuiltinTools`\n- `customSystemPrompt`\n- `appendSystemPrompt`\n\n### Fullscreen Mode\n\nCodeshell defaults to **fullscreen** (alt-screen + ScrollBox). This is the\nmode where window resize repaints cleanly — flow mode can show duplicate\ncontent in the terminal's scrollback after a resize because the terminal\npushes the old viewport up before codeshell can erase it.\n\nOpt out of fullscreen at startup with `CODESHELL_FULLSCREEN=0|false|off`,\nor toggle at runtime with `/fullscreen off`. Flow mode lets the transcript\nflow into the terminal's native scrollback (useful if you prefer keeping\nshell history above codeshell visible).\n\n### Stream Idle Watchdog (opt-in)\n\nWhen `CODESHELL_ENABLE_STREAM_WATCHDOG=1`, the openai provider aborts any LLM\nstream that has gone `CODESHELL_STREAM_IDLE_TIMEOUT_MS` ms (default `90000`)\nwithout receiving a chunk. The engine then retries via the existing\n`withRetry` policy, capped by `CODESHELL_STREAM_WATCHDOG_RETRIES` (default\n`2`) attempts with exponential backoff.\n\nThis bounds upstream hangs at ~90 s instead of indefinitely. User-initiated\naborts (Esc / Ctrl+C) are never retried.\n\nDisabled by default — set the flag explicitly to opt in.\n\n## Built-in presets\n\n| Preset | Purpose | Extra tools |\n|------|------|------|\n| `general` | General orchestration, research, automation, long-running work | Core orchestration tools only |\n| `terminal-coding` | Terminal coding assistant | `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`, `Brief` |\n\n## Built-in tools\n\nThe framework keeps a broad orchestration toolbox available, including:\n\n- File tools: `Read`, `Write`, `Edit`, `Glob`, `Grep`\n- Execution tools: `Bash`, `PowerShell`, `REPL`\n- Coordination tools: `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `TaskOutput`, `Agent`, `SendMessage`, `Sleep`\n- Planning/runtime tools: `EnterPlanMode`, `ExitPlanMode`, `CronCreate`, `CronDelete`, `CronList`\n- Discovery/integration tools: `ToolSearch`, `Skill`, `MCPTool`, `ListMcpResources`, `ReadMcpResource`\n- Coding-only preset extras: `EnterWorktree`, `ExitWorktree`, `NotebookEdit`, `LSP`\n\n## Architecture\n\n```text\nUser / CLI / SDK\n  -\u003e Engine\n    -\u003e Preset resolution (prompt + default tools + default permission shortcuts)\n    -\u003e TurnLoop\n      -\u003e ModelFacade\n      -\u003e ToolExecutor\n      -\u003e ContextManager\n      -\u003e Hooks / MCP / Tasks / Sessions\n```\n\nDesign principles:\n\n- Core first: orchestration engine stays domain-agnostic\n- Presets over hardcoding: coding behavior lives in configuration\n- Secure by default: permission-gated actions and explicit approval flow\n- Long-running ready: tasks, cron, sleep, and sub-agents are first-class\n\n## Further Reading\n\n- [CodeShell architecture documentation set](docs/architecture/README.md)\n- [CodeShell architecture diagrams](docs/architecture/10-architecture-diagrams.md)\n- [TUI Render 能力规划](docs/architecture/11-render-tui-capability-plan.md)\n- [mac 端可视化客户端调研](docs/architecture/12-mac-visual-client-research.md)\n- [CodeShell 当前架构与定位说明](docs/codeshell-repo-architecture.md)\n\n## Project structure\n\n```text\nsrc/\n├── cli/              # CLI entrypoints, commands, onboarding, and output modes\n├── context/          # Context compaction and window management\n├── engine/           # Turn loop orchestration\n├── hooks/            # Hook chain\n├── llm/              # Model providers\n├── preset/           # Built-in agent presets\n├── prompt/           # Prompt composition\n├── protocol/         # Agent client/server protocol\n├── render/           # Custom Ink-like terminal renderer\n├── run/              # Managed run lifecycle\n├── session/          # Session persistence and memory\n├── tool-system/      # Tool registry, execution, permissions, MCP\n├── ui/               # Terminal UI components\n└── index.ts          # Public API exports\n```\n\n## Development\n\n```bash\nbun install\nbun run build\nbun run tsc --noEmit\n```\n\n`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.\n\n## Acknowledgments\n\nThe `ApplyPatch` tool (`src/tool-system/builtin/apply-patch/`) is adapted from\n[OpenAI Codex `codex-rs/apply-patch`](https://github.com/openai/codex/tree/main/codex-rs/apply-patch),\nlicensed under the Apache License 2.0. See `NOTICE.md` and `LICENSE-codex` in\nthat directory for details, including the intentional behavioral divergence\nwhere our applier rolls back partial writes on failure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjhyy%2Fcodeshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjhyy%2Fcodeshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjhyy%2Fcodeshell/lists"}