Who this is for

Use zero-employee if you are experimenting with AI agents that create code, docs, designs, or reviews, and you need a better answer to:

• What work exists?
• Who or what is blocked?
• Which decisions were made?
• Which files prove the work is done?
• Can a new person or agent resume without reading a giant chat transcript?

You only need basic command-line and Python familiarity to start. The first workflow is local: install the package, scaffold a tiny example corpus, capture one idea, and ask zeo what to do next.

What zeo gives you

• A corpus: a normal git repository that stores your work records.
• Intake files: quick notes for raw ideas before you know the exact work.
• SOWs: “Statements of Work” with machine-checked status, scope, and done criteria.
• Rulings: durable decisions that answer design or governance questions.
• Boards and triage: generated views that show what needs attention.
• Hooks and scaffolding: optional guardrails for teams using agents, Codex, Claude Code, Cursor, Gemini, or plain git.
• Session tooling: branch/worktree/session cleanup for multi-agent work.

The important idea: chat is temporary; the corpus is the durable record.

Install

Recommended:

uv tool install zero-employee
zeo --version

If you do not have uv yet:

python -m pip install uv
uv tool install zero-employee

Standard pip also works:

python -m pip install zero-employee
zeo --version

Requirements: Python 3.11 or newer.

The old sow-lint executable name still works as a compatibility alias for older corpora and historical checks. New docs, scripts, and CI should use zeo. In GitHub Actions, prefer the check/workflow name zeo-sow-ruling-gate for SOW/ruling validation.

Upgrade an existing install:

uv tool upgrade zero-employee

If zeo --version still shows an old version, your shell is finding a different zeo executable first. Run which zeo to see which one.

10-minute first run

This creates a disposable practice corpus in /tmp, captures one idea, and shows the basic dashboard.

mkdir -p /tmp/zeo-demo
cd /tmp/zeo-demo
git init
git branch -m main
zeo init
git add .gitignore CLAUDE.md claude-md governance intake
git commit -m "initialize zeo corpus"
zeo intake "add a health-check endpoint to the demo service"
zeo
zeo triage

What just happened:

1. zeo init created the minimum files that make this directory a ZEO corpus.
2. zeo intake ... saved your idea as a small Markdown file under intake/.
3. zeo printed the orientation dashboard.
4. zeo triage showed whether anything needs a decision, a successor, or cleanup.

Next: follow the full Getting started guide.

The beginner path

Read these in order:

1. Getting started — copy/paste setup and first useful commands.
2. Mental model and glossary — corpus, SOW, ruling, stream, seat, session.
3. Tutorial — convert one raw idea into a grounded SOW.
4. Codex swap guide — if you want Codex Master/Sparring/Stream seats.
5. Contributing — if you want to change zero-employee itself.

Common commands

Minimal workflow

For a solo developer:

zeo intake "describe the problem in plain English"
zeo intake mission intake/<created-file>.md
# investigate the real repo, then follow docs/tutorial.md to propose and promote
zeo triage

For an agent-assisted team:

zeo orient --json
git checkout -b master/demo-20260824
zeo session start --id master-demo-20260824 --master master-demo-1 --branch master/demo-20260824
zeo session status --id master-demo-20260824

To launch live Codex seats, use the guarded launcher so each session starts with the right relay address and GitHub identity instead of inheriting the wrong shell:

zeo seat launch master --instance master-zeroemployee-1 --exec codex
zeo seat launch sparring --instance sparring-zeroemployee-1 --exec codex

The first workflow is the one to learn first. The second is for teams already running multiple agent seats and branches.

Repository layout after zeo init

my-org/
├── claude-md/CLAUDE.md       # corpus marker and imported doctrine entrypoint
├── governance/GOVERNANCE.md  # tool-neutral governance starter
├── intake/                   # raw ideas live here first
├── projects/                 # SOWs grouped by project and stream
├── ruling/                   # durable decisions
└── .zeo/                     # local runtime state, ignored by git

Generated board files such as STATE.md and stream-index.md are local views. They are intentionally ignored by git.

Developing this package

git clone https://github.com/zeroemployeeorg/zero-employee.git
cd zero-employee
make setup
make verify

make verify runs formatting checks, linting, and the full test suite. PR CI keeps the required zeo check fast; deep changed SOW/ruling validation runs in the tracked pre-push hook installed by make setup. See CONTRIBUTING.md for the contributor workflow.

Documentation

• Getting started
• Mental model and glossary
• Tutorial
• Seat identities
• Codex swap guide
• Release process
• Non-goals
• Changelog

License

MIT. See LICENSE.