zall 0.1.0

A falsifiable, reproducible coding agent CLI — model-agnostic, engineering-grade

Quick Start • Features • Architecture • Configuration • API Reference • Contributing

📦 Installation

pip install zall

Requires Python 3.10+. For optional features:

pip install "zall[tui]"       # inline/full-screen Textual UI (recommended)
pip install "zall[bs4]"      # web_fetch with BeautifulSoup HTML parsing
pip install "zall[images]"    # read_image with Pillow
pip install "zall[dev]"       # development tools (pytest, mypy, ruff)
pip install "zall[all]"       # everything

Works on Windows, macOS and Linux (pure-Python wheel, py3-none-any).

🚀 Quick Start

1. Set your API key

# OpenAI-compatible API
export ZALL_API_KEY="sk-..."
export ZALL_MODEL="gpt-4o"

# Or use Anthropic, Gemini, Ollama, or any OpenAI-compatible provider
export ZALL_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-ant-..."

2. Run a task

# One-shot: fix a bug
zall "refactor the auth module to use async"

# One-shot with verbose output
zall "write a snake game in Python" --verbose

# Interactive REPL
zall

3. Interactive REPL

> /help                    # Show all commands
> /model gpt-4o            # Switch model
> /plan on                 # Read-only mode
> /lsp status              # Live code diagnostics
> /codegraph search MyClass  # Find symbols
> /sandbox process         # Isolated execution
> /eval                    # Evaluate sessions
> /replay <id>             # Replay a session
> /cost                    # Token usage
> /compact                 # Compress context
> /doctor                  # Diagnose setup

✨ Features

🧠 Code Intelligence

🛡️ Safety & Reproducibility

🔌 Extensibility

🎯 Agent Architecture

🎬 Demo

One-shot: Create a Snake game

zall "Create a classic Snake game in Python with pygame"

zall writes the code, tests it, and fixes any issues automatically:

❯ zall "Create a classic Snake game in Python with pygame"
● read_file(file_path="snake.py")
  └ File does not exist yet — will create new
● write_file(file_path="snake.py", content="...")
  └ 142 lines written
● bash(command="python -c 'import pygame; print(pygame.version.ver)'")
  └ pygame 2.6.1
● bash(command="python snake.py")
  └ Process exited with code 0 (game window opened successfully)
● bash(command="pytest test_snake.py -q")
  └ 5 passed in 0.32s
✓ Task completed (8 steps, 2 model calls)

Interactive Bug Fixing

zall  # Start interactive REPL

> /model gpt-4o
> /lsp status
  ✓ pyright: active (2 errors, 3 warnings)
> fix the off-by-one error in binary_search.py
  ● read_file(src/binary_search.py)
  ● edit_file(old_string="...", new_string="...")
  ● bash(command="pytest tests/test_search.py -x -q")
  └ 12 passed in 0.45s
✓ Bug fixed in 3 steps

@file Reference (Claude Code-style)

zall "Refactor the auth module @src/auth.py to use async/await"

Files referenced with @ are automatically injected into the model context — no need for the agent to read_file first.

Multi-step Research Task

zall --yes -j "Study the Collatz stopping time for numbers up to 100000"

The agent runs a full research pipeline: write code → execute → analyze → report → detect and fix its own errors:

✓ Collatz study complete: max stopping time=350 (n=77031),
  mean=107.54 (corrected after agent self-detected its initial
  mean=114.98 included out-of-range memo keys)

PR-0 Hallucination Detection: The agent independently caught its own mistake — the mean calculation included intermediate memo keys outside the study range. It diagnosed the root cause, fixed the code, and re-ran. This is not a prompt-based guard; it's architectural (IPR-0).

🏗️ Architecture

zall/
├── core/              # Primitives: model, agent, chat_state, gate, goal, safety, tool
│   ├── loop.py        # AgentLoop orchestrator (synchronous main controller)
│   ├── loop_config.py # AgentConfig — unified configuration dataclass
│   ├── loop_events.py # LoopEvent, RunEgress, StepResult
│   ├── loop_errors.py # ToolNotFound, AgentRunaway, ContextLimitExceeded
│   ├── tool_kind.py   # ToolKind taxonomy — 19 semantic kinds
│   ├── policies.py    # CompactionPolicy, ReminderPolicy
│   ├── agent.py       # AgentDefinition + ToolsetPreset + CapabilityMode
│   ├── chat_state.py  # Actor-based message management
│   ├── safety.py      # Three-state context_judge (whitelist/greylist/blacklist)
│   ├── gate.py        # ConfirmGate state machine (8-state)
│   └── verifiability.py  # RunRecorder (chain-hash) + TrustAnchor (ed25519)
├── cli/               # Rich REPL, 25+ slash commands, replay, session management
├── tools/             # 21 tools: read/write/edit/bash/grep/lsp/codegraph/…
├── adapters/          # OpenAI-compat, Anthropic, Gemini, Ollama
├── codegraph/         # Multi-language symbol indexer
├── lsp/               # LSP client (pyright, rust-analyzer, gopls, clangd)
├── sandbox/           # Process isolation (worktree/process/bwrap/container)
├── plugin/            # Plugin system with marketplace
├── mcp/               # MCP client for Model Context Protocol
├── safety/            # Rule loader and config management
├── eval/              # 5-dimensional R-Metric evaluation
└── skills/            # Skill loader and executor

Key Design Principles

1. Model Agnostic (IPR-3): Core never imports model SDKs. ModelAdapter is a Protocol — adapters are pluggable.
2. Immutable First: All Pydantic models are frozen=True. AgentConfig is a frozen dataclass.
3. Declarative Safety: context_judge uses rule matching (fnmatch glob) — no model calls, no arbitrary code.
4. Dual Safety Nets: GitProtect (git stash) + CheckpointManager (filesystem snapshots).
5. Full Audit Trail: RunRecorder + chain-hash SHA-256 + TrustAnchor ed25519 signing.
6. Self-Falsifying (PR-0): Architectural hallucination detection, not prompt-based.

⚙️ Configuration

config.toml

Create ~/.zall/config.toml:

[general]
default_model = "gpt-4o"
timeout = 300  # seconds (default: 300, was 120 in v0.4.2)

[openai]
api_key = "sk-..."
api_base = "https://api.openai.com/v1"

[anthropic]
api_key = "sk-ant-..."

[gemini]
api_key = "..."

[ollama]
api_base = "http://localhost:11434"
default_model = "llama3"

Environment Variables

Agent Definition Files

Place .md files in .zall/agents/ with YAML frontmatter:

---
name: my-agent
description: Custom agent for Python development
toolset: zall
permission_mode: auto
model: gpt-4o
---
Your custom system prompt here...

📖 API Reference

Python API

from zall.core.builder import AgentBuilder
from zall.core.loop_config import AgentConfig
from zall.core.goal import GoalType
from zall.cli.orchestrator import run

# One-shot execution
egress = run(
    "refactor the auth module",
    model="gpt-4o",
    judge_mode="none",
    stream=True,
)

# Programmatic agent loop
loop = (
    AgentBuilder()
    .with_model(adapter)
    .with_tools(tools)
    .with_goal(goal)
    .with_config(AgentConfig(max_steps=30, stream=True))
    .build()
)
egress = loop.run(system_prompt="You are a coding assistant...")

CLI Reference

zall [task] [options]

Options:
	  --model TEXT       Model name (overrides config)
	  --yes, -y          Auto-accept greylist actions
	  --strict, -S       Strict mode: enable full confirm/downgrade gates
	  --judge MODE       Judge mode: none (default), system
	  --json             Output events as NDJSON
	  --no-stream        Disable token streaming
	  --max-steps N      Maximum steps before termination
	  --init             Initialize .zall/ config in current directory
	  --verbose          Show full tool output
	  --version, -V      Show version

Commands in REPL:
  /help, /model, /plan, /lsp, /codegraph, /sandbox,
  /chatstate, /plugin, /add, /drop, /diff, /search,
  /web, /git, /commit, /sessions, /resume, /replay,
  /eval, /cost, /compact, /undo, /retry, /doctor,
  /checkpoint, /clear, /suggest, /learn

🆚 Comparison

vs Claude Code / Copilot / Cursor

🧪 Development

# Clone and install
git clone https://github.com/Qinrayn/zall.git
cd zall
pip install -e ".[dev,bs4,images]"

# Run tests
python -m pytest tests/ -q

# Type check
mypy src/zall/

# Lint
ruff check src/

# Build
python -m build

Test Structure

The project follows IPR-0: every invariant has a counterexample test. Tests are organized by component:

tests/
├── test_loop_invariants.py          # AgentLoop core invariants
├── test_safety_invariants.py        # context_judge rules
├── test_gate_invariants.py          # ConfirmGate state machine
├── test_verifiability_invariants.py # Chain-hash timeline
├── test_read_file_invariants.py     # ReadFileTool invariants
├── test_bash_invariants.py          # BashTool invariants
├── test_chat_state_invariants.py    # ChatState actor
├── test_lsp_invariants.py           # LSP integration
├── test_sandbox_invariants.py       # Sandbox isolation
└── ...

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

• Report bugs: github.com/Qinrayn/zall/issues
• Feature requests: Open an issue with the enhancement label
• Pull requests: PRs are reviewed within 48 hours
• Security issues: See SECURITY.md

📄 License

MIT © 2026 qinrayn (Yuhan Zhang)

🙏 Acknowledgements

• xAI Grok Build — Architecture inspiration for agent definition, tool taxonomy, and modular design
• Claude Code — Interaction design patterns
• OpenAI Function Calling — API compatibility
• MCP Specification — Model Context Protocol integration