The Problem

Developers need a locally‑run coding assistant that can edit source, run commands, and respect strict permission policies while remaining provider‑agnostic. Existing agents either tie you to a single cloud model or expose the host to uncontrolled side‑effects.

What This Does

zero is a terminal‑first AI coding agent that you own. The binary (cmd/zero/main.go) drives a TUI and a non‑interactive CLI (zero exec). It delegates work to sub‑agents (e.g., internal/agent/loop.go, internal/agent/guardrails.go) that enforce file‑write, shell‑command, and network permissions. The npm wrapper (bin/zero.js) fetches the appropriate Go build from GitHub releases, so the same package works on Linux, macOS, and Windows without extra installers.

Key files:

  • cmd/zero/main.go – entry point for the interactive UI.
  • internal/agent/loop.go – core execution loop that parses a “turn” (JSON‑encoded plan) and invokes tools.
  • internal/agent/guardrails.go – central policy checks that block unsafe actions.
  • internal/agenteval/* – test harness used by zero-perf-bench to evaluate agent behaviour.
  • cmd/zero-perf-bench/* – benchmarking CLI that runs synthetic workloads against the agent.

The repository also ships a sandbox helper (cmd/zero-linux-sandbox/main.go) used on Linux for syscall restriction.

How It Is Wired

  1. Startup – go run ./cmd/zero (or the built zero binary) loads configuration from internal/config (not listed but referenced by internal/agentinit).
  2. Main Loop – internal/agent/loop.go reads a turn (JSON from stdin or file) and calls internal/agent/turn_session.go to maintain state.
  3. Tool Dispatch – internal/agent/parallel_tools.go spawns workers for file edits, shell commands, or HTTP calls. Each worker first passes through internal/agent/guardrails.go, which checks the permission model defined in internal/acp/permission.go.
  4. Output – Results are streamed back as plain text or stream-json (see docs/STREAM_JSON_PROTOCOL.md). The UI renders them in real time, while the CLI returns appropriate exit codes for CI.
  5. Extensibility – MCP servers (internal/mcp/*) and specialist sub‑agents can be registered via the agentinit package; the registration points are in internal/agentinit/agentinit.go.

The only external effect is writing edited files under the current workspace and optionally invoking the sandbox binary (zero-linux-sandbox). No telemetry is sent; all state lives in ~/.local/share/zero (implicitly created by the agent).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/zero-agent
cd zero-agent

# Build the core binary and the Linux sandbox helper
go build -o zero ./cmd/zero
go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox   # optional, Linux only

# Add the binaries to your PATH
export PATH=$PWD:$PATH

# Run the interactive UI
zero

# Or run a single scripted turn (JSON format)
zero exec --output-format stream-json < turns.jsonl

The npm wrapper (npm install -g @gitlawb/zero) works out‑of‑the‑box and will download the matching release assets if they are missing.

Real‑World Use

A CI pipeline can invoke zero exec to automatically fix lint failures. Example workflow step:

- name: Auto‑fix lint
  run: |
    zero exec "fix lint errors in ./pkg" \
      --output-format stream-json > fix-output.jsonl
    git add .
    git commit -m "chore: lint auto‑fix"
    git push

Because guardrails.go blocks any network call without explicit permission, the step cannot exfiltrate code or secrets.

Code Health & Issues

Measured static findings (260 total)

  • HIGH – Deep nesting – 40 occurrences (e.g., internal/cli/app.go, internal/mcp/client_test.go, internal/tools/ask_user.go). Max indentation depth 9.
  • HIGH – Duplicated code – 686 identical 6‑line blocks across 272 files (e.g., bin/zero.js, internal/cli/observability.go, cmd/zero-perf-bench/main.go).
  • HIGH – Oversized files – 19 files > 2 k lines (e.g., internal/agent/loop.go, internal/agent/loop_test.go, internal/cli/app_test.go).

Code‑health audit (6 findings)

  • HIGH – continue-on-error on a correctness step masks failures (.github/workflows/ci.yml, line 53).
  • MEDIUM – No least‑privilege GITHUB_TOKEN permissions (.github/workflows/ci.yml).
  • MEDIUM – Dependabot not configured (.github/dependabot.yml missing).
  • MEDIUM – CI runs npm install instead of npm ci (.github/workflows/*).
  • MEDIUM – Checkout step keeps token; should set persist-credentials: false (.github/workflows/release-artifacts.yml).
  • LOW – Job timeouts undefined (.github/workflows/ci.yml).

These issues are actionable and have explicit fix recommendations in the audit report.

The Bottom Line

zero delivers a self‑hosted, permission‑aware coding agent with strong test coverage and a clear separation between core logic (internal/agent/*) and extensibility points. The codebase suffers from deep nesting, duplicated snippets, and a few oversized files, which increase maintenance cost. CI hygiene needs minor tightening, but the overall architecture is solid for teams that require full control over model choice and local execution.