// guides · cookbook

Executable recipes

Copy-pasteable recipes that leave verifiable evidence: goal, command, success criterion and where to inspect failures.

Run a task with exit criteria

okami task "create hello.txt with hi" \
  -e file_exists:hello.txt \
  -e "file_contains:hello.txt:hi"
okami events -n 20

success	evidence
exit code 0	`COMPLETE` in events.jsonl
file created	`hello.txt` exists and contains `hi`
audit	`write_file` in `.okami/audit.jsonl`

Apply the UI gate

okami task "create a login screen with shadcn" -e ui_gate
okami gate -c ui ./src

Boot the local HTTP API

okami config set OKAMI_API_TOKEN <strong-token>
okami serve --host 127.0.0.1 --port 8765
curl -s http://127.0.0.1:8765/health
curl -s http://127.0.0.1:8765/chat \
  -H 'Authorization: Bearer <strong-token>' \
  -H 'content-type: application/json' \
  -d '{"agent":"okami","message":"say hi"}'

Supervise a process outside the agent

okami task "start the development server and tell me the port" \
  -e "shell_ok:curl -fsS http://127.0.0.1:3000"
okami ps -w workspaces/default
okami process log <id> -n 80
okami process signal <id> INT
okami process clean --ttl-hours 24 --dry-run

Create a Telegram agent

okami agent new support --name "Support" --telegram-token $TELEGRAM_TOKEN
okami route telegram:<chat-id>
okami gateway --foreground

Configure MCP

okami mcp
okami tools
okami task "list the repositories available from the configured MCP"

Run a Paperclip heartbeat

export PAPERCLIP_API_URL=https://paperclip.example.com
export PAPERCLIP_API_KEY=<token>
export PAPERCLIP_RUN_ID=<run-id>
okami paperclip
okami heartbeat --mode defer

Multi-agent room

okami room "plan an auth migration for production" -g 0
okami chat
/agents

Open this page in the interactive docs