zavora-cli

  ███████╗ █████╗ ██╗   ██╗ ██████╗ ██████╗  █████╗
  ╚══███╔╝██╔══██╗██║   ██║██╔═══██╗██╔══██╗██╔══██╗
    ███╔╝ ███████║██║   ██║██║   ██║██████╔╝███████║
   ███╔╝  ██╔══██║╚██╗ ██╔╝██║   ██║██╔══██╗██╔══██║
  ███████╗██║  ██║ ╚████╔╝ ╚██████╔╝██║  ██║██║  ██║
  ╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝

Your AI agent, in the terminal. Built on ADK-Rust.

Install

cargo install --path .

Requires Rust toolchain (rustup, cargo).

Set Up a Provider

Export at least one API key:

export OPENAI_API_KEY="sk-..."
# or: GOOGLE_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY

Or use Ollama locally with no key needed:

OLLAMA_HOST=http://localhost:11434  # optional, this is the default

Usage

# Ask a one-shot question
zavora-cli ask "Explain Rust ownership"

# Interactive chat
zavora-cli --provider openai --model gpt-4.1 chat

# Workflows
zavora-cli workflow sequential "Plan an MVP rollout"
zavora-cli workflow graph "Draft a release plan with risks"

# Health check
zavora-cli doctor

Chat Commands

Once in chat mode, these slash commands are available:

Built-in Tools

The agent has access to these tools during execution:

Context Management

• /usage shows real-time token breakdown by author (user, assistant, tool, system)
• Prompt shows ⚠ (>75%) or 🔴 (>90%) when approaching context limits
• /compact manually summarizes history to reclaim space
• Auto-compaction triggers when configured thresholds are exceeded

Checkpoints and Tangents

• /checkpoint save <label> snapshots session state — persisted to .zavora/checkpoints.json across restarts
• /tangent start branches the session for exploratory work; /tangent end merges or discards

Delegation

/delegate <task> runs a prompt in an isolated sub-agent session and returns the result inline.

Configuration

Profiles

Runtime defaults live in .zavora/config.toml:

[profiles.default]
provider = "openai"
model = "gpt-4.1"
session_backend = "sqlite"
session_db_url = "sqlite://.zavora/sessions.db"
retrieval_backend = "disabled"
tool_confirmation_mode = "mcp-only"
compaction_threshold = 0.75
compaction_target = 0.50
telemetry_enabled = true
guardrail_input_mode = "disabled"
guardrail_output_mode = "disabled"
guardrail_terms = ["password", "secret", "api key"]

zavora-cli profiles list
zavora-cli --profile ops profiles show

Agent Catalogs

Configure agent personas separately from profiles. Precedence: implicit default → global ~/.zavora/agents.toml → local .zavora/agents.toml.

[agents.coder]
description = "Code-focused assistant"
provider = "openai"
model = "gpt-4.1"
tool_confirmation_mode = "always"
allow_tools = ["fs_read", "fs_write", "execute_bash"]
deny_tools = ["execute_bash.rm_*"]

zavora-cli agents list
zavora-cli agents select --name coder
zavora-cli --agent reviewer ask "Review this patch"

Persistent Sessions

zavora-cli --session-backend sqlite --session-db-url sqlite://.zavora/sessions.db chat
zavora-cli --session-backend sqlite --session-db-url sqlite://.zavora/sessions.db sessions list

Advanced Features

Tool Policy and Hooks

Control tool execution with confirmation modes, aliases, allow/deny lists, and hooks:

[profiles.default]
tool_confirmation_mode = "mcp-only"  # never | mcp-only | always
tool_aliases = { "read_file" = "fs_read", "write_file" = "fs_write" }
tool_timeout_secs = 45
tool_retry_attempts = 2

[[profiles.default.hooks.pre_tool]]
name = "block-rm"
match_tool = "execute_bash"
match_args = "rm -rf"
action = "block"
message = "Destructive rm blocked by hook policy"

MCP Integration

Discover and invoke external tool servers per profile:

[[profiles.ops.mcp_servers]]
name = "ops-tools"
endpoint = "https://mcp.example.com/ops"
enabled = true
timeout_secs = 15
auth_bearer_env = "OPS_MCP_TOKEN"
tool_allowlist = ["search_incidents", "get_runbook"]

zavora-cli --profile ops mcp discover

Guardrails

Independent input/output content policy (disabled | observe | block | redact):

zavora-cli --guardrail-input-mode block --guardrail-output-mode redact ask "Summarize this"

Retrieval

Pluggable context injection from local documents or semantic search:

zavora-cli --retrieval-backend local --retrieval-doc-path ./docs/knowledge.md ask "What are our standards?"

Telemetry

Structured JSONL telemetry enabled by default:

zavora-cli telemetry report --limit 2000

Evaluation Harness

zavora-cli eval run --dataset evals/datasets/retrieval-baseline.v1.json --fail-under 0.90

Server Mode and A2A

zavora-cli server serve --host 127.0.0.1 --port 8787
zavora-cli server a2a-smoke

Endpoints: GET /healthz, POST /v1/ask, POST /v1/a2a/ping.

Development

make fmt          # format
make check        # cargo check
make lint         # clippy
make test         # unit tests
make eval         # evaluation harness
make quality-gate # eval + guardrail regression
make ci           # full CI pipeline

Sensitive Config

• profiles show, doctor, and migrate redact session DB URLs by default
• Use --show-sensitive-config for local debugging when full values are needed

Documentation

Current version: v1.1.3