GitHub - mfelix/quibble: Adversarial AI document review CLI that iterates Codex and Claude until consensus, with resumable sessions.

Adversarial AI document review CLI that iterates between Codex (reviewer) and Claude (author) until consensus is reached. Quibble is designed for markdown documents and keeps a resumable session history on disk by default.

Requirements

• Node.js >= 18
• OpenAI Codex CLI available on PATH (codex)
• Anthropic Claude Code CLI available on PATH (claude)

Install

Run directly without installing:

npx @mfelix.org/quibble <file>

Or install globally for repeated use:

npm install -g @mfelix.org/quibble
quibble <file>

From source

git clone https://github.com/mfelix/quibble.git
cd quibble
npm install
npm run build
npm link

Usage

Example:

Focus the review on specific aspects:

quibble docs/plan.md --focus "security and error handling"

CLI Options

--focus <guidance>            Focus the review on specific aspects
--json                        Output structured JSONL events
--max-rounds <n>              Maximum review cycles before forced stop (default: 5)
--output <path>               Output path for final document
--resume <id>                 Resume a previous session by ID
--session-dir <p>             Override session storage location
--no-persist                  Disable session storage; runs in-memory only
--no-summarize-items          Disable LLM summarization of issues/opportunities
--context-max-files <n>       Max auto-included context files
--context-max-file-bytes <n>  Max bytes per context file
--context-max-total-bytes <n> Max total bytes across context files
--debug-claude                Log raw Claude stream lines for debugging
--debug-codex                 Log raw Codex stream lines for debugging
--keep-debug                  Keep debug logs after a successful run
--dry-run                     Show resolved config and exit

How It Works

Each round has three phases:

1. Codex reviews the document and returns issues/opportunities.
2. Claude responds, updates the document, and assesses consensus.
3. Codex checks whether the response resolves the feedback.

The loop stops when consensus is approved, the max rounds are reached, or a failure occurs.

Context Discovery

Quibble auto-includes repo files referenced by path in the document. It looks for file path mentions and pulls the matching files as context for Codex and Claude, with size caps and skipping common build/output directories.

Output Files

Quibble writes a final document next to the input by default:

It also writes session artifacts (unless --no-persist) under:

.quibble/sessions/<session-id>/

Typical session layout:

.quibble/sessions/<session-id>/
  manifest.json
  round-1/
    codex-review.json
    claude-response.json
    codex-consensus.json
    timings.json (durations + token counts)
    document-v1.md
  final/
    document.md
    summary.json
  debug/
    claude-stream-round-1.log
    codex-stream-round-1.log

JSONL Output

When --json is set, Quibble emits one JSON object per line with event types:

• start, round_start
• codex_review, codex_progress
• claude_progress, claude_response
• consensus, complete, error

This is useful for CI or custom UIs.

Exit Codes

• 0: Completed successfully (or max rounds reached with no unresolved critical/major issues)
• 1: Max rounds reached with unresolved major issues
• 2: Failure or unresolved critical issues

Debugging

If Claude or Codex progress appears stuck, enable debug logs:

quibble example.md --debug-claude --debug-codex --keep-debug

Logs are written to the session debug/ directory. By default they are deleted after a successful run; use --keep-debug to retain them.

Development

npm install
npm run build
npm run typecheck
npm test

Troubleshooting

• Ensure codex and claude are on PATH.
• If the CLI times out, re-run with debug flags and inspect the logs.
• For large documents, increase --max-rounds or edit prompts in src/prompts/.