# Gitlawb/zero: a terminal coding agent that keeps the model choice and the permission policy in your hands

> Zero is a Go-based AI coding agent for the local terminal, installed from npm or a shell script, with multi-provider model support and a permission layer over file writes and shell commands. The design is coherent; the documentation is thinner than the feature list suggests.

**Gitlawb/zero** — The coding agent that answers to you, your model, your machine, your rules.

- Repository: https://github.com/Gitlawb/zero
- Website: https://zero.gitlawb.com
- Stars: 1,683 · Forks: 193
- Language: Go
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/gitlawb-zero

## What Gitlawb/zero is for, and who it is not for

Most coding agents make you a guest in someone else's product. You get their model, their hosted session store, their permission model. Zero inverts that. It runs in your terminal, talks to the provider you configure, and writes sessions to local disk. The README states plainly that sessions are "stored on disk, searchable, resumable, and never uploaded as telemetry by Zero." That single sentence is the whole pitch.

The target user is an engineer who already lives in a shell and has opinions about which model to call. The provider list is unusually wide for a project this size: OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Mistral, xAI, Qwen, Kimi, GitHub Models, Ollama, LM Studio, plus any OpenAI- or Anthropic-compatible endpoint. If you pay for two of those and want to switch per task, Zero is built for exactly that.

It is not for someone who wants a browser tab and a chat box. There is a TUI, not a web UI. It is also not for a team that needs centrally managed policy: the permission model described in the README is local and session-scoped, and the README does not describe any server-side enforcement.

## How the agent loop, permissions and sessions fit together

Three pieces are visible from the repository layout and the README. The first is the agent loop itself, under internal/agent/loop.go, which the README uses as its own example prompt. The second is the permission and sandbox layer: file writes, shell commands, network access and out-of-workspace writes all pass through a policy you can inspect with /permissions and /tools. The third is the session store, which is local, resumable and forkable.

The sandbox is where the platform split matters. On Linux, native sandboxing needs a separate helper binary, zero-linux-sandbox, built from ./cmd/zero-linux-sandbox, with an optional zero-seccomp compatibility wrapper. macOS needs no extra helper. Windows source builds can use the main zero.exe as the sandbox helper, while release archives ship standalone Windows helper executables. That is not incidental detail: if you build on Linux and skip the helper, you are running with a weaker isolation story than the README's safety section implies.

Sessions are the other half. /resume and /rewind continue or roll back a session, /new starts fresh while leaving the old session on disk, and /btw runs a side question in an isolated fork so it never pollutes the main conversation. The headless path mirrors this with zero exec --resume and zero exec --fork <session-id>. The design assumption is that agent transcripts are cheap to keep and expensive to lose.

## Installing Zero and running a first headless task

The npm route is the shortest. The package is @gitlawb/zero, and the README notes the wrapper pulls a platform build as an optional dependency straight from the npm registry, with no install scripts and no downloads outside npm. Bun, pnpm and yarn behave the same way.

```bash
npm install -g @gitlawb/zero
zero
```

Running zero with no arguments opens the TUI and, on a first run, a setup wizard that asks you to pick a provider and model. If you would rather stay out of the wizard, the CLI has direct equivalents.

```bash
zero setup
zero providers list
zero models list
zero doctor
```

For API providers, export the matching key before setup. The README lists OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, AIMLAPI_API_KEY, LONGCAT_API_KEY, FIREWORKS_API_KEY, MINIMAX_API_KEY and MINIMAXI_API_KEY. Local models need no key: run Ollama or LM Studio, then use zero setup or zero providers detect.

Once a provider is active, the scriptable path is zero exec. This is the form that matters for CI, because the README says it returns meaningful exit codes.

```bash
zero exec "explain internal/agent/loop.go"
zero exec --model claude-sonnet-4.5 "refactor the config loader"
zero exec --use-spec "add rate limiting to the API client"
zero exec --worktree "try the migration in an isolated worktree"
```

The --worktree flag is the one to reach for first on a real repository, since it keeps the attempt out of your working tree. For programmatic use, the stream-JSON contract is the interface, and the README points at docs/STREAM_JSON_PROTOCOL.md for it.

```bash
zero exec --input-format stream-json --output-format stream-json < turns.jsonl
```

If you build from source instead, the requirement is Go 1.26.6 or newer, and on Linux you want both binaries on PATH in the same directory.

```bash
git clone https://github.com/Gitlawb/zero.git
cd zero
go build -o zero ./cmd/zero
go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
```

## Where Zero gets awkward: sandbox helpers, packaging and thin docs

The most concrete limitation is the Linux sandbox helper. Native sandboxing depends on a second binary that must sit next to zero on PATH. Nothing in the README's install section enforces that placement, and the failure mode is quiet: the agent runs, but with less isolation than you think you configured. The README says ~/.local/bin is "a good default", which is guidance, not a check. Run zero doctor after installing and confirm what it reports.

Windows has its own rough edge. The README states that Windows on ARM runs the x64 build under emulation, and that source builds can use zero.exe as the sandbox helper while release archives ship standalone helpers. That is three different Windows configurations depending on how you installed, which is a lot of variation for a platform where you cannot easily tell which one you got.

The documentation is incomplete. The README's Safety Model section is truncated in the repository text, and the deeper documents it references, docs/INSTALL.md, docs/NPM_PACKAGING.md and docs/STREAM_JSON_PROTOCOL.md, are not reproduced here. The README does not document rollback semantics for permission decisions, and it does not describe what happens when a sandbox helper is missing. Treat the safety model as something to verify by reading the source under internal/, not as something the README settles.

Finally, the release cadence is fast. v0.6.0, v0.7.0 and v0.8.0 landed within roughly a month of each other, with the last push on 2026-08-21. Pinning a version for CI is advisable; tracking main is not.

## How Zero differs from Aider and from hosted agents

Aider is the closest well-known comparison in the terminal-agent space, and the difference is in where control sits. Aider's model is repository-map-driven editing with git commits as the primary artifact. Zero's model is permission-policy-driven execution: the README frames file writes, shell commands, network access and out-of-workspace writes as things that go through a policy you can inspect, and it adds a sandbox helper on Linux that Aider does not ship. Zero also carries a full TUI with provider pickers, image input and slash commands, plus a headless exec mode with text, JSON and stream-JSON output.

Against hosted agents, the split is simpler. Hosted tools give you a managed session store and a web interface; Zero gives you local sessions and a terminal. The README's claim that sessions are never uploaded as telemetry is the trade: you own the storage, and you own the backups.

The multi-provider breadth is the other differentiator. Custom profiles are first-class, not a workaround. The README shows adding an OpenAI-compatible profile for a specific region with a named model, base URL and API key environment variable, which is the same mechanism you would use for any internal gateway.

```bash
zero providers add custom-openai-compatible \
  --name minimax-openai \
  --model MiniMax-M3 \
  --base-url https://api.minimax.io/v1 \
  --api-key-env MINIMAX_API_KEY \
  --set-active
```

## Licence, maintenance and the cost of upgrading

Zero is MIT licensed, stated in both the repository metadata and package.json, and the LICENSE file is at the repository root. MIT is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and permission notice travel with it. That is a description of the licence text, not legal advice; if you are embedding Zero in a distributed product, have counsel read the actual LICENSE file.

The npm wrapper adds a second set of obligations worth knowing about. The package depends on agent-browser and tuistory, and declares engines.node >=18 with os entries for linux, darwin, win32 and android and cpu entries for x64 and arm64. Those dependencies carry their own licences, and the wrapper's optional-dependency mechanism means the binary you actually execute arrives through a different channel than the JavaScript you install. Read docs/NPM_PACKAGING.md before you vendor it.

Maintenance cost is dominated by the provider surface. Each provider you configure is another API key environment variable, another base URL and another model name that can drift. The CLI tools for this are zero providers list, zero models list and zero doctor. Upgrading is cheap in the common case: npm install -g @gitlawb/zero pulls the new version and its matching platform build. It is more expensive if you build from source, because the Go directive in go.mod is 1.26.6 and the Makefile pins its own tool versions, including golangci-lint v2.12.2, deadcode v0.46.0 and govulncheck v1.3.0. The Makefile's lint target is deliberately dependency-light, running gofmt -l over tracked Go files plus go vet, so a baseline check needs no extra tooling. Given the release cadence, budget for reading CHANGELOG.md on each bump rather than assuming drop-in compatibility.

## Conclusion

Adopt Zero if you already run a terminal-heavy workflow and want to point an agent at whichever provider you are paying for, including a local Ollama or LM Studio endpoint. Do not adopt it if you need a hosted service with a web UI, or if you expect the repository to document every flag: the README stops before the safety model finishes, and docs/STREAM_JSON_PROTOCOL.md, docs/INSTALL.md and docs/NPM_PACKAGING.md are referenced but not reproduced here. Verify three things first: that your Go toolchain is 1.26.6 or newer if you build from source, that zero and zero-linux-sandbox end up in the same directory on PATH on Linux, and that zero doctor reports your provider as reachable before you let the agent touch a real repository.

## FAQ

### What is Gitlawb/zero?

It is an AI coding agent that runs in your local terminal, written in Go and licensed MIT. According to the README it can inspect a repository, edit files, run commands, use browser and terminal helpers, and keep durable local sessions while you choose the model and the permission level.

### How do I install the Zero coding agent?

The README gives npm as the primary route: npm install -g @gitlawb/zero, then run zero. There are also install scripts for Linux, macOS and Windows PowerShell, and a source build that requires Go 1.26.6 or newer.

### Which model providers does Zero support?

The README lists OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Mistral, xAI, Qwen, Kimi, GitHub Models, Ollama, LM Studio, and any OpenAI- or Anthropic-compatible endpoint. Local models work through Ollama or LM Studio, configured with zero setup or zero providers detect.

### Can I use Zero without the interactive TUI?

Yes. The zero exec subcommand is scriptable and supports text, JSON and stream-JSON input and output, isolated worktrees via --worktree, spec-first runs via --use-spec, and exit codes intended for CI. The stream-JSON contract is documented in docs/STREAM_JSON_PROTOCOL.md.

### Where are Zero's sessions stored?

On local disk. The README states that sessions are stored on disk, searchable and resumable, and are never uploaded as telemetry by Zero. The TUI exposes /resume and /rewind for continuing or rolling back a session.

### What does the zero-linux-sandbox binary do?

It provides native sandboxing on Linux and must be built separately and placed in the same directory as zero on PATH. macOS does not need an extra helper binary, and Windows source builds can use the main zero.exe as their sandbox helper.

## Sources

- [Official documentation](https://zero.gitlawb.com)
- [Official README](https://github.com/Gitlawb/zero#readme)
- [Project repository](https://github.com/Gitlawb/zero)
- [Release notes](https://github.com/Gitlawb/zero/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gitlawb-zero