A conversational AI coding agent that runs in your terminal — written in 100% Rust, modeled on Claude Code. Built on ratatui 0.30 + crossterm + tokio, and talks to OpenAI-compatible and Anthropic-style providers.
- Multi-Provider — OpenAI, Anthropic, and any OpenAI-compatible endpoint. Per-provider credentials with a provider store, switchable at runtime.
- Interactive TUI — streaming responses, diffs, syntax highlighting, themes, mouse support.
- Headless Mode — drive a prompt from a script and get JSONL or plain text back.
- Rich Toolchain — read/write/edit/notebook tools, shell, ripgrep search, AST-aware codebase search, git insight, sub-agents, todos, cron, worktrees, MCP servers.
- Permissions — every tool call can be confirmed interactively; plan mode restricts the agent to read-only actions.
- Project Context — instructions are picked up from
STAR.md/STARCODE.md/CLAUDE.md/AGENTS.mdin your project. - Sessions — save, resume, and manage conversation history.
- Internationalization — English and Chinese UI.
- Cross-Platform — Linux, macOS, and Windows.
git clone https://github.com/xyz1o2/starcode-cli.git
cd starcode-cli
./install.sh # Windows: .\install.ps1install.sh builds one binary (starcode-cli) and symlinks two aliases next to it in ~/.cargo/bin, so all three start the same program:
sc # short form
starcode
starcode-cliNote:
cargo build --releaseon its own only gives you thestarcode-cliname — thesc/starcodealiases are created by the install script.
cargo install --git https://github.com/xyz1o2/starcode-cli.git starcode-cliDownload the latest release for your platform from the Releases page.
# Option 1: Environment variable
export STAR_API_KEY="your-api-key"
# Option 2: Config file (see "Configuration" below)
# Option 3: One-off CLI flag
sc -k "your-api-key"sc # interactive TUI
sc "Explain the structure of this project" # with an initial messagesc -p "What files are in the current directory?"
sc -p "List all Rust files" --output-format textCredentials and model settings resolve in this order (first wins): in-session override → CLI flag → STAR_* env vars → ANTHROPIC_* env vars → provider store → user settings file.
Searched from the current directory upwards to the project root (.jsonc with comments is supported). This is where shared, checked-in configuration lives. Global settings live at ~/.star/settings.json.
| Variable | Purpose |
|---|---|
STAR_API_KEY |
API key |
STAR_BASE_URL |
Custom API base URL |
STAR_MODEL |
Default model |
STAR_CONTEXT_WINDOW |
Context window size |
STAR_LLM_TIMEOUT |
LLM request timeout |
STAR_TOOL_TIMEOUT_SECS |
Tool execution timeout |
STAR_LOG_DIR |
Relocate the log directory |
STAR_LOG_ENABLED |
Set to 0 to disable file logging |
StarCode reads instructions from the first existing of STAR.md, STARCODE.md, CLAUDE.md, AGENTS.md at the project root (truncated to 8000 chars). Use starcode init to scaffold a STAR.md.
starcode # start interactive session
starcode -d /path/to/project # working directory
starcode --resume # resume the latest session
starcode --resume <session-id> # resume a specific session
starcode --dangerously-skip-permissions # skip all prompts (dangerous!)starcode -p "Your prompt here"
starcode -p "Your prompt" --output-format jsonl
starcode -p "Your prompt" --output-format text
starcode -p "Your prompt" --max-turns 50 --max-tool-rounds 200starcode init # scaffold STAR.md
starcode doctor # diagnose config, credentials, toolchain, logs
starcode mcp add <name> <command> # register an MCP server
starcode mcp list # list configured servers
starcode mcp remove <name> # remove a server
starcode git commit # AI-assisted git operations
starcode git diff
starcode git statusstarcode --permission-mode default # ask for permission (default)
starcode --permission-mode plan # read-only; plans before touching anything
starcode --permission-mode yolo # bypass all permissions (dangerous!)acceptEdits and bypassPermissions are accepted as aliases for default and yolo respectively.
Roughly 300 slash commands are available, grouped into Automation, Tools, Session, Config, Security, Git, Debug, MCP, Memory, and more. Type / to browse them, and /help for the full list.
| Tool | What it does |
|---|---|
Read / Write / Edit / MultiEdit / SmartEdit |
File reading and precise editing (SmartEdit repairs malformed edits with an LLM pass) |
NotebookRead / NotebookEdit |
Jupyter notebook support |
Bash |
Shell execution with sandboxing and timeouts |
Grep / Glob |
ripgrep-backed search and file patterns |
CodebaseSearch |
AST-aware semantic search over the codebase |
Agent / SendMessage |
Spawn and steer sub-agents |
TodoWrite / TaskGet |
Task and todo tracking |
WebFetch |
Fetch and analyze web pages |
GitInsight / GhPrComments |
Git history and GitHub PR context |
EnterPlanMode / ExitPlanMode |
Plan-mode control |
EnterWorktree / ExitWorktree |
Isolated git worktrees |
CronCreate / CronList / CronDelete |
Scheduled tasks |
BackgroundTask / ScheduleWakeup / RemoteTrigger |
Background and deferred execution |
Memory |
Persistent agent memory |
GetDiagnostics / RunTests / ProjectMap |
LSP diagnostics, test runner, project overview |
Skill / ToolSearch |
Skill invocation and tool discovery |
Plus any tools contributed by configured MCP servers.
StarCode supports the Model Context Protocol for extensible toolchains:
starcode mcp add filesystem "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"
starcode mcp list
starcode mcp remove filesystemcargo check --all-targets # fastest correctness gate — use while iterating
cargo build --release # → target/release/starcode-cli
cargo test --lib # unit tests live inside src/
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warningsstarcode-cli/
├── src/
│ ├── main.rs # binary entry: CLI parse, headless path, TUI bootstrap
│ ├── lib.rs # library root
│ ├── agent/ # agent core, turn loop, compaction, tool routing, fallback
│ ├── commands/ # slash commands and their dispatch
│ ├── core/ # config, tools, policy, context engine, confirmation bus, i18n
│ ├── llm/ # LLM clients and streaming
│ ├── runtime/ # UI ↔ Agent protocol and the runtime seam
│ ├── tools/ heavier tool implementations (bash, search, todo, git, lsp)
│ ├── types/ # shared types
│ ├── ui/ # terminal UI (ratatui): state, widgets, services
│ └── utils/ # logging, paths, project context, misc
├── eval/ # eval task definitions
├── i18n/ # translations
├── install.sh / .ps1 / .bat
└── Cargo.toml
You can't println! from a TUI. File logging is on by default and writes to .star/logs/starcode_debug.log and .star/logs/agent.log. Set STAR_LOG_DIR to relocate them, or STAR_LOG_ENABLED=0 to disable. If the app starts but the loading screen never clears, starcode doctor reports what's wrong without launching the TUI.
StarCode ships with a built-in eval harness:
starcode eval --tasks eval/tasks.json
starcode eval --tasks eval/tasks.json --trials 3
starcode eval --tasks eval/tasks.json --report-md eval-report.md
starcode eval --baseline .star/eval-baseline.jsonAPI key not found — echo $STAR_API_KEY, check ~/.star/user-settings.json, or run starcode doctor.
Build fails — make sure Rust is installed (rustc --version), then rustup update and cargo clean && cargo build --release.
Stuck on the loading screen — startup failures don't crash, they hang the loading view. Check .star/logs/agent.log for [INIT] breadcrumbs, or run starcode doctor.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Built with Rust
- Terminal UI powered by Ratatui
- LLM integration via Rig
- MCP support following the Model Context Protocol
Made by xyz1o2
{ "apiKey": "your-api-key", "baseUrl": "https://api.openai.com/v1", "defaultModel": "gpt-5", "isOpenAICompatible": true, "uiLanguage": "en", // "en" | "zh" "thinkingEffort": "medium", "outputStyle": "default", "contextWindow": 200000 }