What Okami Agent is
Okami is a public alpha of an open-source coding agent. The thesis is clear: the intelligence lives in the harness, not the model. The model is a narrow, swappable…
The mental model
Most agents dump everything on the model — planning, memory, perfect tool-calls — and pray the model is strong enough. Okami flips that: the harness decomposes the task, constrains the output, verifies every effect and compensates for what's missing. The weaker the model, the harder the harness works — which is why a small local model gets close to a frontier model on well-gated tasks.
Start by goal
| I want to | read first | next step |
|---|---|---|
| test it in the terminal | Installation + Quickstart | okami chat and okami task in a disposable workspace |
| automate with evidence | Executable recipes | exitCriteria, events and replay |
| run a bot/API | Channels & gateway | Self-hosting + Runbooks |
| configure a provider | Config examples | Providers & auth + doctor |
| evaluate technically | Technical comparison | Architecture + generated version |
| contribute to the alpha | Roadmap & changelog | open an issue, PR or provider report |
| extend capabilities | Skills overview | Tools overview + MCP |
What “compensate for what's missing” means in practice
A weak model tends to (a) declare completion without doing the work, (b) repeat the same action in a loop, and (c) emit a tool-call with broken JSON. The harness neutralizes all three by construction: completion only counts with mechanically-verified exitCriteria; a fingerprint/cycle detector cuts the repetition; and constrained decoding (GBNF/json_constrained) makes invalid JSON impossible. The model only has to propose the next step — the quality floor comes from the verifier.
That's why the same task runs on a small local model or a frontier model without rewriting anything: the provider's tier and capability profile tell the harness how much to decompose, which tool-call mode to use and when to escalate — the rest of the scaffold is identical.
The two pains it was born from
Every capability in the project is born from one of these concrete failures, observed in other agents:
- Unreliable harness: the agent says “I'll do that” and doesn't act; pressed, it says “hang on, doing it” and never finishes. No action invariant, no real completion detection.
- Doesn't adhere to skills / design system: you ask for ShadCN/HeroUI and it invents ugly CSS. The skill becomes a hint, not a gate. No mechanical verification.
run, task or chat?
Three entry points, from rawest to most complete. Pick by what you need:
| command | what it is | when to use |
|---|---|---|
| okami run | a raw round-trip to the provider | test a prompt, simple pipe/script |
| okami task | full harness until exitCriteria | verifiable automation (CI, cron, scripts) |
| okami chat | interactive TUI, persistent session | work alongside it, iterate, converse |
| okami gateway | channel bots (Telegram, Paperclip…) | let the agent work remotely |
Anatomy of the agent
The okami/ package is organized by domain — each piece is pluggable and follows the same invariants:
core/ harness · tools · approval ❤️ the engine (state machine)
llm/ providers · transports · oauth model access + routing
agents/ load_agents · Router · group multi-agent + group
gateway/ run_gateway · sessions control plane / chat
channels/ telegram · paperclip · slack… channel adapters
learning/ reflect · taste · persona self-improvement
memory/ sqlite_fts5 · holographic · honcho
skills/ load_skills · skill_security skills + scanHow to read these docs
The documentation is organized by intent. If you want to do something, head to Guides; if you want to understand how it works, Concepts; if you want the exact detail of a command or key, Reference.