// guides · 01

Recipes (cookbook)

Real tasks, end to end. Each recipe is copy-pasteable and uses only what the code delivers — no magic steps. Start with the one that looks like your problem.

Open in full documentation GitHub

Run a verifiable task in CI

okami task only declares success when the exitCriteria actually pass — and exits non-zero if the final state isn't COMPLETE. That's what makes it safe in a pipeline.

okami task "create a /health endpoint in FastAPI" \
  -e file_exists:app/health.py \
  -e "file_contains:app/health.py:/health" \
  -e "shell_ok:pytest -q"
echo $?     # 0 = COMPLETE · 2 = BLOCKED/NEEDS_INPUT/FAILED

Build UI that obeys the design system

Declare the contract once in okami.yaml; then run the gate as exitCriteria. Code that violates the contract (inline hex, raw <style>, an import outside the lib) fails and goes back to the model.

okami task "login screen with shadcn" -e ui_gate
okami gate -c ui ./src        # or run the gate alone on a directory

Run 100% local / offline

An lmstudio provider (or any local OpenAI-compat) + holographic memory (or sqlite-fts5) runs with no network. The remote embedder is optional and degrades to BM25 if it's offline.

okami setup --memory holographic   # local backend, no embedding server
okami provider default lmstudio
okami chat                          # converse without touching the network

Put an agent on Telegram

Create the bot
Talk to @BotFather on Telegram and copy the token.
Attach the token to the agent
The token lives on the agent, not in the global YAML.
```
okami setup channel    # paste the token (goes into agent.yaml)
```
Allow your chat
Deny-by-default: with no allowlist the bot answers no one. Get your id with /whoami in chat and allow it.
```
okami config set channels.telegram.allow_chats '[<your_id>]'
```
Boot the gateway
Runs in the background and gives the terminal back; 1 bot per agent.
```
okami gateway              # --status / --stop to control
```

Multi-agent brainstorm

cd examples/company          # cto / ui / backend, each on its own model
okami agent list
okami room "CTO, what about the frontend?"   # the moderator picks who speaks (or no one)

Schedule a recurring task

Okami's cron is persisted; a system cron (or systemd timer) calls okami cron tick to run what's due.

okami cron add "0 9 * * 1" "summarize this week's commits"  # every Monday 9am
okami cron list
# system crontab:
*/5 * * * * cd /path/to/project && okami cron tick

Use it as an HTTP API (headless)

okami config set OKAMI_API_TOKEN <a-secret-token>
okami serve                                  # binds 127.0.0.1:8765 (fail-closed)
curl -s localhost:8765/chat \
  -H 'Authorization: Bearer <a-secret-token>' \
  -H 'content-type: application/json' \
  -d '{"agent":"okami","message":"say hi"}'

Install a skill safely

okami learn owner/repo       # download to quarantine, scan, promote only if it passes
okami scan ./skills/x        # re-validate on demand
okami skills                 # list the active ones

Roll back a bad change

Every file write enters a checkpoint journal. Reverting the last N is one command.

okami rollback 3      # undoes the 3 most recent writes

CLI · basicsrun, task, chat and the -e criteria.Self-hostingTaking this to production safely.

Open this page in the interactive docs