ethos
A responsible agent harness — control, auditability, and
performance for AI agent delegation.
The problem
Agents write code you're responsible for, and you can't see what
they did or why.
A developer delegates a task to an AI agent. The agent reads files,
edits code, runs tests, commits. Six months later someone asks: who
authorized this change? What were the instructions? Did the agent
stay within the files it was supposed to touch? Why this approach?
Today the answer is: check the chat history, if you still have it.
There is no durable record connecting a line of code to the contract
that authorized it, the prompt that drove it, and the tool calls
that produced it.
What ethos does
Ethos makes agent delegation responsible rather than reckless. Three
axes:
Control. Typed mission contracts with file-level write-sets
enforced at runtime, frozen evaluators (hash-pinned so nobody swaps
the reviewer mid-mission), bounded review rounds, preconditions
that gate tool calls on prior reads, and delegation depth limits.
The agent can only do what the contract authorizes.
Auditability. Every delegation produces artifacts on disk —
contract, delegation record, the exact dispatch prompt, a
per-tool-call audit trail tagged with the delegation ID, and
Mission:/Delegation: git trailers on commits. git blame any
line → commit → trailer → contract → prompt → audit trail. Months
later, you can reconstruct exactly what happened and why.
Performance. Named specialist agents with encapsulated domain
expertise — not generic assistants, but a Go specialist grounded in
Kernighan's principles, a security reviewer with Bernstein's
methodology. Personalities, writing styles, and talents shape the
model's output the way a real colleague's expertise would. Roles
restrict tool access. Teams define delegation topology. The
configuration is reusable, measurable, and improvable.
Quick start
curl -fsSL https://raw.githubusercontent.com/punt-labs/ethos/b379a79/install.sh | sh
ethos setup
The installer places the ethos binary in ~/.local/bin and,
when claude and git are available, registers the Claude Code
plugin. ethos setup asks 3 questions
(name, handle, working style), then creates your identity, a paired
agent, repo config, a 4-agent team, and agent definition files.
Start Claude Code — the agent knows who it is, who you are, and how
to delegate. See Onboarding for the full walkthrough.
Platforms: macOS, Linux (amd64, arm64).
What it looks like
Traceability: line of code → full history
When commits carry Mission:/Delegation: git trailers (appended
automatically by the commit-msg hook), the blame chain works like
this:
$ git blame -L 42,42 internal/hook/generate_agents.go
abc1234 (bwk 2026-05-25 42) func projectFilePatterns(repoRoot string) string {
$ git log --format='%(trailers)' abc1234
Mission: m-2026-05-25-002
Delegation: d-2026-05-25-011
$ cat .punt-labs/ethos/missions/m-2026-05-25-002/delegations/d-2026-05-25-011/prompt.md
"Fix the hardcoded Go file-extension patterns. Detect project type
at generation time (go.mod → Go, pyproject.toml → Python)..."
$ ethos audit show --delegation d-2026-05-25-011 --format text
2026-05-25T12:49:23Z Read <repo>/internal/hook/generate_agents.go
2026-05-25T12:49:55Z Edit <repo>/internal/hook/generate_agents.go
2026-05-25T12:51:06Z Bash go test -run TestGenerateAgentFiles ...
2026-05-25T12:53:25Z Bash make check
2026-05-25T12:53:37Z Bash git commit ...
Illustrative — actual SHAs and IDs vary per repo.
Or visually: ethos ui opens a localhost dashboard where you browse
the repo, click a line, and see the agent who wrote it, the prompt
they received, and every tool call they made.
Contract-bound delegation
leader: claude
worker: bwk
evaluator:
handle: djb
write_set:
- internal/hook/generate_agents.go
- internal/hook/generate_agents_test.go
success_criteria:
- detect project type at generation time
- tests cover Go, Python, and generic fallback
budget:
rounds: 2
reflection_after_each: true
When a verifier agent is spawned, the PreToolUse hook enforces the
write-set — an Edit to a file outside the contract is blocked before
it executes.
Specialist agents
