Hipson

Lead quick reference

• After context loss: hipson lead resume
• What needs attention now: hipson task now
• Start with acceptance checks: hipson task open --project . --title T --objective O --check 'pytest -q' --start
• Run workers: hipson task run --task T-0001 --actor codex --role builder --mode rw --scope src -- COMMAND [ARGS...]
• Acknowledge deliveries: hipson task ack --assignment A-0001
• Verify and close (runs the checks): hipson task close --task T-0001
• One shot (open, run one worker, verify, close): hipson task do --title T --check 'pytest -q' --actor codex --scope src -- COMMAND [ARGS...]
• Ad-hoc verification: hipson task verify --task T-0001 -- COMMAND [ARGS...]

A control plane for the coordination layer, not another agent. A lead (for example Claude Code) opens tasks and hands bounded pieces to workers: Codex, Antigravity, subagents. Every task, assignment, path claim and result lands in one transactional SQLite ledger on your machine, next to a hash-chained evidence log linked by task id. No silent overlap: a second writer on the same paths is refused before it starts (exit 75). No zombie locks: a dead run's claims are reaped automatically. Evidence, not confidence: worker results are process results; only the lead says done. Local-first: no cloud service, zero runtime dependencies, Apache-2.0. The film on the left was produced by an agent pipeline (Claude directing and animating, Codex reviewing frames and running QA) from facts in this repository only. Silent excerpt, 28 s.

_{Rendered from the real hipson task events --json record of building Hipson's own evidence hardening (task T-0003; long summaries shortened): builder → independent reviewer → builder with fixes → lead verification → done.}

Why it exists

Agents drift when each one keeps its own notes, its own plan and its own idea of "done". Two writers edit the same files. A crashed run keeps a lock forever. A worker's "all tests pass" gets taken as proof.

Hipson fixes the coordination layer, not the agents:

• One source of truth per task. Status, assignments, path claims and an append-only event log in one SQLite store.
• No silent overlap. A writer must claim its paths; an overlapping live claim is refused before the worker starts.
• No zombie locks. Runs launched through the wrapper record their owner (process group, boot id, host); when that owner is gone, its claims are reaped. Assignments recorded by hand can carry a lease instead.
• Evidence, not confidence. Worker results are recorded as process results; only the lead moves a task to done.
• Workers stay workers. Agents launched by a lead switch to worker mode: no own orchestration, no own notes, no commits.

Built with itself

The task ledger in this repository was built by Claude Code as lead with Codex as builder and reviewer and Antigravity as a second reviewer; once the ledger existed, the rest of the work ran through it. Numbers from branch feat/task-ledger, 2026-10-25:

Failure cases that are covered by tests, not just described: two processes racing for the same claim, a worker whose runner is SIGKILLed while the worker survives (claims stay), a dead process group (claims released), a worker that ignores SIGTERM and its leftover child processes, readers racing writers, twelve concurrent evidence writers keeping one hash chain, and secrets nested inside evidence payloads.

How it works

flowchart LR
  L([Lead<br/><sub>Claude Code</sub>]) -->|task open| T[(Task ledger<br/><sub>SQLite</sub>)]
  L -->|brief + task id| R[hipson task run<br/><sub>worker runner</sub>]
  R -->|assign + owner + claims| T
  R --> W[Worker<br/><sub>Codex · agy · subagent</sub>]
  W -->|report, diff| L
  R -->|finish: exit code, model, report path| T
  L -->|verify, then review → done| T
  T -.->|dead owner| X[reap<br/><sub>release claims</sub>]

Quick start

Requires Git and Python 3.11+; uv can install Python for you. Install for your OS, then run hipson init from your project.

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install --python 3.12 git+https://github.com/Hipson47/Hipson
uv tool update-shell
cd /path/to/your/project
hipson init

macOS

Install Git first (xcode-select --install if missing). In Terminal:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install --python 3.12 git+https://github.com/Hipson47/Hipson
uv tool update-shell
cd /path/to/your/project
hipson init

The native runner uses Python for process containment; no Bash or GNU utilities are required.

Windows native (PowerShell)

Install Git for Windows, then install uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Reopen PowerShell, then:

uv tool install --python 3.12 git+https://github.com/Hipson47/Hipson
uv tool update-shell
$env:Path = "$(uv tool dir --bin);$env:Path"
Set-Location C:\path\to\your\project
hipson init

Run workers directly with hipson task run (example below). It records the assignment and process outcome, forwards console interrupts and contains descendants in a Windows Job Object. The Bash example and Linux agent e2e harness still require WSL2.

Windows WSL2

In an administrator PowerShell, install Ubuntu with wsl --install -d Ubuntu and restart if prompted. Open Ubuntu and follow the Linux commands above. Keep projects in ~/code, with the lead client, Hipson and workers in that same WSL distro.

hipson init checks prerequisites, creates or migrates the ledger, registers MCP with Claude Code and/or Codex found on PATH, and verifies MCP with an initialize/tools-list handshake. It shows the plan and asks before making changes. Use --dry-run to preview, --yes for unattended setup, --client claude|codex to select a client (with Claude Code as the lead, --client claude), or --client none for the ledger only. Claude defaults to project scope (.mcp.json); --scope user selects its user config. Codex uses $CODEX_HOME/config.toml (default ~/.codex/config.toml). Existing registrations are left alone; config edits get unique backups first. Restart the lead client after setup, then open your first task below.

Run from a clone instead

On any OS, after installing uv and Git, clone once and run Hipson from your project directory:

git clone https://github.com/Hipson47/Hipson.git ~/tools/Hipson
uv sync --project ~/tools/Hipson --python 3.12 --no-dev
cd /path/to/your/project
uv run --project ~/tools/Hipson --no-dev hipson init

Use uv run --project ~/tools/Hipson --no-dev hipson (an absolute path to the clone) in place of hipson below. For virtualenv activation, MCP registration from a clone, PATH troubleshooting and verification commands, see docs/INSTALL.md.

Run a coordination smoke test (the same command syntax works in PowerShell). It needs a Git repository with at least one commit; the worker only prints a line, so the check is a whitespace check. Use the task id printed by task open in place of T-0001 when your ledger already has tasks.

hipson task open --project . --title "Smoke test" --objective "Ledger records a worker and a lead check" --check "git diff --check" --start
hipson task run --task T-0001 --actor codex --role builder --mode rw --scope src/parser -- python -c "print('worker check')"
hipson task now
hipson task ack --assignment A-0001 --note "Read worker outcome and independently checked the change"
hipson task close --task T-0001
hipson task events --task T-0001

--check declares an acceptance check: a command (split like a shell would, but never run through one) that the lead runs on the current tree. review and done need every declared check to pass after the latest worker result, on the same HEAD and working-tree content; any other passing command does not count. Replace git diff --check with the command that actually proves your acceptance criteria, for example --check "pytest -q", and repeat --check for more. task close runs the checks that are not yet fresh, then moves the task to review and done; if anything blocks (a failing check, an unread result, an open major finding) it changes nothing and prints the command that clears each blocker. hipson task checks changes the checks later (replacing them needs --reason, and workers cannot), hipson task verify --task T without a command runs them all, and --force --reason on task status stays the audited override.

For one bounded job, task do does it all in one command: open with checks, run the worker, acknowledge its result, run the checks and close. If the worker fails or reports partial work, the task stays in_progress for you to inspect.

hipson task do --title "Fix parser" --check "pytest -q" --actor codex --scope src/parser -- codex exec -s workspace-write "Fix the parser"

Use hipson task now --project . for pending results, activity ages, blockers, review decisions and cleanup. After context loss, hipson lead resume --project . restores objectives, acceptance, decisions, failed attempts, findings, verification freshness and Git state in bounded text. Both use sidecar-free ledger snapshots and refuse stores with a nonempty WAL or rollback journal until the writable owner checkpoints/closes the store. Git dirty state uses index/stat observations; tracked content and submodule contents are not inspected. Add --json for the full view. Use the assignment id printed by your runner in place of A-0001 when acknowledging its result.

Wrap real workers so the ledger fills itself. The brief tells the worker its objective, scope, the checks the lead will run and the result it must return; review it before launching:

set -e
TASK=$(hipson task open --project . --title "Add rate limit" --objective "API returns 429 over quota" \
  --check "python -m pytest -q" --start --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')
hipson task brief --task "$TASK" --role builder --scope src/api > brief.md
hipson task run --task "$TASK" --actor codex --role builder --mode rw --scope src/api --rollout codex \
  -- codex exec -s workspace-write < brief.md
hipson task now

The runner exits with the worker's code, 75 for an assignment refusal, 76 for a project mismatch, or 64 for invalid arguments. Use --result-file PATH to ingest a structured worker report. The process outcome is recorded even if the report is rejected.

The ledger lives at $HIPSON_LEDGER or ~/.config/hipson/ledger.sqlite ($env:USERPROFILE\.config\hipson\ledger.sqlite on native Windows). HIPSON_HOME and XDG_CONFIG_HOME can change its config directory. Details, recovery rules and limits: docs/TASK_LEDGER.md.

Use it from a lead agent (MCP)

Hipson ships a stdio MCP server; its initialize response carries the lead lifecycle as instructions. Start and recover: lead.resume, task.now. Read tools: task.show, task.brief, task.context, task.events, task.activity, task.list, task.board, task.findings. Write tools (each requires approved=true): task.open, task.status, task.checks, task.verify, task.close, task.ack, task.assign, task.finish, task.event, task.reap, task.finding_add, task.finding_update. Workers are launched by hipson task run, not through MCP.

hipson init --client claude
# Or: hipson init --client codex

The server only uses the configured ledger, never a caller-supplied database path, and read tools never create or migrate the store.

More than the ledger

The ledger sits on top of Hipson's existing local workflow layer:

Full command reference and workflows: docs/USAGE.md. All docs: docs/README.md.

Safety in short

• Provider-free by default. Core commands make no network calls; provider sidecars are explicit and advisory.
• Repository content is data, not instructions. Packets are bounded; sensitive files are skipped or summarized.
• Redaction before persistence. Evidence, work plans and release claims are redacted recursively, including any value under a credential-named key. Ledger text and MCP error messages get pattern-based redaction.
• Write gates. Every MCP write needs approved=true; invalid arguments are rejected before a database is opened.
• Honest limits. Actor names are recorded labels, not authenticated identities. Path claims coordinate cooperating agents; they are not filesystem permissions. Worker mode is an instruction, not a sandbox.

Hipson is a beta coordination tool for cooperating agents, not a security boundary or an enforced release gate. A task reaching done checks ledger closure, not the truth of its evidence or release readiness.

Keep real provider keys in ~/.config/hipson/agents.env or your shell, never in git.

Development

uv sync --all-extras
uv run ruff check .
uv run mypy src/hipson
uv run bandit -q -r src -c pyproject.toml
uv run python scripts/run_tests.py
uv run python -m pytest -q
uv build

CI runs Linux on Python 3.11/3.12 and macOS/Windows on Python 3.12, including installed CLI ledger commands and MCP initialize/tools-list over stdio. Mutation testing and pip-audit run on Linux. On Linux with CI set, both test runners fail on any skip, including pytest collection skips. The standalone runner reports passed, skipped and failed counts separately. Outside CI, missing prerequisites produce explicit skips, including the pytest-policy probe when pytest is unavailable. Wrapper tests resolve the installed CLI through HIPSON_BIN, then PATH, then the checkout's .venv/bin/hipson (.venv\Scripts\hipson.exe on Windows); missing prerequisites fail Linux CI. The agent e2e harness stays Linux/WSL2-only; other platforms report explicit skips. Artifact tests validate every keyword currently used in schemas/, including nested array items, additional properties, references, nullable types, patterns and bounds. Unsupported schema keywords fail even in unused branches.

Python 3.12 CI also enforces a bounded mutation baseline within a 20-minute step:

uv run mutmut run --max-children 2
uv run mutmut export-cicd-stats
uv run python scripts/mutation_gate.py

The mutated paths are approvals.py, evidence.py, redaction.py and sandbox.py; the test selection, including tests/test_evidence.py, is in pyproject.toml.

A second gate covers the review/done gates of the ledger core (ledger.py, task_verification.py) with the fast, in-process contracts in tests/test_gate_contracts.py:

uv run python scripts/mutation_profile.py ledger-core   # swaps [tool.mutmut]; restore with git checkout
uv run mutmut run --max-children 2
uv run mutmut export-cicd-stats
git checkout -- pyproject.toml
uv run python scripts/mutation_gate.py --section mutation-gate-ledger-core

It mutates only lines those contracts execute (mutate_only_covered_lines); the CLI, runner and Git paths of the same modules are exercised by subprocess tests that mutmut cannot attribute. The score is **