Kyotee v1.0.0 Walkthrough

A multi-model AI harness running locally with terminal UI.

1. The Headless Engine

Kyotee runs as a persistent background engine handling API keys, state checkpoints, and SSE streaming. We spin this up first:

$ ./kyotee serve
[INFO] Engine listening on 127.0.0.1:8484
[INFO] Loaded 5 providers from ~/.kyotee/config.yaml

2. Running the TUI

The magic happens when you attach the TUI client to the running engine. Because the orchestration is entirely decoupled, you can close the TUI, reboot your machine, and re-attach later to see the exact state.

$ ./kyotee tui --url http://127.0.0.1:8484

Kyotee TUI[ twobrain | slow mode | budget $1.50 ]Cost: $0.034Prompt: What is the best way to handle state in a distributed Cloudflare Workers application: Durable Objects, D1, or KV? Give a definitive answer.

[ Divergent Thinker (gemini-2.5-pro, temp 1.0) ]
Round 1: Durable Objects are the *only* true choice for strong consistency. D1 is SQLite and KV is eventually consistent. If you need coordination, it's DO or bust.
  

[ Convergent Synthesizer (gemini-2.5-pro, temp 0.3) ]
Round 1: While DO provides strong consistency, D1 now supports read-heavy global scaling, and KV is faster for pure reads. A definitive answer must segment by use case...
  
[Events]
· classified  chat/technical tools:likely
· routed      twobrain (auto)
· thinking    slow — forced by complexity
· stage       twobrain…
    

3. Direct CLI (Spec 09 Adapter)

You can also use Kyotee directly from the terminal without the TUI using the Spec 09 adapter, which streams the answer back seamlessly:

$ ./kyotee ask --wait --strategy twobrain "What is the best way to handle state..."
· classified  chat/standard tools:likely
· routed      twobrain (auto) budget $1.5
· stage       thinking…
· stage done  thinking (spent $0.0013)
· stage       twobrain…

[Final Synthesis Output Streams Here]

4. Council Debate & JSON Output

Kyotee can assemble a vendor-diverse council to debate hard problems. By adding --json, it outputs a stable contract perfect for piping into other tools or skills.

$ ./kyotee ask --wait --json --strategy council "Monolith or microservices for a 4-person team?"
{
  "task_id": "tsk_01H...",
  "answer": "A monolith is strongly recommended for a 4-person team to minimize operational overhead...",
  "strategy": "council",
  "consensus": { "reached": true, "method": "vote", "rounds_used": 2 },
  "dissent": ["gemini-2.5-pro dissented, arguing for macro-services if domains are disjoint"],
  "total_cost_usd": 0.042,
  "total_tokens": 12400
}

5. Checkpointing & Resuming

Every step, thought, and API call is event-sourced. If you hit your budget ceiling or kill the process, you can resume exactly where it left off.

$ ./kyotee resume tsk_01H... --wait
· resuming from stage: twobrain_round_2
· stage       twobrain…

6. Providers & Config Hot-Reload

Check which models are active and how much they cost, or validate your routing rules before hot-reloading them into the running engine.

$ ./kyotee providers
[ anthropic ] claude-opus-4-8 (reasoning: true) - $5.00 / $25.00
[ google    ] gemini-2.5-pro  (reasoning: true) - $2.00 / $8.00

$ ./kyotee config validate ~/.kyotee/config.yaml
✅ Config valid. 6 routes, 5 providers.