ai-hats

Role-based multi-harness framework with behavior feedback.

Configure any agent CLI for a job once, run as many agents as the work needs, and let every session leave evidence behind.
_{Do. Reflect. Repeat.}

_{Reading in another language? Chrome / Edge / Safari Reader Mode translate this site cleanly — no separate translations are maintained.}

Why ai-hats?

Have you ever watched the same AI agent step on the same rakes across projects? Forgetting your conventions, skipping the planning step, falling back to the same anti-pattern. Copy-pasting CLAUDE.md doesn't scale: edits drift across projects, and a fix in one rarely makes it back to the others. And when a lesson is learned, nothing decides whether it was worth keeping — memory files grow until nobody reads them.

ai-hats answers this in four parts.

• Role-based. A role is one uniform way to configure a harness for a job — an SRE, a technical writer, a Go developer. It sets more than the opening context: the runtime comes with it. Hooks that fire on the agent's tool calls, consent gates that turn a destructive command into a question, the skills it may reach for. Terms and the composition model — glossary, architecture.
• Multi-harness. ai-hats levels the role systems of different agent CLIs into a single set. You stop asking how a job is expressed in harness X: describe it once, and it is delivered in each harness's own dialect. See harnesses below.
• Framework, multi-scale out of the box. Want five Claude developers, two SREs and a technical writer running at once? No problem — the agents don't collide, they compound. Each works in an isolated git worktree, they share context through the rack backlog instead of over each other's heads, and the feedback below improves the roles all of them run on. Worktree workflow — how-to-advanced §2; backlog — how-to-hatrack.
• Behavior feedback. A session is not a black box: it is scored, measured, and can be behavior-tested. An edit to a role is settled by an A/B experiment rather than by argument, and what the agent learns reaches the next prompt only after it is proven — not when it is guessed. The loop — how-to-feedback-loop; experiments — how-to-experiments.

_{The loop closes on the runtime: what one session proves, the next session starts from.}

Quick start

Prerequisite: uv is the single host requirement — the env engine that also provisions Python. The one-command install auto-installs it if absent.

cd ~/dev/my-project     # run this from the project you want to wire

# installs the launcher into ~/.local/bin/ and creates the managed venv
curl -LsSf https://github.com/muratovv/ai-hats/raw/master/scripts/bootstrap.sh | bash

ai-hats self init       # wizard: detects your stack, picks a role and a harness
ai-hats                 # start a session with the composed role

The wizard is its own step on purpose: a piped installer owns stdin, so it cannot ask you anything. Run it from your terminal and it detects the stack, recommends a role, and sets the feedback policy. If bootstrap warns that ~/.local/bin is not on your $PATH, add it and reopen the shell — otherwise ai-hats won't resolve.

Scripted or CI instead of a wizard? Pass the answers and skip it: ai-hats self init -p claude -r go-dev --no-wizard. Bootstrap takes -r/-p too, and then runs init for you.

No uv yet and just want a look? uvx ai-hats self init wires a single project from the published release without installing anything permanent. Other install paths, overlay recipes, and out-of-band repair — how-to; the full setup walkthrough — how-to-configure.

Harnesses

Harnesses are discovered through the ai_hats.providers entry point — an open registry, so a package outside this repo can add one. These ship in-tree:

gemini is an accepted alias for agy. Support is not uniform — what a hook gate may do, whether the audit is parsed from a real session log, how sub-agents run, whether consent wrappers work. The per-capability matrix is surfaces; read it before committing to a harness.

Ask your own host what it has: ai-hats list providers.

Roles

A role is picked at init and switched any time with ai-hats config set -r <role>. The ones you are most likely to start from:

ai-hats list roles prints the full set, including the ones the engine runs for itself — the session reviewer and the judges behind the feedback loop.

Read maintainer before writing your own. It is not a role to pick for your project — it maintains this repo, and ships in the ai-hats-dev library layer rather than usage/ for that reason. It is the reference: ten traits, each with an author-facing note on why it is there, plus a full injection. That is what a finished role looks like. Composing your own, or overriding a shipped one — how-to-extend.

CLI

ai-hats self init                  # wire a project — interactive wizard
ai-hats self update                # update the tool, self-healing
ai-hats                            # session with current settings
ai-hats -p claude -r sre           # override harness and role for one run

Everything else is discoverable from the tool itself: ai-hats --tree prints the whole command tree, ai-hats --tree wt one subtree of it. The backlog is a separate CLI — rack.

Customization

The shipped library splits into core/ (engine fundament) and usage/ (curated content). You change behavior by composing or replacing roles rather than editing core code — add your own role, override a built-in like session-reviewer, point ai-hats at an external library repo, or ship a role as a one-liner shell alias. Recipes and the override-precedence chain — how-to-extend.

Documentation

Every document in the repo is cataloged in docs/INDEX.md.

Project status

Beta. Until v1.0.0 the version reads 0.MAJOR.MINOR: a breaking change lands on a MAJOR bump and ships with a migration guide; MINOR is additive or fix-only. See Releases and CHANGELOG.md.

Contributing

See CONTRIBUTING.md — development setup, library layout, diagram house style. Security policy: SECURITY.md. License: MIT.