ZCode CLI Agent
zmccyy/ZCode--CLI--agent
Agent de codificação nativo do terminal com suporte multi-modelo e sistema de permissões granulares
Ver no GitHubFramework de agent para codificação via terminal inspirado no Claude Code. Executa tarefas de desenvolvimento em linguagem natural, com acesso a leitura de arquivos, execução de comandos, busca de código e integração com ferramentas MCP, tudo diretamente do shell.
Instalação
npx convez-ai zmccyy/ZCode--CLI--agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de tarefas de desenvolvimento via linha de comando
- Execução de workflows de codificação com múltiplos passos
- Integração com ferramentas MCP e serviços LSP em ambiente local
Veredito

Framework robusto que traz capacidades de agency para o terminal com suporte multi-provider e sistema de tools integrado. Bem estruturado e testado, ideal para desenvolvedores que precisam de workflows de IA scriptáveis e locais.
README
A tradução para o português deste README ainda está na fila.
ZCode CLI Agent
Your terminal-native AI coding agent — describe the task, ship the work.
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 --jsonfor CI pipelines;--write,--plan,--yolo,--reasoningflags - 🖥️ 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
- Create
.envwith your LLM provider credentials - Verify —
bun run doctor --json - List models —
bun run models - Run a prompt —
bun run start -p "Explain this repo" --json - Optional —
npm linkto usezcodeglobally
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.
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!
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