codex-roundtable 0.2.0

Local multi-participant discussion orchestrator for Codex

codex-roundtable

codex-roundtable is a standalone local orchestrator that runs one moderated discussion round, with one optional bounded follow-up round, across fixed participants and saves auditable artifacts.

Purpose

• Run one initial discussion round per command with Codex as moderator.
• Optionally run one follow-up round when --follow-up-once is enabled and round-one replies reveal a bounded disagreement, risk, or recommendation gap.
• Collect participant responses from bridge CLIs (codex2claude, codex2opencode).
• Produce conservative synthesis and persist JSON + Markdown artifacts.
• Preserve session continuity with lock-based concurrency control.

Boundaries

• This repository is an orchestrator, not a framework.
• Bridge repositories stay separate; this package shells out to bridge CLIs.
• v2.1 supports one initial round plus one optional second round.
• v2.1 participants are fixed to claude and opencode.
• single-participant requests should stay on the corresponding single bridge skill/CLI and should not trigger roundtable.

Install

python3 -m pip install -e .

Source-tree execution without installation is also supported:

PYTHONPATH=orchestrator python3 -m codex_roundtable --help

Install Skill Locally

If you want Codex to route explicit multi-participant requests into this CLI, install the skill into your local Codex skill directory:

mkdir -p ~/.codex/skills
ln -sfn "$PWD/skills/codex-roundtable" ~/.codex/skills/codex-roundtable

After installing or updating the skill, start a fresh Codex session so the new trigger rules are picked up.

Quick Start

# Check local dependencies and writable state home
codex-roundtable doctor

# Run one discussion round (session continuity is keyed by workspace + session)
codex-roundtable discuss \
  --topic "Should we split this repo into bridge and orchestrator?" \
  --workspace "$PWD" \
  --session architecture \
  --timeout 60

# Run one bounded second round when the first round exposes a useful follow-up
codex-roundtable discuss \
  --topic "Review this rollout plan and follow up once if they disagree." \
  --workspace "$PWD" \
  --session rollout-review \
  --timeout 60 \
  --follow-up-once

# Inspect persisted state and artifacts
codex-roundtable status --workspace "$PWD" --session architecture
codex-roundtable show --run-id run-20260328T120000000000Z --format json
codex-roundtable show --run-id run-20260328T120000000000Z --format markdown

Commands

Command	Purpose
codex-roundtable discuss --topic ... --workspace ... --session ... [--follow-up-once]	Runs one initial discussion round and optionally one bounded follow-up round.
codex-roundtable doctor [--workspace ... --session ...]	Emits JSON diagnostics for state home, participant bridges, and optional session state.
codex-roundtable status --workspace ... --session ...	Prints persisted session JSON.
`codex-roundtable show --run-id ... --format json	markdown`
codex-roundtable forget --workspace ... --session ...	Deletes session state + lock file only (keeps run artifacts).
codex-roundtable gc --max-age-days N	Deletes old unlocked session/run files.

Skill Routing

These intents should trigger roundtable:

• roundtable 一下这个方案
• 让 cc 和 opencode 都看一下
• 做一个多方 review
• 圆桌会议讨论这个设计
• 如果有分歧再追问一轮

These intents should not trigger roundtable:

• 问问 cc
• 让 oc 看一下
• Claude 怎么看
• 给 cc review 一下
• 给 opencode 看看

Roundtable is for explicit multi-participant intent. Single-participant intent should route to the single bridge instead of codex-roundtable.

Artifact Notes

Persisted run JSON is versioned. v2.1 artifacts add:

• version = "2.1"
• follow_up_enabled
• follow_up_reason
• stop_reason
• rounds[].prompt_role

stop_reason records why the discussion ended, for example round_one_complete, follow_up_not_needed, follow_up_complete, follow_up_failed, or all_participants_failed.

Doctor Output

codex-roundtable doctor returns JSON with these top-level keys:

• ok: overall health boolean.
• roundtable_home: path/read-write checks.
• participants: bridge command availability for claude and opencode.
• session_state: optional session check (ok, missing, skipped, or error states).

Troubleshooting

• participants.*.status=missing in doctor: install or expose codex2claude and codex2opencode on PATH.
• workspace does not exist: pass an existing path to --workspace.
• Session lock conflict: another process is using the same workspace/session key; retry after it completes.
• run artifact not found from show: check --run-id and --format, or list files under ~/.codex/codex-roundtable/runs/.

State Layout

Default state root is ~/.codex/codex-roundtable. Override with CODEX_ROUNDTABLE_HOME.

• sessions/<session_key>/session.json
• sessions/<session_key>/session.lock
• runs/<session_key>/<run_id>.json
• runs/<session_key>/<run_id>.md
• logs/sessions/<session_key>.jsonl
• logs/runs/<session_key>/<run_id>.jsonl

Compatibility Matrix

Component	v1 Support
Python	3.11+
OS	macOS and Linux
Discussion rounds	One initial round plus one optional second round
Moderator	Codex (fixed)
Participants	claude, opencode
Participant transport	External bridge CLIs (codex2claude, codex2opencode)