# Zero CLI

Zero CLI is an open-source coding-agent CLI for cloud and local model providers.

Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported backends while keeping one terminal-first workflow: prompts, tools, agents, MCP, slash commands, and streaming output.

[![PR Checks](https://github.com/Duheso/ZeroCLI/actions/workflows/pr-checks.yml/badge.svg?branch=main)](https://github.com/Duheso/ZeroCLI/actions/workflows/pr-checks.yml)
[![Release](https://img.shields.io/github/v/tag/Gitlawb/zero?label=release&color=0ea5e9)](https://github.com/Duheso/ZeroCLI/tags)
[![Discussions](https://img.shields.io/badge/discussions-open-7c3aed)](https://github.com/Duheso/ZeroCLI/discussions)
[![Security Policy](https://img.shields.io/badge/security-policy-0f766e)](SECURITY.md)
[![License](https://img.shields.io/badge/license-MIT-2563eb)](LICENSE)


[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Tribunal do Conselho](#️-tribunal-do-conselho--council-tribunal) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community)

## Why Zero CLI

- Use one CLI across cloud APIs and local model backends
- Save provider profiles inside the app with `/provider`
- Run with OpenAI-compatible services, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported providers
- Keep coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
- Invoke the **Tribunal do Conselho** to have 5 AI advisors debate any problem from radically different perspectives
- Use the bundled VS Code extension for launch integration and theme support

## Quick Start

### Prerequisites

**Node.js 20 or later is required.** Verify with `node --version`.

If your distro ships an older Node.js (common on AlmaLinux, CentOS, Fedora, RHEL), upgrade first:

<details>
<summary>AlmaLinux / CentOS / RHEL / Fedora — upgrade Node.js</summary>

Using [nvm](https://github.com/nvm-sh/nvm) (recommended, no root required):

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc          # or ~/.zshrc / ~/.profile
nvm install 22
nvm use 22
node --version            # should print v22.x.x
```

Or using the NodeSource RPM repository (requires root):

```bash
# Fedora / RHEL 9+ / AlmaLinux 9+
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs
```

</details>

### Install

```bash
npm install -g @duheso/zerocli
```

If the install later reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting Zero CLI.

### Start

```bash
zero
```

Inside Zero CLI:

- run `/provider` for guided provider setup and saved profiles
- run `/onboard-github` for GitHub Models onboarding

### Fastest OpenAI setup

macOS / Linux:

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

zero
```

Windows PowerShell:

```powershell
$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

zero
```

### Fastest local Ollama setup

macOS / Linux:

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

zero
```

Windows PowerShell:

```powershell
$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

zero
```

### Using COPILOT_* env vars (remote or local server)

The `COPILOT_*` variables are an alternative mapping supported by the launcher. They are translated to the native OpenAI-compatible vars at startup, so you never need to set both.

**Remote server — macOS / Linux:**

```bash
export COPILOT_PROVIDER_BASE_URL=http://10.11.36.131:3053/v1
export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_API_KEY=not-required
export COPILOT_MODEL=gpt-oss-120b

zero
```

**Remote server — Windows PowerShell:**

```powershell
$env:COPILOT_PROVIDER_BASE_URL="http://10.11.36.131:3053/v1"
$env:COPILOT_PROVIDER_TYPE="openai"
$env:COPILOT_PROVIDER_API_KEY="not-required"
$env:COPILOT_MODEL="gpt-oss-120b"

zero
```

**Localhost — macOS / Linux:**

```bash
export COPILOT_PROVIDER_BASE_URL=http://localhost:3053/v1
export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_API_KEY=not-required
export COPILOT_MODEL=gpt-oss-120b

zero
```

**Localhost — Windows PowerShell:**

```powershell
$env:COPILOT_PROVIDER_BASE_URL="http://localhost:3053/v1"
$env:COPILOT_PROVIDER_TYPE="openai"
$env:COPILOT_PROVIDER_API_KEY="not-required"
$env:COPILOT_MODEL="gpt-oss-120b"

zero
```

| Variable | Maps to | Description |
|---|---|---|
| `COPILOT_PROVIDER_BASE_URL` | `OPENAI_BASE_URL` | Base URL of the OpenAI-compatible server |
| `COPILOT_PROVIDER_TYPE` | activates OpenAI shim | Set to `openai` for any `/v1` endpoint |
| `COPILOT_PROVIDER_API_KEY` | `OPENAI_API_KEY` | API key; use `not-required` for local servers |
| `COPILOT_MODEL` | `OPENAI_MODEL` | Model name served by the endpoint |
| `COPILOT_TOOLLESS` | `OPENAI_TOOLLESS` | Set to `1` to disable tool calling (text-only mode) |

> **Note:** `COPILOT_*` vars are only applied when the matching native var (`OPENAI_BASE_URL`, etc.) is not already set, so the two styles can coexist without conflict.

### Using Ollama's launch command

If you have [Ollama](https://ollama.com) installed, you can skip the env var setup entirely:

```bash
ollama launch zero --model qwen2.5-coder:7b
```

This automatically sets `ANTHROPIC_BASE_URL`, model routing, and auth so all API traffic goes through your local Ollama instance. Works with any model you have pulled — local or cloud.

## Setup Guides

Beginner-friendly guides:

- [Non-Technical Setup](docs/non-technical-setup.md)
- [Windows Quick Start](docs/quick-start-windows.md)
- [macOS / Linux Quick Start](docs/quick-start-mac-linux.md)

Advanced and source-build guides:

- [Advanced Setup](docs/advanced-setup.md)
- [Android Install](ANDROID_INSTALL.md)

## Supported Providers

| Provider | Setup Path | Notes |
| --- | --- | --- |
| OpenAI-compatible | `/provider` or env vars | Works with OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio, and other compatible `/v1` servers |
| Gemini | `/provider` or env vars | Supports API key, access token, or local ADC workflow on current `main` |
| GitHub Models | `/onboard-github` | Interactive onboarding with saved credentials |
| Codex OAuth | `/provider` | Opens ChatGPT sign-in in your browser and stores Codex credentials securely |
| Codex | `/provider` | Uses existing Codex CLI auth, Zero CLI secure storage, or env credentials |
| Ollama | `/provider`, env vars, or `ollama launch` | Local inference with no API key |
| Atomic Chat | `/provider`, env vars, or `bun run dev:atomic-chat` | Local Model Provider; auto-detects loaded models |
| Bedrock / Vertex / Foundry | env vars | Additional provider integrations for supported environments |

## What Works

- **Tool-driven coding workflows**: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
- **Streaming responses**: Real-time token output and tool progress
- **Tool calling**: Multi-step tool loops with model calls, tool execution, and follow-up responses
- **Images**: URL and base64 image inputs for providers that support vision
- **Provider profiles**: Guided setup plus saved `.zerocli-profile.json` support
- **Local and remote model backends**: Cloud APIs, local servers, and Apple Silicon local inference
- **Tribunal do Conselho**: Multi-agent deliberation with 5 AI advisors modeled on historical figures

## ⚖️ Tribunal do Conselho — Council Tribunal

The **Tribunal do Conselho** is a signature Zero CLI skill that convenes a panel of 5 AI advisors to debate any question, dilemma, or decision from radically different perspectives. Rather than getting a single AI opinion, you get a full deliberation — with agreements, disagreements, and a final synthesized verdict.

This is invaluable for complex decisions, brainstorming, code architecture review, life choices, or any situation where a single perspective is not enough.

### How to invoke

```
/council  Should I leave my job and start a company?
/council  Review this architecture — microservices vs monolith for a 3-person team
/council  I'm getting married in 6 months. How should I prepare financially?
```

Aliases also work: `/conselho` and `/tribunal`.

Or just type naturally and the model will invoke it:

```
invoco o tribunal do conselho — quero largar meu emprego
```

### How it works

```
User prompt
    │
    ▼
📨 Mensageiro (Messenger)
    Analyzes complexity → generates 3-13 clarifying questions
    │
    ▼
❓ AskUserQuestion (per question)
    Collects all context from the user
    │
    ▼
⚖️ TRIBUNAL DO CONSELHO — Round 1 / 2 / 3
    5 advisors deliberate in parallel
    React to each other, agree, disagree, debate
    │
    ▼
🔍 Convergence check after Round 3
    ├── Consensus reached → proceed to verdict
    └── Still diverging → ⚠️ 2 extra rounds invoked
                             "DIVERGÊNCIA NO CONSELHO — Rodadas extras invocadas!"
    │
    ▼
📜 Síntese — Synthesizer consolidates the verdict
    │
    ▼
✅ Final verdict delivered to the user
```

### The Classic Council (default pack)

Five legendary figures with radically different worldviews ensure every angle of your problem is covered:

| Advisor | Role | Focus |
|---|---|---|
| 🏛️ **Marco Aurélio** | O Estoico / Líder Consciente | Focus on what you can control, stay calm under pressure, act with ethics and reason |
| 🗡️ **Maquiavel** | O Estrategista Realista | Pragmatic, cold analysis — human risks, power dynamics, and effective action without idealism |
| ⚗️ **Marie Curie** | A Cientista Analítica | Demands data, facts, and experimentation — breaks problems logically before committing |
| 🎨 **Leonardo da Vinci** | O Inovador Criativo | Lateral thinking, unexpected connections, completely original solutions |
| 👑 **Catarina, a Grande** | A Executora de Longo Prazo | Evaluates long-term impact, master of ambitious plans executed with patience |

### Council Packs

Switch the deliberating panel by passing `pack:` in your prompt or using the tool parameter:

| Pack | Members | Best for |
|---|---|---|
| `default` | Marco Aurélio, Maquiavel, Marie Curie, Da Vinci, Catarina | General decisions, life dilemmas, strategy |
| `strategy` | Sun Tzu, Clausewitz, Bismarck, Napoleão, Genghis Khan | Competitive strategy, negotiations, conflict |
| `creativity` | Tesla, Ada Lovelace, Frida Kahlo, Mozart, Steve Jobs | Innovation, creative blocks, product design |
| `leadership` | Churchill, Mandela, Cleópatra, Lincoln, Ashoka | Leadership decisions, team challenges, governance |

### Dynamic rounds

The debate starts with **3 rounds** (minimum). After round 3, convergence is automatically detected:

- **Consensus reached** → debate closes, verdict synthesized immediately
- **Significant divergence** → a bold visual alert appears and 2 extra rounds are invoked:

```
⚠️  DIVERGÊNCIA NO CONSELHO — Rodadas extras invocadas!
🔥  O Tribunal detectou divergências significativas. Invocando 2 rodadas extras finais...
```

### Dynamic clarification questions

The Messenger automatically calibrates the number of clarifying questions (3–13) based on the detail level of your prompt:
- **Vague / short prompt** → 8–13 questions to fill all gaps
- **Moderate detail** → 5–7 focused questions
- **Detailed prompt** → 3–5 targeted questions on remaining blind spots

### Live progress streaming

You see the debate unfold in real time as each round completes — no waiting until the end to see results. Each advisor's response streams as it finishes, round by round.

---



Zero CLI supports multiple providers, but behavior is not identical across all of them.

- Anthropic-specific features may not exist on other providers
- Tool quality depends heavily on the selected model
- Smaller local models can struggle with long multi-step tool flows
- Some providers impose lower output caps than the CLI defaults, and Zero CLI adapts where possible

For best results, use models with strong tool/function calling support.

## Agent Routing

Zero CLI can route different agents to different models through settings-based routing. This is useful for cost optimization or splitting work by model strength.

Add to `~/.zerocli/settings.json`:

```json
{
  "agentModels": {
    "deepseek-chat": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-chat",
    "Plan": "gpt-4o",
    "general-purpose": "gpt-4o",
    "frontend-dev": "deepseek-chat",
    "default": "gpt-4o"
  }
}
```

When no routing match is found, the global provider remains the fallback.

> **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep this file private and do not commit it to version control.

## Web Search and Fetch

By default, `WebSearch` works on non-Anthropic models using DuckDuckGo. This gives GPT-4o, DeepSeek, Gemini, Ollama, and other OpenAI-compatible providers a free web search path out of the box.

> **Note:** DuckDuckGo fallback works by scraping search results and may be rate-limited, blocked, or subject to DuckDuckGo's Terms of Service. If you want a more reliable supported option, configure Firecrawl.

For Anthropic-native backends and Codex responses, Zero CLI keeps the native provider web search behavior.

`WebFetch` works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.

Set a [Firecrawl](https://firecrawl.dev) API key if you want Firecrawl-powered search/fetch behavior:

```bash
export FIRECRAWL_API_KEY=your-key-here
```

With Firecrawl enabled:

- `WebSearch` can use Firecrawl's search API while DuckDuckGo remains the default free path for non-ZeroCLI models
- `WebFetch` uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly

Free tier at [firecrawl.dev](https://firecrawl.dev) includes 500 credits. The key is optional.

---

## Headless gRPC Server

Zero CLI can be run as a headless gRPC service, allowing you to integrate its agentic capabilities (tools, bash, file editing) into other applications, CI/CD pipelines, or custom user interfaces. The server uses bidirectional streaming to send real-time text chunks, tool calls, and request permissions for sensitive commands.

### 1. Start the gRPC Server

Start the core engine as a gRPC service on `localhost:50051`:

```bash
npm run dev:grpc
```

#### Configuration

| Variable | Default | Description |
|-----------|-------------|------------------------------------------------|
| `GRPC_PORT` | `50051` | Port the gRPC server listens on |
| `GRPC_HOST` | `localhost` | Bind address. Use `0.0.0.0` to expose on all interfaces (not recommended without authentication) |

### 2. Run the Test CLI Client

We provide a lightweight CLI client that communicates exclusively over gRPC. It acts just like the main interactive CLI, rendering colors, streaming tokens, and prompting you for tool permissions (y/n) via the gRPC `action_required` event.

In a separate terminal, run:

```bash
npm run dev:grpc:cli
```

*Note: The gRPC definitions are located in `src/proto/zero.proto`. You can use this file to generate clients in Python, Go, Rust, or any other language.*

---

## Source Build And Local Development

```bash
bun install
bun run build
node dist/cli.mjs
```

Helpful commands:

- `bun run dev`
- `bun test`
- `bun run test:coverage`
- `bun run security:pr-scan -- --base origin/main`
- `bun run smoke`
- `bun run doctor:runtime`
- `bun run verify:privacy`
- focused `bun test ...` runs for the areas you touch

## Testing And Coverage

Zero CLI uses Bun's built-in test runner for unit tests.

Run the full unit suite:

```bash
bun test
```

Generate unit test coverage:

```bash
bun run test:coverage
```

Open the visual coverage report:

```bash
open coverage/index.html
```

If you already have `coverage/lcov.info` and only want to rebuild the UI:

```bash
bun run test:coverage:ui
```

Use focused test runs when you only touch one area:

- `bun run test:provider`
- `bun run test:provider-recommendation`
- `bun test path/to/file.test.ts`

Recommended contributor validation before opening a PR:

- `bun run build`
- `bun run smoke`
- `bun run test:coverage` for broader unit coverage when your change affects shared runtime or provider logic
- focused `bun test ...` runs for the files and flows you changed

Coverage output is written to `coverage/lcov.info`, and Zero CLI also generates a git-activity-style heatmap at `coverage/index.html`.
## Repository Structure

- `src/` - core CLI/runtime
- `scripts/` - build, verification, and maintenance scripts
- `docs/` - setup, contributor, and project documentation
- `python/` - standalone Python helpers and their tests
- `vscode-extension/zero-vscode/` - VS Code extension
- `.github/` - repo automation, templates, and CI configuration
- `bin/` - CLI launcher entrypoints

## VS Code Extension

The repo includes a VS Code extension in [`vscode-extension/zero-vscode`](vscode-extension/zero-vscode) for Zero CLI launch integration, provider-aware control-center UI, and theme support.

## Security

If you believe you found a security issue, see [SECURITY.md](SECURITY.md).

## Community

- Use [GitHub Discussions](https://github.com/Duheso/ZeroCLI/discussions) for Q&A, ideas, and community conversation
- Use [GitHub Issues](https://github.com/Duheso/ZeroCLI/issues) for confirmed bugs and actionable feature work

## Contributing

Contributions are welcome.

For larger changes, open an issue first so the scope is clear before implementation. Helpful validation commands include:

- `bun run build`
- `bun run test:coverage`
- `bun run smoke`
- focused `bun test ...` runs for files and flows you changed


## Disclaimer

Zero CLI is an independent community project and is not affiliated with, endorsed by, or sponsored by Anthropic.

Zero CLI originated from the Claude Code codebase and has since been substantially modified to support multiple providers and open use. "Claude" and "Claude Code" are trademarks of Anthropic PBC. See [LICENSE](LICENSE) for details.

## License

See [LICENSE](LICENSE).
