🇺🇸 English ｜ 🇯🇵 日本語 ｜ 🇨🇳 简体中文 ｜ 🇹🇭 ไทย
CI evidence (2026-08-15 UTC): matrix 7/7 green ・ 60 independent runs of one SHA, 0 flakes. Weekly schedule — GitHub pauses schedules after 60 days of repo inactivity, so mind the run date.
Re-explaining everything. Context that vanishes. A cheerful "done!" with nothing to show for it.
Caty Agent Harness fixes those — with plain text files and real checks.
Not magic. The machinery remembers, drives, and checks, so the AI can focus on thinking —
a small system, wrapped around the AI you already use.
A tool that grows on its own — and learns to run your tasks all the way to done.
Measured — sealed, pre-registered benchmark on context-overflow workloads (2026-08):
| Model | Verified completion (bare → harness) | Completion hallucination¹ | Time & tokens |
|---|---|---|---|
| Claude Haiku 4.5 | 13% → 43% (+30 pt, p=0.0079) | 98% → 8% | 59% fewer tokens · 40–46% less time |
| GPT-5.6 Luna (Codex) | planned | — | — |
| Local models (Ollama) | planned | — | — |
¹ Claiming "done" without having read the work — measured from tool-call transcripts, not self-reports: 222 → 2 such claims on the 150K–300K-token jobs (30 runs per arm, machine-scored). Weak spots included: full numbers & limitations.
🔧 Engineering guide ｜ 📘 Reference
- Does this sound familiar?
- What you get
- What you need
- Get started
- Why it's safe to try
- Dig deeper
- Part of Family OS
- License
The more work you hand to an AI, the more often these moments show up.
- Every new session starts with you explaining the same background again.
- The AI says the job is complete — but the result is missing, or you can't tell.
- Long work loses its place halfway and quietly stalls.
- A fix that worked last week is forgotten by this week.
If you nodded at any of these, this was built for you. And if you only use AI for short one-off questions, this machinery is more than you need — you're fine as you are.
These four problems are exactly what Caty Agent Harness was built to crush, with machinery instead of promises.
It's one loop, repeated: remember → work → prove it → hand over. The machinery keeps that loop turning, so even when the AI forgets, the work is never forgotten.
flowchart LR
A["Remember"] --> B["Work"]
B --> C["Prove it"]
C --> D["Hand over"]
D -. next time .-> A
-
🌱 It gets smarter on its own
When it makes a mistake, the reason and the evidence are recorded on the spot in a notebook (really just a plain text file). The next attempt always inherits the previous failure, and retrying the same way is mechanically forbidden — the same mistake stops repeating. You never have to say "take a note."
-
🏁 It runs to the finish
Big jobs are split into small numbered steps, and the machinery drives them forward one at a time. Sessions can end, windows can close, models can change — the work continues from where it left off.
-
🔍 "Done" comes with proof
"Done" is judged by mechanical checks against the actual result — never by the AI's own claim. An independent verifier joins only when configured; without one, the mechanical check remains the core, and the maker's claim is still not treated as proof. When nothing is working, it doesn't spin forever: it stops honestly, with evidence, and reports to you.
How it works (the reason it isn't magic)
- When it fails — what went wrong, plus the evidence, is recorded automatically in a notebook inside your project.
- On the next attempt — the previous failure is always handed over, and a mechanical rule forbids retrying the same way.
- When it succeeds — the method is saved only as a lesson at first, and becomes a rule after passing verification again on a different job. Procedures that keep coming up are reviewed by a different AI than the one that wrote them; only the ones that pass are stored as skills.
- While it runs — a scheduler kicks the next step every few minutes, handing the AI only a short, fresh context. Attempts and active time have limits counted by the machinery, so endless grinding is impossible.
→ In depth: learning from repeated failures ／ the completion rail
Whether you can use it comes down to the tools you already have — here's the table.
The supported AI tools all run in a terminal — but you won't be the one typing. Your AI does the setup and the upkeep; you just talk to it.
| Category | Supported |
|---|---|
| OS | macOS: ✅ CI-tested (GitHub Actions macos-latest, Apple silicon) ／ Linux: ✅ CI-tested (GitHub Actions ubuntu-latest) |
| Windows | ❌ not supported (not tested; WSL not tested) |
| AI tools | Claude Code ✅ ／ Codex CLI ✅ ／ Kimi Code CLI ✅ ／ Hermes Agent ✅ ／ OpenClaw ✅ |
| Shell | bash 3.2+ ✅ (the macOS default is fine) |
| Python 3 | used by behind-the-scenes automation (technically, a mechanism called hooks) — your AI will check this for you |
Support depth differs by tool on purpose — the details live in the engineering guide.
If your setup is on the table, installing takes one prompt.
There is one thing to do on your side. Open the AI tool you already use inside the project folder where it works, and paste this — your AI handles the install, the checks, and the report back to you.
Please set up https://github.com/caty-ai/caty-agent-harness.git in this project:
read docs/agent-guide.md in that repository and follow it — install into this folder
as the workspace, run the health check, and then tell me in plain words what you set
up and what I can do next.
That's it. The agent guide walks your AI through every choice, the health check, and what to report back to you.
For a concrete first demo, your AI can run the bundled image pilot example, which builds an SVG image card and JSON delivery receipt using local tools only.
Prefer to type the commands yourself? → the engineering guide has the full manual path.
If something feels off
- Your AI will run a read-only health check (
--check) and show you the result — a healthy setup ends withok: required layout and STATE.md headers present. - Some check rows can say
FAILwhile the core is healthy: those are optional automation paths that aren't wired yet. The agent guide tells your AI which ones matter for your tool.
Still hesitant to paste it? The next section explains why nothing gets broken.
- Your AI stays exactly yours — its personality and accumulated memory stay as they are. Existing instruction-file content is left intact; if you choose
--append-bootstrap, setup adds only the documented bootstrap block to the selected instruction file. The rest is harness scaffold around it. - Quitting is one command too — installing is one command, pausing is one command, and nothing it learned is lost. Resume, and it continues where it stopped.
- You can read everything — lessons, progress, and evidence all live in plain text files, so you can see what's happening with your own eyes.
That's the short version. The depth is all below.
The page you just read is a map. The substance is real, and it's all documented.
| Document | What's inside |
|---|---|
| docs/agent-guide.md | The installer's playbook — a step-by-step guide your AI follows: choices, commands, checks, and how to report back |
| docs/benchmark.md | The sealed benchmark — full numbers behind the hero table, method, and the honest limitations |
| docs/engineering.md | The full technical guide — what's enforced where, per-tool depth, pause semantics, architecture, directory map |
| docs/reference.md | The exact contracts — every flag, every state, every pointer to the design documents |
| Runtime setup | Per-tool wiring — hooks, verifiers, and schedules for each of the five AI tools |
| CONTRIBUTING.md | How to propose changes — issue-first flow and every test suite under tests/ (one make test runs them all) |
| SECURITY.md | How to report issues safely — private vulnerability reporting |
- CI: — runs
make test+make linton every pull request - Verified environments: macOS (GitHub Actions
macos-latest, Apple silicon) and Linux (ubuntu-latest) — see the table in What you need - Maturity: public preview — the FROZEN CLI output contracts in docs/cli-conventions.md are stable; everything else may still move
- Known constraints: Windows is not supported; some updater suites need
ssh-keygen(see CONTRIBUTING Prerequisites)
One last thing — the bigger picture this tool belongs to.
Part of the Caty AI family — open tools for running a family of AI agents. The full map, including modules still being prepared for release, lives in Family OS.
| Axis | Module | What it does | State |
|---|---|---|---|
| Map | Family OS | The map of the whole family — every module, its state, and how they fit | published, MIT |
| Rules | Family Dev Handbook | The rules of the road — issues, PRs, worktrees, handoffs, parallel development | published, MIT |
| Vertical · foundation | Caty Agent Harness | Task backbone for AI agents — retries, checkpoints, and honest completion | published, MIT |
| Vertical | context-kit | Six-piece context hygiene kit for one agent — bounded output, delegation briefs, safety guards, recall, worktree snapshots | published, MIT |
| Vertical | Persona Engine | Gives an agent a persona — layered personality and graded emotion | published, MIT |
| Vertical | Persona Growth Loop | Grows the persona itself — minimal, idempotent proposals | published, MIT |
| Vertical | X Collector | Turns X and the web into one daily digest — for people and agents | published, MIT |
| Vertical | Self Growth Loop | Lets an agent grow its own abilities — proposals, governance, adoption records | published, MIT |
| Horizontal · foundation | Family Memory Architecture | The memory bus — how the family shares what it knows | published, MIT |
| Horizontal | Sitter | Babysits delegated agent runs — watches, keeps evidence, restarts | published, MIT |
Caty Agent Harness is one tool inside Family OS — the Caty AI project's larger blueprint for running multiple AI agents as one family. It works fully on its own, and it becomes even stronger combined with:
- family-os — the blueprint that ties the family together. Inside it, this Harness owns the vertical axis: growing an individual agent and driving its work to completion.
- sitter — a watchdog that keeps an eye on long-running agent work from the outside, and raises its hand when the work stalls or freezes.
MIT — chosen so anyone can use it, study it, and build it into anything, including commercial agent setups. That's the point.
plain text files ｜ works with 5 AI tools ｜ paused in one command