jaosua-agents

A tmux-based multi-agent orchestration system — a hierarchy of AI coding agents (CEO → Manager → Advisor → Staff×7) commanded by one human boss, themed as a Thai corporate dynasty ("เจ้าสัว / Tycoon"). Bilingual EN/TH, portable across macOS and Linux, and CLI-agnostic (Claude Code + Codex in v1).

It is a 100% rewrite of multi-agent-shogun: reverse-engineered from the working system, re-themed, theme-decoupled, and hardened — every behavioral decision now reads a capability flag from one registry instead of matching on a role name.

The cast

Role	TH	EN	CLI / model	Job
Boss	เทพ	Boss	(human)	Gives orders. Not an agent — display only.
CEO	ซีอีโอ	CEO	claude / opus	Orchestrator. Decides what, never how. Reads the dashboard.
Manager	ผู้จัดการ	Manager	claude / sonnet	Traffic control. Delegates, owns the dashboard, receives completion notices.
Advisor	ที่ปรึกษา	Advisor	claude / opus	Strategy + QC gate + root-cause analysis. Thinker, not doer.
Staff ×7	พนักงาน	Staff	claude/codex / sonnet	Front-line workers. Each report to the Advisor.

Chain of command is strict: Boss → CEO → Manager → Advisor/Staff. Nobody bypasses the Manager.

Quickstart

Prerequisites: tmux, python3, and the agent CLIs you intend to use (claude, codex). bash 3.2+ (the macOS default) is fine.

make venv                      # create .venv + install pyyaml, jsonschema, pytest
bash scripts/start.sh          # DRY-RUN: prints the exact launch plan, touches nothing
bash scripts/start.sh --go     # LIVE: creates tmux sessions and starts real (paid) agents
make check                     # run the full verification suite

scripts/start.sh with no flag is a safe dry-run — it prints every session, pane, @agent_id stamp, and launch command without creating anything, so it is safe to run anywhere. --go is the only thing that spends money.

Live mode opens two tmux sessions: ceo (the human-facing CEO pane) and office (the worker grid). Attach with tmux attach -t ceo.

How it works

• Theme is data, not code. Role names, personas, and per-role behavior live in config/theme.yaml. Re-theming or switching language (locale: en|th) is a one-file edit; no logic changes.
• The roster is explicit. config/agents.yaml lists each agent instance and its CLI. The system never parses an id to infer role or rank.
• Communication is a file mailbox. Agents talk via queue/inbox/{agent}.yaml (written through scripts/inbox_write.sh); scripts/inbox_watcher.sh watches each inbox and delivers a minimal inboxN wake-up nudge. Message content never travels through tmux keystrokes.
• Completion is CLI-agnostic. An agent signals "done/failed" by writing a status to its report YAML; scripts/notify_completion.py routes the notice to the Manager. This works for Codex too, which has no Stop hook.
• Instructions are generated, not hand-edited. roles/ + personas/ + common/ + cli/ compile into generated/{cli}-{role}.md via scripts/build_instructions.py, with a --check sync gate so the sources and outputs can never drift.

Verification

make check runs: validate (config/schema), test (pytest), compat (bash-3.2 portability), roundtrip (queue read/write), parity (the M1–M13 mitigation contract that reproduces the reference system's hard-won fixes), state, launchplan (golden dry-run plan), instructions (generator sync), and peripherals.

Repo layout

config/      theme.yaml (registry), agents*.yaml (rosters), status.yaml (enums)
schema/      JSON schemas for queue/config validation
roles/ personas/ common/ cli/   instruction sources  →  generated/
scripts/     start.sh, inbox_watcher.sh, queue_write.py, registry.py, notify_completion.py, …
lib/         cli_adapter.sh (per-CLI behavior), compat.sh (bash-3.2 helpers)
queue/       live task/inbox/report data (git-ignored)
docs/        PRD.md · reference/ (reverse-engineered specs) · PHASE8_E2E.md
memory/      MEMORY.md — persistent cross-session memory

Start with PRD.md for the architecture and docs/reference/ for the five reverse-engineered subsystem specs.

Status

Built and tested. Phase 8 ran a real end-to-end delegation across both CLIs (Claude + Codex) — see docs/PHASE8_E2E.md. v1 targets claude + codex (the owner's machine); adding a CLI means extending lib/cli_adapter.sh.

Language

Code and docs are English. Persona and display strings are bilingual EN/TH, selected by the single locale switch in config/theme.yaml.

Safety

The Thai corporate satire targets only fictional roles. Agents operate under an unconditional destructive-operation policy (see common/forbidden_actions.md): no rm -rf outside the project tree, no force-push, no killing other processes, no pipe-to-shell.