Metadata-Version: 2.4
Name: codex-roundtable
Version: 0.2.0
Summary: Local multi-participant discussion orchestrator for Codex
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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

```bash
python3 -m pip install -e .
```

Source-tree execution without installation is also supported:

```bash
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:

```bash
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

```bash
# 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` | Prints one persisted run artifact. |
| `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`) |
