ZCode CLI Agent

Your terminal-native AI coding agent — describe the task, ship the work.

English | 中文

---

Why ZCode?

Most AI coding assistants are locked inside a browser tab or IDE window. ZCode CLI Agent puts the full agent loop right in your terminal — read files, run commands, search code, call MCP tools, edit with LSP diagnostics, and ship changes, all without leaving the shell.

It's Claude Code–class terminal agency, built for developers who want scriptable, local-first AI workflows with multi-model support, fine-grained tool permissions, and a persistent task system that survives restarts.

---

✨ Features

• 🎯 Natural-language coding — Describe tasks in plain language; the agent plans and executes with tools
• 🔌 Multi-provider LLM — Anthropic, AWS Bedrock, Google Vertex, Azure, and any OpenAI-compatible API
• 🧰 Rich tool system — File read/write/edit, shell, grep, glob, LSP diagnostics, skills, and extensible agents
• 🌐 MCP integration — Plug in external tools via Model Context Protocol servers
• 🛡️ Permission control — Four modes: Plan (preview only), Agent (ask per action), YOLO (auto-approve), Auto (bypass)
• 📦 Scriptable CLI — -p --json for CI pipelines; --write, --plan, --yolo, --reasoning flags
• 🖥️ Interactive Ink TUI — Full-screen REPL with session resume, context compression, and layered memory
• 💬 Reasoning preview — Stream model thinking blocks inline before tool calls and replies
• ⌨️ Keyboard-driven — Configurable keybindings: F1 help, Ctrl+K command palette, Ctrl+R history, chord sequences
• 📋 Persistent tasks — Create, track, and auto-restore task lists across sessions
• 🩺 LSP diagnostics — Auto-inject language server errors/warnings after file edits (toggleable)
• 🪟 Windows-first — Drive-letter path completion, backslash separators, portable installer via PowerShell

---

📸 Quick Demo

Offline (no API key needed, 21 checks):

bash scripts/demo-all-features.sh

Live (8 real LLM calls, requires .env):

bash scripts/demo-all-features.sh --live

See the full walkthrough at docs/guides/demo-walkthrough.md.

Sample output

$ cd ZCode && bun run doctor --json

{
  "productName": "ZCode",
  "version": "0.1.0",
  "startable": true,
  "provider": {
    "mode": "openai-compatible",
    "printReady": true,
    "modelCount": 12
  },
  "commands": ["help", "doctor", "models", "print"]
}

$ zcode -p "Explain this repository" --json

{
  "provider": "openai-compatible:deepseek",
  "model": "deepseek-chat",
  "text": "ZCode CLI Agent is a terminal-native AI coding assistant...",
  "toolCalls": [],
  "finishReason": "stop"
}

# New flags — preview without executing, write code to files, enable reasoning
$ zcode -p "Create a REST API" --plan           # analyze only, no execution
$ zcode -p "Write a Fibonacci script" --write fib.py
$ zcode -p "Optimize this algorithm" --reasoning  # stream thinking process
$ zcode -p "Deploy to staging" --yolo           # skip approval prompts

---

🚀 Quick Start

Requirements: Node.js ≥ 22 · Bun ≥ 1.0 (recommended for REPL)

git clone https://github.com/zmccyy/ZCode--CLI--agent.git
cd ZCode--CLI--agent/ZCode
bun install

1. Create .env with your LLM provider credentials
2. Verify — bun run doctor --json
3. List models — bun run models
4. Run a prompt — bun run start -p "Explain this repo" --json
5. Optional — npm link to use zcode globally

Windows portable install

Download from Releases or build locally:

powershell -ExecutionPolicy Bypass -File packaging\windows\build-portable.ps1
powershell -ExecutionPolicy Bypass -File packaging\windows\install.ps1 -ZipPath .\dist\zcode-0.1.0-win-x64-portable.zip

Then zcode --help from any terminal. See Windows Install Guide.

Minimal .env (OpenAI-compatible / DeepSeek)

ZCODE_PROVIDER=openai-compatible
ZCODE_OPENAI_PROVIDER=deepseek
ZCODE_OPENAI_MODEL=deepseek-chat
ZCODE_OPENAI_BASE_URL=https://api.deepseek.com/v1
ZCODE_OPENAI_API_KEY=your-api-key

---

💡 Usage

Public CLI (stable)

Command	Description
bun run start --help	Show all commands and flags
bun run doctor --json	Runtime & provider diagnostics
bun run models	List all 12 available models
bun run start -p "..." --json	One-shot prompt, JSON output
bun run start -p "..." --plan	Analyze without executing
bun run start -p "..." --write output.py	Generate and save code
bun run start -p "..." --reasoning	Stream thinking process
bun run start -p "..." --yolo	Auto-approve tool actions

Node.js equivalent:

npm start -- --help
npm run doctor -- --json
npm start -- -p "Summarize this repository" --json

Interactive REPL (Bun)

bun src/entrypoints/cli.tsx

The TUI gives you: streaming responses, tool approval dialogs, LSP diagnostics overlay, persistent task panel (Ctrl+T), transcript viewer (Ctrl+O), command palette (Ctrl+K), help overlay (F1), and full session persistence.

Start in Plan mode:

bun src/entrypoints/cli.tsx --plan

JSON output schema

{
  "provider": "deepseek",
  "model": "deepseek-chat",
  "messageId": "abc-123",
  "text": "Response content",
  "toolCalls": [],
  "finishReason": "stop"
}

Full env var reference → API Reference

---

⌨️ Keybindings

Key	Action
Ctrl+K	Command palette
F1	Help overlay
Ctrl+R	History search / resume session
Ctrl+T	Task panel
Ctrl+O	Transcript viewer
Ctrl+L	Redraw screen
Shift+Tab	Cycle permission mode
Meta+T	Toggle reasoning/thinking
Ctrl+C / Ctrl+D	Interrupt / exit

Keybindings are fully configurable via ~/.claude/keybindings.json. See the keybinding system for details.

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│  CLI Entry  (publicCli / cli.tsx)       │
├─────────────────────────────────────────┤
│  Query Engine  ·  Session & Memory      │
├─────────────────────────────────────────┤
│  Tool System  ·  Permissions  ·  MCP    │
├─────────────────────────────────────────┤
│  Provider Layer  (Anthropic / OpenAI / …)│
└─────────────────────────────────────────┘

Layer	Responsibility
CLI	Command parsing, print mode, interactive REPL
Query Engine	Conversation loop, streaming, context compaction
Tools	File I/O, shell, search, LSP, skills, agents
Providers	Multi-vendor LLM routing & model registry
MCP	External tool server integration

---

📚 Documentation

Topic	Link
Doc Hub	docs/README.md
Requirements	docs/requirements-analysis.md
Implementation	docs/implementation-status.md
Quick Start	docs/getting-started/quick-start.md
System Design	docs/系统设计说明书.md
API / Env Vars	docs/references/api-reference.md
AI Development	docs/guides/ai-development-methodology.md
Demo Walkthrough	docs/guides/demo-walkthrough.md

---

❓ FAQ

Q: Public CLI vs full REPL — what's the difference?

The public build (publicCli.js) exposes stable commands — help, doctor, models, and -p print mode — without booting the full Ink TUI. The complete agent experience lives at bun src/entrypoints/cli.tsx.

Q: Which LLM providers are supported?

Anthropic, AWS Bedrock, Google Vertex, Azure Foundry, and any OpenAI-compatible endpoint. The public print mode validates against OpenAI-compatible providers via .env.

Q: What does --plan mode do?

--plan runs the agent in read-only analysis mode. It explores, reads, and plans — but never edits, writes, or executes. You see what it would do before committing. Remove --plan to execute.

Q: How does --yolo differ from Plan mode?

--yolo auto-approves all tool actions without asking for permission. Useful in CI or when you fully trust the agent. --plan is the opposite — zero execution.

Q: Environment variables not loading?

Place .env in your current working directory. Existing process env vars take precedence over .env.

Q: Node.js or Bun?

Both run the public CLI. Bun is recommended for the full interactive REPL and faster startup.

---

🤝 Contributing

Contributions welcome!

• Report an issue
• Submit a pull request
• Suggest a feature

cd ZCode
bun test          # 801 tests, 795 passing
npx tsc --noEmit  # type-check

---

🌟 Star History

---

📄 License

MIT License — Copyright (c) 2026 zmccyy

---

💞 Acknowledgments

Inspired by the terminal agent paradigm pioneered by Claude Code. Built with Ink, Commander, and the MCP SDK.

Last updated: 2026-06-09