CodeShell

CodeShell is a general-purpose AI agent orchestration framework for terminal and headless workflows.

It now ships with built-in presets:

• general: a domain-agnostic orchestrator for research, automation, operations, and long-running tasks
• terminal-coding: a coding-focused terminal assistant built on top of the same core engine

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.

Features

Core engine

• Turn-based agent loop with streaming output
• Context compaction and session persistence
• Permission-gated tool execution
• Hook pipeline and MCP integration
• Task tracking, sub-agents, sleep, and cron tools for long-running workflows

Presets

• general for orchestration-heavy work
• terminal-coding for terminal-native code editing and code navigation
• Configurable prompt and built-in tool selection through settings or the programmatic API

Terminal UX

• Interactive REPL built with Ink
• Headless run mode for one-shot execution
• Session resume and cost tracking

Quick start

# Default CLI preset: terminal coding assistant
npx @cjhyy/code-shell

# Run the same framework as a general orchestrator
npx @cjhyy/code-shell --preset general

# One-shot execution with the general preset
npx @cjhyy/code-shell run --preset general "Create a long-running research plan and track it with tasks"

Programmatic API

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",
});

Subpath imports

Pull only what you need:

import { RunManager, FileRunStore } from "@cjhyy/code-shell/run";
import { Arena, IterativeArena }     from "@cjhyy/code-shell/arena";
import { defineProduct }             from "@cjhyy/code-shell/product";

Configuration

CLI preset selection:

npx @cjhyy/code-shell --preset general
npx @cjhyy/code-shell --preset terminal-coding

Settings-based configuration:

{
  "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

Fullscreen Mode

Codeshell defaults to fullscreen (alt-screen + ScrollBox). This is the mode where window resize repaints cleanly — flow mode can show duplicate content in the terminal's scrollback after a resize because the terminal pushes the old viewport up before codeshell can erase it.

Opt out of fullscreen 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 (opt-in)

When CODESHELL_ENABLE_STREAM_WATCHDOG=1, the openai provider aborts any LLM stream that has gone CODESHELL_STREAM_IDLE_TIMEOUT_MS ms (default 90000) without receiving a chunk. The engine then retries via the existing withRetry policy, capped by CODESHELL_STREAM_WATCHDOG_RETRIES (default 2) attempts with exponential backoff.

This bounds upstream hangs at ~90 s instead of indefinitely. User-initiated aborts (Esc / Ctrl+C) are never retried.

Disabled by default — set the flag explicitly to opt in.

Built-in presets

Built-in tools

The framework keeps a broad orchestration toolbox available, including:

• File tools: Read, Write, Edit, Glob, Grep
• Execution tools: Bash, PowerShell, REPL
• Coordination tools: TaskCreate, TaskUpdate, TaskList, TaskGet, TaskOutput, Agent, SendMessage, Sleep
• Planning/runtime tools: EnterPlanMode, ExitPlanMode, CronCreate, CronDelete, CronList
• Discovery/integration tools: ToolSearch, Skill, MCPTool, ListMcpResources, ReadMcpResource
• Coding-only preset extras: EnterWorktree, ExitWorktree, NotebookEdit, LSP

Architecture

User / CLI / SDK
  -> Engine
    -> Preset resolution (prompt + default tools + default permission shortcuts)
    -> TurnLoop
      -> ModelFacade
      -> ToolExecutor
      -> ContextManager
      -> Hooks / MCP / Tasks / Sessions

Design principles:

• Core first: orchestration engine stays domain-agnostic
• Presets over hardcoding: coding behavior lives in configuration
• Secure by default: permission-gated actions and explicit approval flow
• Long-running ready: tasks, cron, sleep, and sub-agents are first-class

Further Reading

• CodeShell architecture documentation set
• CodeShell architecture diagrams
• TUI Render 能力规划
• mac 端可视化客户端调研
• CodeShell 当前架构与定位说明

Project structure

src/
├── cli/              # CLI entrypoints, commands, onboarding, and output modes
├── context/          # Context compaction and window management
├── engine/           # Turn loop orchestration
├── hooks/            # Hook chain
├── llm/              # Model providers
├── preset/           # Built-in agent presets
├── prompt/           # Prompt composition
├── protocol/         # Agent client/server protocol
├── render/           # Custom Ink-like terminal renderer
├── run/              # Managed run lifecycle
├── session/          # Session persistence and memory
├── tool-system/      # Tool registry, execution, permissions, MCP
├── ui/               # Terminal UI components
└── index.ts          # Public API exports

Development

bun install
bun run build
bun run tsc --noEmit

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.

Acknowledgments

The ApplyPatch tool (src/tool-system/builtin/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.