Metadata-Version: 2.4
Name: councilroom-ai
Version: 0.1.0
Summary: A local council room for coordinating multiple coding agent CLIs.
Project-URL: Homepage, https://github.com/mosesmrima/councli
Project-URL: Repository, https://github.com/mosesmrima/councli
Project-URL: Issues, https://github.com/mosesmrima/councli/issues
Project-URL: Documentation, https://github.com/mosesmrima/councli/tree/main/docs
Author: councli contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,cli,coding-assistant,coordination,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# councli

`councli` is a local council room for multiple coding agent CLIs. It broadcasts
prompts to installed assistants, records their responses on an inspectable
blackboard, gives them shared visibility into each other's output, and returns a
unified answer while preserving each assistant's native harness.

It is not a model provider, not a replacement for Claude Code/Codex/AGY/Kimi,
and not a new tool sandbox. The assistants remain ordinary binaries on your
machine; `councli` is the room, recorder, router, and coordination layer around
them.

## Features

- Shared conversation turns by default.
- Explicit `/deliberate` and `/vote` commands for stronger coordination.
- Slash-command autocomplete, prompt history, and a terminal-friendly control
  plane.
- File-backed blackboards under `.councli/runs/`.
- Packet-file prompts and response sidecars for inspectable collaboration.
- Configurable participants for `codex`, `claude`, `agy`, `codewhale`, `kimi`,
  and custom adapters.
- `/enable <agent>`, `/disable <agent>`, and `/agents` for participant control.
- Native attach mode for using an assistant's own TUI when `tmux` is available.
- Read-only broadcast mode for comparing answers across assistants.
- Trust pins for command templates, binary paths, binary hashes, and elevated
  command surfaces.
- Packaged JSON Schemas under `councli.schemas` for protocol artifacts.
- Graceful degradation when an assistant is missing, disabled, unauthenticated,
  or missing a configured model.

## Platform support

`councli` is a pure Python CLI for Python 3.11+.

| Platform | Install | Core council turns | Native tmux attach |
| --- | --- | --- | --- |
| Linux | Supported | Supported | Supported with `tmux` |
| macOS | Supported | Supported | Supported with `tmux` |
| Windows | Supported | Supported with exec-mode agents | Use WSL for tmux |
| WSL | Supported | Supported | Supported with `tmux` |

Assistant availability depends on whether that assistant CLI is installed,
authenticated, configured, and on `PATH` in the same shell.

## Install

Recommended install from PyPI:

```bash
pipx install councilroom-ai
councli --help
```

The PyPI distribution is `councilroom-ai`; the installed shell command is
`councli`.

Install from GitHub:

```bash
pipx install "git+https://github.com/mosesmrima/councli.git"
councli --help
```

Install from a local checkout:

```bash
git clone https://github.com/mosesmrima/councli.git
cd councli
pipx install .
councli --help
```

For Linux, macOS, Windows, WSL, shell completion, upgrade, and troubleshooting
details, see [`docs/INSTALL.md`](docs/INSTALL.md).

## Quick start

From the project you want the assistants to inspect:

```bash
councli setup
councli doctor
councli
```

Inside the interactive shell:

```text
/agents
/enable claude
what can you all do?
/deliberate compare sqlite and postgres for this app
/vote choose the transport: exec, tmux
/assistant codex
/quit
```

Normal prompts run a shared conversation turn. Slash commands opt into stronger
coordination or local control-plane actions.

## Development

```bash
git clone https://github.com/mosesmrima/councli.git
cd councli
uv sync
uv run pytest -q
uv build
```

For contribution guidance, see [`CONTRIBUTING.md`](CONTRIBUTING.md). For build
and release details, see [`docs/PACKAGING.md`](docs/PACKAGING.md).

## Documentation map

- [`docs/INSTALL.md`](docs/INSTALL.md): install on Linux, macOS, Windows, WSL.
- [`docs/PACKAGING.md`](docs/PACKAGING.md): build, wheel checks, release steps.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): high-level design.
- [`docs/PROTOCOL_DESIGN.md`](docs/PROTOCOL_DESIGN.md): shared-turn protocol,
  state machine, sidecars, and locking rules.
- [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md): command trust, artifact
  secrecy, elevated command risk, and hardening gates.
- [`docs/TERMINAL_SUBSTRATE.md`](docs/TERMINAL_SUBSTRATE.md): tmux, PTY, TUI,
  native sessions, and terminal capture boundaries.
- [`docs/ADAPTER_CONTRACT.md`](docs/ADAPTER_CONTRACT.md): adapter readiness,
  capability-aware routing, launch states, and response sidecars.
- [`docs/STATE_CONCURRENCY.md`](docs/STATE_CONCURRENCY.md): events, blackboard
  projection, locking, crash recovery, and indexing.
- [`docs/RESEARCH_FINDINGS.md`](docs/RESEARCH_FINDINGS.md): consolidated
  research findings and implementation handoff.

## Config

`councli init` writes `.councli/config.yaml` in the current project.
Assistant command and transport fields in that file are pinned in user-local councli state
(`$COUNCLI_STATE_HOME`, `$XDG_STATE_HOME/councli`, or
`~/.local/state/councli`). The trust pin also records resolved binary paths and
executable hashes for enabled agents. If you edit command templates, binaries,
backend, enabled flags, broadcast flags, session names, or tmux input settings,
or if an installed assistant binary changes, review the file and run
`councli trust` before running assistant commands again. If a project was
intentionally moved or renamed, run `councli trust --repair-identity` after
reviewing the config. Use `councli trust --dry-run` to inspect command-field,
binary, and hash changes before accepting the current config.

Project-level fields include:

- `schema_version`: current config schema marker, currently
  `councli.config.v1`. Use `councli config check` and
  `councli config migrate` to inspect or upgrade legacy configs.

Each agent has:

- `enabled`: whether to consider it.
  Prefer `/enable <agent>` and `/disable <agent>` in the interactive shell for
  normal toggles; those commands update the config, refresh trust, and reload
  the current session.
- `backend`: `exec` or `tmux`.
- `binary`: executable name to find on `PATH`.
- `display_name`: optional human-readable adapter name.
- `capabilities`: optional intent list such as `chat`, `deliberate`, `vote`,
  `broadcast`, and `assistant`. Empty means infer support from configured
  commands.
- `command_capabilities`: what the normal prompt command may do, using values
  such as `planning_only`, `reads_workspace`, `writes_workspace`, `runs_tools`,
  `network_access`, and `full_permission`.
- `broadcast_capabilities`: capabilities for `broadcast_command`. If omitted,
  legacy configs infer read-only behavior from `broadcast_read_only`.
- `start_capabilities` / `resume_capabilities`: capabilities for native tmux
  start/resume commands.
- `read_only_policy`: `safe_only` by default for `chat`, `deliberate`, `vote`,
  and synthesis. Set `allow_full_permission` only when unsafe shared-turn
  routing is intentional.
- `broadcast_policy`: `safe_only` by default. Set `allow_full_permission` only
  when an unsafe broadcast fallback is intentional.
- `version_command`: optional lightweight version probe command.
- `readiness_command`: optional bounded, non-mutating probe for auth/model/quota
  readiness. Nonzero output is classified into statuses such as
  `auth_required`, `model_unconfigured`, or `quota_unavailable` when possible.
- `sandbox_wrapper`: optional argv prefix for exec-mode prompt commands, such
  as a local `bwrap`, `firejail`, or `systemd-run` wrapper. It is prepended to
  the rendered assistant command and is a trusted command-bearing field.
- `probe_timeout_seconds`: timeout for version/probe commands.
- `readiness_timeout_seconds`: timeout for the readiness probe.
- `command`: argv template. For `exec`, `{prompt}` is replaced with the generated prompt.
- `broadcast_command`: optional argv template for read-only broadcast/planning.
- `broadcast_enabled`: whether the agent can participate in broadcast.
- `broadcast_read_only`: legacy advisory field retained for old configs.
- `broadcast_timeout_seconds`: optional broadcast-specific timeout.
- `resume_command`: optional argv template where `{session_id}` is replaced by an imported native session id.
- `session_name`: tmux session name for `tmux` backend.
- `start_command`: command used to start the tmux session.
- `done_marker`: legacy base marker. Tmux runs use a unique per-turn marker to avoid stale scrollback.
- `prompt_style`: `compact` or `verbatim`. Use `compact` by default for TUI safety.
- `input_method`: `paste` or `type`. Use `type` for TUIs that keep bracketed paste in a draft composer.
- `submit_keys`: tmux keys used to submit after input, usually `["Enter"]`.
- `post_paste_delay_seconds`: delay between input and submit.
- `timeout_seconds`: max run time for one prompt.

Consensus settings:

- `max_rounds`: maximum implementation/review attempts before stopping.
- `min_confidence`: minimum `0.0` to `1.0` confidence for a vote or review to
  count toward majority. Low-confidence responses remain in the transcript and
  decision JSON, but they do not approve a plan or implementation.

Context packing settings:

- `peer_context_latest_rounds`: number of prior rounds included in the prompt
  excerpt for a follow-up round.
- `peer_context_per_participant_chars`: maximum characters copied from one
  participant into the peer-context excerpt.
- `peer_context_total_chars`: maximum characters copied into the whole
  peer-context excerpt before councli points agents at the full blackboard.
- `peer_context_include_failures`: `summary`, `full`, or `omit` for failed
  participant output in later-round prompts.

Native session settings:

- `tmux_socket`: dedicated tmux socket name, default `councli`.
- `detach_key`: simple tmux key chord used to return from attached assistant sessions, default `C-]`.
- `raw_log_max_bytes`: rotate raw pane recordings when they exceed this size on session start.
- `raw_log_backups`: number of rotated raw recordings to keep.
- `session_prefix`: prefix for project-scoped tmux session names.

Artifact hygiene settings:

- `prune_default_classes`: artifact classes pruned by default, currently raw
  logs, session archives, and session snapshots.
- `redact_patterns`: regexes used by `councli artifacts scrub`.
- `redact_replacement`: replacement text for scrubbed secrets.
- `scrub_max_file_bytes`: skip larger files during scrub to avoid accidental
  expensive rewrites.

`councli` deliberately does not model each participant's native feature set.
Slash commands, `@file` mention syntax, MCP configuration, plugins, goals, and
tool-specific subagents remain native to Codex, Claude Code, AGY, Kimi, or
CodeWhale. The MVP coordination layer sends ordinary task/packet prompts and
records artifacts; after a council pass, the user can still enter any native
participant session and use that tool's full UI directly.

Example:

```yaml
agents:
  codex:
    enabled: true
    binary: codex
    command: ["codex", "exec", "{prompt}"]
    timeout_seconds: 900
```

If an agent is unavailable, `councli` records that and continues with the available agents.
During one interactive `councli chat` session, repeated auth/model/quota
failures are marked degraded and skipped on later turns until you restart the
session.

`councli doctor --json` emits per-intent readiness objects, so setup scripts can
distinguish `ready`, `missing_binary`, `unsupported_intent`, `tmux_unavailable`,
`auth_required`, `model_unconfigured`, `quota_unavailable`, and disabled
participants without scraping the table output.

Native tmux-backed sessions are supported for CLIs that behave better interactively:

```yaml
  agy:
    enabled: true
    backend: tmux
    binary: agy
    command: ["agy"]
    session_name: councli-agy
    start_command: ["agy", "--dangerously-skip-permissions"]
    done_marker: "<<<COUNCLI_DONE:agy>>>"
    prompt_style: compact
    input_method: paste
    submit_keys: ["Enter"]
    post_paste_delay_seconds: 0.5
    timeout_seconds: 900
```

Useful commands:

```bash
councli sessions list
councli sessions start agy
councli sessions attach agy
councli sessions capture agy
councli sessions stop agy --dry-run
councli sessions prune --dry-run
```

Run inspection commands:

```bash
councli status
councli show latest
councli show <run-id-prefix> --blackboard
councli verify latest
councli verify <run-id-prefix> --json
councli recover latest
councli recover <run-id-prefix> --json
councli artifacts list
councli artifacts scrub --dry-run
councli artifacts scrub --write
councli artifacts prune --older-than 30 --dry-run
councli artifacts prune --older-than 30 --delete
councli worktrees prune --status abandoned --dry-run
councli worktrees prune --status abandoned --delete
```

`status` lists recent run ids with task, participants, decision, review, and
implementation status when present. `show` reopens a run's durable state and
prints the paths to its blackboard, machine state, event log, and artifacts.
`verify` checks a run's event log, refs, response sidecars, and rebuildable
projections before you trust, export, or share the output.
`recover` rebuilds `state.json` and `blackboard.md` from the run's event log
and artifacts, then verifies the rebuilt projections.
`security` prints the trusted command surface, resolved binaries, version
metadata, and drift status without running agent prompts, so it can diagnose
trust failures that would block `doctor`. Use `doctor --security` when you want
the same security summary beside normal readiness checks.
`artifacts scrub` redacts common secret-looking tokens from text artifacts and
defaults to dry-run. `artifacts prune` removes old raw logs, session archives,
and snapshots by default, and only deletes when `--delete` is supplied.
`artifacts export` creates a redacted `.tar.gz` support bundle with a manifest.
It exports run/task/ledger/snapshot artifacts by default and excludes raw
terminal recordings unless you explicitly choose that artifact class.
`worktrees prune` finds councli-created implementation worktrees from run state.
It defaults to dry-run and only removes safe registered worktrees on `councli/`
branches under the expected `.councli-worktrees/<repo>` directory.
`metrics` derives local JSON or OpenMetrics-style counters from event logs,
participant response sidecars, and artifact sizes.

Interactive councli shell:

```bash
councli chat
```

Inside `chat`, type a normal prompt to run a shared conversation turn. `councli`
fans the prompt out to available assistants, records their responses on the
blackboard, synthesizes a single council answer, and returns to `councli>`.
Normal prompts do not force a fixed orient/propose/critique/revise/vote
lifecycle.

Terminology:

- A `councli chat` session is the interactive shell lifetime.
- A turn is one user prompt inside that shell.
- A round is one fan-out pass to participants inside a turn.

Every new prompt starts a new turn, so seeing `Round 1` multiple times in one
interactive session is expected.

Use explicit commands when you want stronger coordination:

- `/deliberate <prompt>` asks participants to respond independently, then gives
  them a peer-aware second round before synthesis.
- `/vote <prompt>` asks for explicit votes and records a decision artifact.
- `/assistant <name>` attaches to a native assistant session.
- `/synthesizer <name>` chooses which assistant writes the unified answer.
- `/agents`, `/enable <name>`, and `/disable <name>` manage participants.

Local shell commands include `/help`, `/doctor`, `/agents`, `/enable`,
`/disable`, `/status`, `/show`, `/sessions`, `/assistant <name>`, `/broadcast
<prompt>`, `/brief [task]`, `/synthesizer [name|auto|clear]`, `/deliberate
<task>`, `/vote <task>`, and `/quit`. Unknown `/` commands are rejected
explicitly. To send a task that literally starts with `/`, prefix it as
`//task`.

`/assistant codex` attaches your terminal to Codex's native tmux session. Codex
owns the keyboard, slash commands, permission prompts, and UI exactly as if you
had launched it directly. Press `Ctrl-]` to detach back to `councli`. Raw pane
output is recorded under `.councli/session-recordings/` for audit/debugging;
`councli` does not parse terminal screen output as the semantic source of truth.
Use `native.detach_key` in config to choose a different detach chord. If you are
already inside tmux, `councli` unsets `$TMUX` for the inner attach and uses its
dedicated tmux server.

`/broadcast <prompt>` and `councli broadcast` use configured non-interactive
commands where available. Broadcasts are meant for planning, critique,
comparison, and review, not concurrent edits in the same worktree. Broadcast
does not inject prompts into active tmux assistant sessions; it launches
headless subprocesses, records each participant result, and does not retry
failed participants. `broadcast_command` is preferred when configured. If it is
missing, `councli` may fall back to the normal prompt-capable `command` and
records that read-only enforcement was not explicit. If a tool is not
authenticated or lacks a configured model, that participant is recorded as a
runtime failure instead of blocking the rest.

Before council/broadcast runs, `councli` writes an inspectable task brief under
`.councli/tasks/<run-id>/brief.md` and copies it into the run directory. The
brief points at native sessions and recent `councli` events instead of silently
stuffing hidden history into prompts.
Use `/brief` or `councli brief` to print the latest brief and a pasteable
instruction for an attached assistant.

Tmux sessions are project-scoped by a hash of the project path and run under the
dedicated `tmux -L councli` server. `.councli/project.json` stores the project
identity so accidental project moves or copied `.councli/` directories are
detected. If a session already exists but its pane is in another directory,
`councli` refuses to reuse it. `sessions list` reconciles the registry against
live tmux sessions, shows the pane's current command, and marks missing, dead,
shell-returned, or cwd-mismatched sessions stale.
`sessions stop` kills configured tmux-backed participant sessions. `sessions
prune` kills configured councli tmux sessions plus visible `councli-room-*`
rooms, archiving captured pane text first by default under
`.councli/session-archives/`. Use `--dry-run` before cleanup when you want to
inspect the target list.

The `council` command is a compatibility entrypoint for an explicit shared
deliberation turn against available participants:

```bash
councli council -p codex -p agy "Decide the smallest safe plan"
```

It writes packet files, participant response sidecars, synthesis artifacts, and
a blackboard under `.councli/runs/<run>/`. The older fixed phase engine remains
hidden for development while the shared-turn protocol is hardened.

CodeWhale/DeepSeek is supported with the non-interactive command:

```yaml
  codewhale:
    enabled: true
    binary: codewhale
    command: ["codewhale", "--yolo", "exec", "--auto", "{prompt}"]
    timeout_seconds: 900
```

Kimi Code is supported with:

```yaml
  kimi:
    enabled: true
    binary: kimi
    command: ["kimi", "--prompt", "{prompt}"]
    timeout_seconds: 900
```

## Current limits

This is v0. It now focuses the public surface on shared conversation,
deliberation, explicit voting, native attach, durable artifacts, and adapter
readiness. Hidden experimental worktree execution/review commands still exist
for development, but they are not the MVP path and require
`COUNCLI_EXPERIMENTAL=1`. Next steps are:

1. Keep improving adapter-specific readiness probes where each CLI exposes a
   richer safe diagnostic command.
2. Continue polishing the interactive prompt and consider a full-screen TUI
   only after the protocol proves useful in normal terminals.
3. Decide whether to delete or separately package the hidden execution/review
   prototype.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design and
[docs/ADAPTER_CONTRACT.md](docs/ADAPTER_CONTRACT.md) for the generic adapter
contract. State and concurrency rules live in
[docs/STATE_CONCURRENCY.md](docs/STATE_CONCURRENCY.md). Participant-specific
CLI notes live in
[docs/ADAPTERS.md](docs/ADAPTERS.md).
