____          _
|__  | ___  __| | ___
  / / / _ \/ _` |/ _ \
 / /_| (_) | (_| |  __/
/____\___/ \__,_|\___|

AI Coding Assistant for your terminal

---

Zode is an open-source, AI-native coding CLI — a terminal-based programming assistant that reads your code, runs commands, searches files, manages git, and more. Built with a microkernel + plugin architecture for extensibility.

Features

• Multi-provider — Anthropic, OpenAI, DeepSeek, Groq, Ollama, or any OpenAI-compatible API
• 25 built-in tools — file ops, shell, code search, git, web fetch
• Plugin system — hot-reloadable plugins with lifecycle hooks
• Permission engine — granular auto/ask/deny rules per tool and command pattern
• Full-screen TUI — Catppuccin theme, gradient borders, animated spinner, markdown rendering
• Rust native — ripgrep-powered search, tree-sitter highlighting, fast diff (with TS fallback)
• Three-level config — global (~/.zode/) → project → directory recursive
• Enterprise ready — remote .well-known policy, sandbox mode, YOLO mode
• Cross-platform — macOS, Linux, Windows

Quick Start

# Install
git clone --recurse-submodules https://github.com/ZSeven-W/zode.git
cd zode
bun install

# Configure a provider
export ANTHROPIC_API_KEY=sk-...    # or any provider
# export OPENAI_API_KEY=sk-...
# export DEEPSEEK_API_KEY=sk-...

# Run
bun run apps/cli/src/index.ts

Usage

# Default provider (from ~/.zode/config.json)
zode

# Specify provider and model
zode --provider anthropic --model claude-sonnet-4-20250514
zode --provider ollama --model llama3
zode --provider deepseek --model deepseek-chat

# YOLO mode (auto-approve tool calls, deny rules still apply)
zode --yolo

# Sandbox mode (restrict file access to project directory)
zode --sandbox

# Resume last session
zode --resume

Slash Commands

Command	Description
/help	Show help
/clear	Clear conversation
/undo	Undo last file edit
/redo	Redo last file edit
/exit	Exit Zode

Configuration

Create ~/.zode/config.json:

{
  "provider": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "sk-...",
      "model": "claude-sonnet-4-20250514"
    },
    "deepseek": {
      "type": "openai",
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    },
    "ollama": {
      "model": "llama3"
    }
  },
  "permissions": {
    "baseline": {},
    "rules": [
      { "tool": "exec", "level": "auto", "conditions": { "commandPrefix": ["git status", "git diff", "ls"] } },
      { "tool": "exec", "level": "deny", "conditions": { "commandBlacklist": ["rm -rf /"] } }
    ]
  }
}

Any OpenAI-compatible API works — set "type": "openai" and provide baseUrl. Use "type": "anthropic" for Anthropic-compatible endpoints.

Architecture

zode/
├── vendor/openpencil/       Git submodule — shared @zseven-w/agent SDK
├── packages/
│   ├── kernel/              Config, permissions, plugins, sessions, loaders
│   ├── native/              Rust NAPI: grep, glob, diff, highlight, watcher
│   └── tui/                 ANSI rendering engine, 15 components
├── plugins/
│   ├── plugin-fs/           read, write, edit, list, delete, move, info (7 tools)
│   ├── plugin-shell/        exec, background, status, kill (4 tools)
│   ├── plugin-search/       grep, glob, find_symbol (3 tools)
│   ├── plugin-git/          status, diff, log, commit, branch, checkout, stash, blame, pr (9 tools)
│   └── plugin-web/          search, fetch (2 tools)
└── apps/cli/                Entry point, TUI REPL, system prompt builder

Key Design Decisions

• Microkernel + plugins — tools are plugins, kernel handles lifecycle, permissions, config
• Shared agent SDK — @zseven-w/agent is shared with OpenPencil via git submodule
• Two-phase permissions — deny rules scan all sources first (cannot be relaxed), then auto/ask by priority
• Rust native with TS fallback — native module optional, CLI works without compilation

Development

bun install                          # Install dependencies
bun run test                         # Run all tests (268 passing)
bun --bun vitest run path/to/test    # Run specific test
npx tsc --noEmit                     # Type check
cd packages/native && cargo build    # Build Rust native module

Project Instructions Compatibility

Zode reads project instructions from multiple formats:

File	Level
CLAUDE.md	Per-directory
AGENTS.md	Per-directory
.claude/instructions.md	Per-directory
.agents/instructions.md	Per-directory
.claude/skills/	Skills (per-directory)
.agents/skills/	Skills (per-directory, overrides .claude)
.claude/mcp.json	MCP servers
.agents/mcp.json	MCP servers (overrides .claude)
~/.zode/instructions.md	Global

License

MIT