convez.ai
AgenteDesenvolvimento WebAvançado
zmccyy

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 GitHub
InicialPluginScore · de 0 a 100

Framework 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--agent

1 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

Estrelas
6
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v1.3.0
Issues abertas
0
Contribuidores
3

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.

English | 中文

Netlify Status zread

Stars License Version Node Bun Platform Tests


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.

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)

CommandDescription
bun run start --helpShow all commands and flags
bun run doctor --jsonRuntime & provider diagnostics
bun run modelsList all 12 available models
bun run start -p "..." --jsonOne-shot prompt, JSON output
bun run start -p "..." --planAnalyze without executing
bun run start -p "..." --write output.pyGenerate and save code
bun run start -p "..." --reasoningStream thinking process
bun run start -p "..." --yoloAuto-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

KeyAction
Ctrl+KCommand palette
F1Help overlay
Ctrl+RHistory search / resume session
Ctrl+TTask panel
Ctrl+OTranscript viewer
Ctrl+LRedraw screen
Shift+TabCycle permission mode
Meta+TToggle reasoning/thinking
Ctrl+C / Ctrl+DInterrupt / 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 / …)│
└─────────────────────────────────────────┘
LayerResponsibility
CLICommand parsing, print mode, interactive REPL
Query EngineConversation loop, streaming, context compaction
ToolsFile I/O, shell, search, LSP, skills, agents
ProvidersMulti-vendor LLM routing & model registry
MCPExternal tool server integration

📚 Documentation

TopicLink
Doc Hubdocs/README.md
Requirementsdocs/requirements-analysis.md
Implementationdocs/implementation-status.md
Quick Startdocs/getting-started/quick-start.md
System Designdocs/系统设计说明书.md
API / Env Varsdocs/references/api-reference.md
AI Developmentdocs/guides/ai-development-methodology.md
Demo Walkthroughdocs/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

Star History Chart


📄 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

Ver o original no GitHub

Bom para

Relacionados