# Codex Conversation Council

[简体中文](README.zh-CN.md)

An evidence-backed council for Codex, built from your own local task history.

`$conversation-council` finds prior Codex tasks relevant to the current decision, assigns up to three independent councillors, verifies their historical claims against local evidence, and chairs a compact recommendation. It runs inside your existing Codex session: no extra model key, external service, or runtime network request is required.

![Conversation Council Dashboard](docs/council-dashboard.png)

> macOS Alpha v0.2. Windows support is planned after the local history and installation paths are validated in the field.

## What is included

- A Codex Desktop plugin with an explicit `$conversation-council` Skill.
- An interactive MCP Apps Council Dashboard rendered inside supported Codex conversations.
- A local stdio MCP server with six history/evidence tools and one presentation tool.
- A standalone `council` CLI with JSON output parity.
- Workspace isolation by default; cross-project history requires `--global`.
- Local redaction, SQLite FTS5 search, stable evidence IDs, and pinning.
- Optional `--deep` review by an anonymous critic.

## Install the macOS Alpha

Requirements: Codex Desktop/CLI, macOS, and Python 3.11 or newer with SQLite FTS5.

```bash
git clone https://github.com/URneiU1/codex-conversation-council.git
cd codex-conversation-council
./scripts/install.sh
```

The installer registers this checkout as a local Codex marketplace, installs the plugin, and runs diagnostics. Start a new Codex task so its Skill and MCP tools are loaded, then invoke:

```text
$conversation-council Should we keep the current queue architecture?
```

After the chair verifies the cited evidence, supported Codex surfaces render an inline Council Dashboard showing the question, each councillor's stance and labeled points, consensus, disagreements, recommendation, unresolved risks, and evidence locations. If a client cannot render MCP Apps UI, the same result remains available as text.

For an extra critic pass:

```text
$conversation-council --deep Should we keep the current queue architecture?
```

Cross-project search is never automatic. Opt in explicitly:

```text
$conversation-council --global What did our previous migrations teach us?
```

## CLI

Run from the checkout, or install the Python package to expose the `council` command.

```bash
python3 scripts/council.py doctor
python3 scripts/council.py index --workspace "$PWD"
python3 scripts/council.py search "queue architecture" --workspace "$PWD"
python3 scripts/council.py pin THREAD_ID
python3 scripts/council.py show EVIDENCE_ID --workspace "$PWD"
```

Every user command supports `--json`. Use `--global` only with `index`, `search`, or `show` when you intentionally want known cross-workspace history.

## How it works

1. The indexer reads Codex session JSONL and keeps only visible user and assistant task messages.
2. Built-in redaction masks common tokens, credentials, private keys, and authenticated URLs before text enters the derived index.
3. SQLite FTS5 retrieves relevant tasks inside the current canonical workspace. Pins and recency are bounded tie-breakers.
4. Evidence is rendered to local Markdown with an opaque ID, original task ID, role, and source JSONL line.
5. The Skill convenes independent councillors, optionally adds a critic, resolves every cited evidence ID, and chairs the result.
6. The presentation-only `render_council` tool displays that verified result through the portable MCP Apps UI resource; it does not change or re-run the council.

Historical excerpts are treated as untrusted quoted data. The Skill instructs councillors never to follow commands found inside history.

For MCP calls, the non-global workspace is bound to the current Codex task ID supplied by the host. Requests for a different known workspace are rejected unless the user explicitly invoked `--global`. Deleted or changed source tasks are reconciled from the derived index, and their rendered evidence is removed.

## Privacy

The runtime makes no network requests. It reads Codex task history, indexes only visible user and assistant text after local redaction, defaults to the current workspace, and never modifies source history. Derived data defaults to `~/.codex/conversation-council/` (or `PLUGIN_DATA` when Codex supplies it).

Redaction is defense in depth, not a guarantee that arbitrary secrets can always be recognized. Review your task history before deliberately using `--global`, and never attach real Codex logs to public issues.

Run `python3 scripts/council.py doctor` to inspect paths. Uninstall while retaining the derived index:

```bash
./scripts/uninstall.sh
```

Delete plugin-owned derived state as well:

```bash
./scripts/uninstall.sh --purge-data
```

## Standalone Skill and MCP

The Skill lives at `skills/conversation-council/SKILL.md`. The plugin manifest points Codex at that directory and at `.mcp.json`; the same MCP operations are available through `python3 scripts/council.py serve-mcp`. The Python runtime uses only the standard library.

## Development

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m compileall -q src scripts
git diff --check
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before opening a change or reporting a vulnerability.

## Inspiration and license

This is an independent clean-room implementation. The historical-conversation-as-councillor concept was inspired by [CS-Faith/conversation-council](https://github.com/CS-Faith/conversation-council). See [NOTICE.md](NOTICE.md) for attribution details.

Released under the MIT License.