Theoros¶

An observed live REPL session. By default make theoros runs in autopilot mode: a separate claude CLI session in a middle pane drives make cli (top pane) through a curated prompt library, while you attach with tmux attach -t kourai-theoros -r and watch all three panes — REPL, Claude's reasoning, docker logs. Named after θεωρός — the Greek "state-appointed spectator sent by the polis to watch the sacred games and report back what was worth knowing." Ancestor of theater and theory.

Script: scripts/theoros.sh
Driver brief: scripts/theoros_autopilot.md
Prompt library: tests/fixtures/theoros_prompts.md
Skill (manual mode): techne:theoros
State file: /tmp/kourai-theoros.state

Role split¶

Two actors are watching the session, and each has a different job. The autopilot Claude in the middle pane covers the operational column; the human spectator covers the aesthetic column.

The split is committed to .claude/skill-context.md's ## theoros section and to the autopilot brief at scripts/theoros_autopilot.md.

Hard rule: if autopilot Claude asks you to paste log output, that's a regression on the role split — it should be capturing panes itself. The full discipline lives in the autopilot brief.

Starting a session¶

The stack must already be running:

make up

Then start theoros:

make theoros

Output prints the spectator command:

theoros session ready (autopilot).
  Spectate:   tmux attach -t kourai-theoros -r
  Take over:  tmux attach -t kourai-theoros
  Tear down:  make theoros-down

Claude is driving the REPL via the middle pane. Watch all three:
  top    — kourai REPL (the game)
  middle — Claude's reasoning
  bottom — docker compose logs

Attach from another terminal with -r for safe spectating. Drop the -r to take the wheel mid-session — all panes accept input from any attached client.

What's in the session¶

A single tmux session, kourai-theoros, with three panes:

The agent list in the bottom pane is curated, not exhaustive — edit ops_command: in .claude/skill-context.md to tail different agents per session. The full agent set is metis mneme kallos dokimasia puck cupid aidos aletheia hephaestus vn-bridge.

The prompt library at tests/fixtures/theoros_prompts.md is a golden dataset (2026 best practice: curated, not random) of (input, expected behavior, observable signal) triples covering every CHAT route. v1 covers 12 prompts; pipeline-triggering prompts are deferred to v2 (they take 5–20 minutes each and create forge sessions to clean up).

Manual mode (--no-autopilot)¶

When the techne:theoros skill is invoked from inside a Claude Code conversation, Claude is already the driver — a second claude pane would be redundant. The skill invokes the script with --no-autopilot:

bash scripts/theoros.sh up --no-autopilot

This gives the 2-pane layout (REPL top 60%, ops bottom 40%) with no autopilot Claude in the middle. You drive the REPL yourself (or via the surrounding CC conversation).

State¶

make theoros-status

Prints either the JSON state file or No theoros session running.:

{
  "session": "kourai-theoros",
  "started_at": "2026-05-17T14:23:01Z",
  "cwd": "/home/ajbar/ajsoftworks/kourai-khryseai",
  "repl_pid": 12345,
  "attach_cmd": "tmux attach -t kourai-theoros -r",
  "driver_pane": "kourai-theoros:0.0",
  "autopilot_pane": "kourai-theoros:0.1",
  "ops_pane": "kourai-theoros:0.2",
  "autopilot": 1
}

When autopilot is off, autopilot_pane is null and autopilot is 0. ops_pane shifts to kourai-theoros:0.1 (the 2-pane layout uses 0.0 + 0.1).

Tear down¶

make theoros-down

Kills the tmux session and removes /tmp/kourai-theoros.state. Tmux scrollback dies with the session.

Troubleshooting¶