An agent harness where humans and AI agents work together like a remote-first team.
Agents work best when animated as specialists in a human team pattern. A Go specialist with Kernighan's principles writes better Go than an anonymous agent — not because of magic, but because personality constrains and focuses the model's output the same way a real colleague's expertise would. Models were trained on human collaboration; ethos gives that collaboration structure and persistence.
Ethos is an agent harness — the shared identity and workflow layer that other tools compose with:
- Identity — one schema for humans and agents. Personality, writing style, domain expertise, role, email, voice config. Loads automatically at session start and survives context compaction.
- Delegation — typed mission contracts with file-level write-sets, frozen evaluators, bounded rounds, and an append-only audit log. Pipeline templates chain missions into multi-stage workflows.
- Composable integrations — every tool in the stack gains richer context when ethos is present and works without it when it is not. This is the core design principle, not a feature.
| Tool | Without ethos | With ethos |
|---|---|---|
| Biff (messaging) | Team chat | + identity, presence, team graph |
| Vox (voice) | Text-to-speech | + voice persona per agent |
| Beadle (email) | Send/receive | + email identity binding |
| Quarry (search) | Semantic search | + per-agent mission memory |
Identity and team state is stored in local files (YAML + Markdown)
and resolved through three layers
(first match wins): repo-local .punt-labs/ethos/, active bundle,
global ~/.punt-labs/ethos/. Orgs with a shared team repo mount it
as a submodule at .punt-labs/ethos/; new users activate a starter
bundle to get a production-ready team in one command. See
Team Setup for the full configuration guide.
No server, no cloud, no telemetry.
Platforms: macOS, Linux (amd64, arm64).
curl -fsSL https://raw.githubusercontent.com/punt-labs/ethos/112dcd9/install.sh | sh
ethos setupThe installer places the ethos binary in ~/.local/bin, seeds
starter content (roles, talents, archetypes, pipelines, skills, bundles),
and registers
the Claude Code plugin when claude and git are available.
ethos setup is an interactive wizard that
asks 3 questions (name, handle, working style), then creates:
- Your human identity
- A paired agent identity (
claude) - Repo config (
.punt-labs/ethos.yaml) - An active team bundle with 4 agents
- Agent definition files (
.claude/agents/*.md)
Start Claude Code. The agent knows who it is, who you are, and how to delegate. Sub-agents each get their own persona and tool restrictions.
ethos setup activates the foundation bundle by default — a
4-agent general-purpose team (architect, implementer, reviewer,
security) that works on any codebase. For the opinionated 6-agent
startup builder team, use ethos setup --bundle gstack. Switch at
any time with ethos team activate <bundle>.
ethos setup # interactive wizard
ethos setup --solo # identity only, no team
ethos setup --bundle gstack # use gstack instead of foundation
ethos setup --file config.yaml # non-interactive, from fileManual install (Go required)
go install github.com/punt-labs/ethos/cmd/ethos@latest
mkdir -p ~/.punt-labs/ethos/identities
ethos doctorAt session start, ethos injects identity from the resolved YAML:
[ethos] Identity: claude (agent)
[ethos] Personality: principal-engineer
[ethos] Writing style: concise-quantified
[ethos] Talents: engineering, security
[ethos] Working context: branch feat/rewrite, 2 dirty files
When you delegate to a sub-agent, it loads a matched persona with tool restrictions from its role:
[ethos] Subagent bwk spawned: go-specialist
[ethos] Tools allowed: Read, Write, Edit, Bash, Grep, Glob
[ethos] Safety: Bash must not run destructive commands (rm -rf, git push --force)
For a real mission — issue ticket claim to merged PR in 12m55s, with
every command and output — see docs/example/. The
walkthrough uses beads as the
issue tracker, but ethos accepts any tracker ID (Linear, Jira, GitHub
issues, etc.) via the inputs.ticket contract field.
Each layer works alone. Add the next when you want more structure.
| Layer | What you get | Guide |
|---|---|---|
| Identity | Consistent agent persona across sessions. Hooks fire automatically. | This page |
| Team | Roles with tool restrictions, team graph with reports_to edges, auto-generated .claude/agents/ files with anti-responsibilities |
Team setup |
| Missions | Typed delegation contracts with write-sets, bounded rounds, frozen evaluators, audit logs. Closing a mission auto-appends a summary to .ethos/missions.jsonl for commit-ready traceability. |
Archetypes and pipelines |
Any tool reads ethos at the coupling level that fits:
| Pattern | How | Dependency |
|---|---|---|
| Filesystem | Read YAML at ~/.punt-labs/ethos/ |
None |
| CLI | ethos whoami --json, ethos identity show <handle> --json |
Binary |
| MCP | ethos serve exposes 11 tools |
Binary |
Three Punt Labs tools integrate today: Biff (team messaging), Vox
(voice), and Beadle (email). Each works without ethos and gains
identity context when present. Extensions let any tool attach per-tool
config under ~/.punt-labs/ethos/identities/<handle>.ext/<tool>.yaml
without schema changes.
Integration guides: filesystem, CLI, MCP.
Essentials below. Every command accepts --json. Full reference in
AGENTS.md.
| Command | What it does |
|---|---|
ethos setup |
Set up identities and team for the current repo |
ethos whoami |
Show your resolved identity |
ethos identity create |
Create a new identity (interactive) |
ethos doctor |
Check installation health |
ethos identity list / get <handle> |
Query identities |
ethos mission create --file <path> |
Create a mission contract |
ethos mission dispatch |
Create a mission from CLI flags (no YAML needed) |
ethos mission show <id> |
Show contract, results, reflections |
ethos mission pipeline list / show <name> |
Query pipeline templates |
ethos mission pipeline instantiate <name> --var key=value |
Create N missions from a pipeline |
ethos mission lint <contract.yaml> |
Advisory pre-delegation linter |
| Tool | What it does | Where ethos differs |
|---|---|---|
| SoulSpec | Structured agent personas in .md files |
Agent-only; no human identity, no teams, no delegation contracts, no CLI/MCP integration surface |
| Mastra | Typed Zod schemas and pre-delegation hooks | No persistent identity, no write-set boundaries, no frozen evaluator |
| CrewAI | Role-based agent orchestration | Prose delegation, no typed contracts, no persistent identity, no reflection gates |
| Claude Managed Agents | Hosted stateful agent sessions | Vendor-specific; "persona" means deployment config, not rich identity; no human developer identity |
Ethos ingests SoulSpec on the way in (ethos import --from soulspec),
exports to SoulSpec and CLAUDE.md on the way out (lossy — structural
enforcement drops because markdown cannot represent it). Coexistence
rather than competition.
v3.9.0 — all five planned phases shipped plus onboarding. 24 KLOC production Go, 38 KLOC tests, A+ Go Report Card. Identity, teams, mission contracts, write-set admission, frozen evaluators, bounded rounds, audit logs, archetypes, pipelines, automatic mission traceability, and mission dispatch one-liner are in daily use by Punt Labs.
New users run ethos setup to get a working team in under 60
seconds. Two embedded bundles ship: foundation (4-agent
general-purpose team) and gstack (6-agent startup builder
team). Existing users on the legacy punt-labs/team submodule can
move to the bundles layout with ethos team migrate.
Remaining work is adoption-driven: customer validation interviews, cross-tool integration. See the roadmap.
Live example · Onboarding design · Team setup · Archetypes and pipelines · Gstack starter team · Persona animation · Agent definitions · Architecture · Agent guide (CLI, MCP, hooks) · Design decisions · Changelog · Roadmap
make check # All quality gates (vet, staticcheck, markdownlint, shellcheck, tests)
make build # Build binary
make install # Install to ~/.local/bin
make help # List all targetsContributors: see CLAUDE.md for the development lifecycle.
MIT