ethos-dev

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/084c933/install.sh | sh
ethos setup

To install the CLI without the Claude Code plugin — for a non-Claude harness, or a Claude install where org policy blocks plugins — pass --no-plugin (or set ETHOS_NO_PLUGIN=1 where arguments cannot pass through the pipe):

curl -fsSL https://raw.githubusercontent.com/punt-labs/ethos/084c933/install.sh | sh -s -- --no-plugin
curl -fsSL https://raw.githubusercontent.com/punt-labs/ethos/084c933/install.sh | ETHOS_NO_PLUGIN=1 sh

--no-plugin skips only the marketplace-register and plugin-install steps; the binary, PATH setup, directories, seed content, per-repo ethos enable, and health check all still run. Re-run the installer without the flag to add the plugin later.

The installer places the ethos binary in ~/.local/bin and, when claude and git are available, registers the Claude Code plugin. ethos setup asks for your name, handle, email, GitHub handle (optional), and working style, then creates your identity as CEO, a paired COO agent (claude), repo config, and a specialist team (architect, implementer, reviewer, security) that reports to the COO, plus agent definition files. Out of the box the org is you (CEO) → claude (COO) → specialists — see DESIGN.md DES-064. The email prompt defaults to your git config user.email; your identity carries that email so ethos can resolve you by it. Start Claude Code — the agent knows who it is, who you are, and how to delegate. See Onboarding for the full walkthrough.

Non-interactive setup reads the same fields from a YAML file:

name: Mal Reynolds
handle: mal
email: [email protected]   # optional; defaults to git config user.email
github: mal                # optional
writing_style: concise-quantified

Run ethos setup --file config.yaml. When email is omitted, setup uses git config user.email; if that is also unset, setup fails with a remedy rather than creating an identity nothing can resolve.

ethos setup requires starter content to be seeded first. The installer runs ethos seed for you, so the quick start above just works. If you build from source or run setup on a machine that was never seeded, run ethos seed first — setup otherwise fails with an error naming the missing attribute and telling you to seed.

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: