the-council

The Council

Convene OpenAI Codex and Google Gemini as an advisory board. Both run in parallel via their CLIs, with full project context, and return independent analyses that Claude synthesizes.

Prerequisites

• Project has a CLAUDE.md file in the working directory
• At least one of the following CLIs installed and authenticated:
  • codex CLI (npm i -g @openai/codex)
  • agy CLI (antigravity CLI)

Permission Setup

Before running any council scripts, request all necessary bash permissions upfront at the start of the session. This prevents permission prompts from interrupting the advisory flow mid-execution.

Tell the user:

The Council needs to run bash scripts to invoke external advisors. I'll request permission for all of them now so the flow isn't interrupted.

Then run all three scripts in sequence to trigger permission grants:

1. bash <skill_dir>/scripts/council_preflight.sh <working_directory> — CLI availability check
2. bash <skill_dir>/scripts/council_sync.sh <working_directory> — context sync
3. bash <skill_dir>/scripts/council_invoke.sh (with --help or a no-op) — advisor invocation

Once permissions are granted, proceed with the workflow. The user will not be prompted again for these scripts during the session.

Workflow

0. Preflight Check (First Invocation Only)

On the first council invocation in a session, run the preflight script to detect available advisors:

bash <skill_dir>/scripts/council_preflight.sh <working_directory>

Parse the output (key=value lines) and determine the operating mode:

Codex Auth	Gemini Auth	Mode
true	true	Full Council — both advisors in parallel
true	false	Codex-only — single advisor mode
false	true	Gemini-only — single advisor mode
false	false	Abort — show installation instructions below

If no advisors are available, display this help and stop:

Neither Codex nor Gemini CLI is available. To use The Council, install at least one:

  Codex:  npm i -g @openai/codex && codex auth
  Gemini: Install agy CLI and verify it is logged in via ~/.gemini/oauth_creds.json (runs automatically on first command)

If one advisor is missing, note which mode is active and proceed. Example:

Council running in Codex-only mode (Gemini CLI not found).

The preflight result is cached for 2 hours — subsequent invocations skip this step automatically.

1. Sync Project Context

Run the sync script to copy CLAUDE.md content into AGENTS.md (for Codex):

bash <skill_dir>/scripts/council_sync.sh <working_directory>

This creates/overwrites AGENTS.md with an advisory preamble + full CLAUDE.md content. Run this once per session or when CLAUDE.md changes. Gemini does not need a context file — it runs from the project directory with read access and receives task-specific context (diffs, plans, questions) via the prompt.

Important: After the council session, clean up the generated file:

rm <working_directory>/AGENTS.md

2. Compose the Advisory Prompt

Select the appropriate template from references/prompt-templates.md based on the use case:

Use Case	Template
Code review	Code Review
Plan/architecture evaluation	Architecture / Planning
Bug investigation	Debugging
General question	General Advisory

Write the composed prompt to a temporary file. Include all relevant context inline (diffs, error messages, plan text) — the advisors cannot read Claude's conversation history.

Context in prompts: Both advisors have read-only filesystem access to the working directory (Codex via its native --sandbox read-only; Gemini via agy wrapped in sandbox-exec on macOS — see Permissions and Safety). However, task-specific context (diffs, error messages, plan text, conversation history) must still be inlined because advisors cannot access Claude's conversation or external paths like ~/.claude/plans/.

• Always inline: diffs, error output, plan text, conversation excerpts, and any content from outside the project directory
• Can reference by path: codebase files that advisors can read directly (e.g., "see src/config.ts for the current implementation")
• For code review: the diff must be inlined (advisors don't have access to git staging), but surrounding context files can be referenced by path
• For large files referenced in the prompt: include the most relevant sections inline, note the file path for full context

3. Invoke The Council (Progressive)

Invoke each advisor as a separate background bash task so results can be presented as they arrive.

3a. Launch Advisors as Background Tasks

For Full Council mode, launch two separate background bash commands simultaneously:

# Launch Codex as background task
bash <skill_dir>/scripts/council_invoke.sh --codex-only <prompt_file> <working_directory>

# Launch Gemini as background task
bash <skill_dir>/scripts/council_invoke.sh --gemini-only <prompt_file> <working_directory>

Run both commands using run_in_background: true in the Bash tool. Each produces its own temp directory (.council-tmp/council_codex_YYYYMMDD_HHMMSS/ and .council-tmp/council_gemini_YYYYMMDD_HHMMSS/ inside the working directory).

For single-advisor modes (Codex-only or Gemini-only), launch only the available advisor as a single background task.

3b. Poll and Present Progressive Results

After launching both tasks, poll for completion using non-blocking TaskOutput checks (with block: false). When the first advisor finishes:

1. Read its response from the temp directory path printed in its output
2. Present the early result to the user immediately:

## Early Result: {Advisor Name} ({model})

{advisor response}

---
*Waiting for {other advisor name} to complete...*

3. Continue polling the second advisor

When the second advisor finishes, read its response and proceed to Step 3.5 (question detection) and then Step 4 (synthesis).

3c. Handling Failures

When an advisor fails (non-zero exit, empty response file, or error patterns in output):

1. Read the error log first — always read the *_error.log file from the temp directory before reporting failure:
   • Codex: <working_directory>/.council-tmp/council_codex_*/codex_error.log
   • Gemini: <working_directory>/.council-tmp/council_gemini_*/gemini_error.log
2. Read the response file — even failed runs may have partial output worth presenting
3. Report the specific error from the log, not a guess. Common failures:
   • empty response — advisor ran but produced no text output
   • unproductive state — Gemini entered a tool-call loop
   • Path not in workspace — prompt referenced files outside the sandbox
   • RESOURCE_EXHAUSTED / rate limit — API quota hit
   • Argument list too long — prompt exceeds shell argument limit (~260KB on macOS)
   • command not found — CLI not installed or not in PATH
4. If one advisor succeeds, present its response and note the other's failure with the actual error
5. If both fail, present both error logs and suggest checking CLI authentication (codex auth / gemini auth)

3d. Fallback

If progressive invocation is not possible (e.g., background tasks not supported), fall back to the single blocking call:

bash <skill_dir>/scripts/council_invoke.sh <prompt_file> <working_directory>

Environment overrides:

• CODEX_MODEL — default: auto (from ~/.codex/config.toml)
• GEMINI_MAX_TURNS — default: 100 (session turns; COUNCIL_TIMEOUT is the primary safety net)
• AGY_PRINT_TIMEOUT — default: 8m (override agy --print-timeout; agy's 5m default can race with COUNCIL_TIMEOUT; 8m keeps COUNCIL_TIMEOUT as the outer bound)

3.5. Question Detection & Auto-Retry

After reading each advisor's response (during progressive polling or after completion), check whether the response contains questions directed at you rather than analysis. Advisors sometimes ask clarifying questions instead of providing their assessment.

Detecting Questions

Scan the advisor response for patterns indicating it needs clarification rather than providing analysis:

• Direct questions ("What is...", "Can you clarify...", "Which approach...", "Could you provide...")
• Requests for information ("I need to know...", "Please share...", "It would help to understand...")
• Conditional analysis ("If X then Y, but if Z then W — which is the case?")

Not all question marks are triggers. Rhetorical questions, questions posed as part of analysis ("Have you considered...?"), and section headers ("What could go wrong?") are normal advisory output. Only trigger retry when the advisor is unable to provide analysis without the answer.

Heuristic: If the response is short (under ~200 words) AND primarily consists of questions rather than analysis, treat it as a question response. If the response contains substantial analysis alongside questions, treat it as a normal response.

Auto-Answer and Retry Flow

When a question is detected in an advisor's response:

1. Extract the question(s) from the response

2. Attempt to answer from project context — search the codebase, CLAUDE.md, conversation history, and relevant files

3. Assess confidence:

   • Confident (answer clearly supported by project context): proceed to auto-retry
   • Unsure (requires judgment or information not available): ask the user:

     {Advisor Name} asked a clarifying question instead of providing analysis:
     
     > {advisor's question}
     
     I'm not confident I can answer this from project context. What's the answer?
     

     Wait for the user's response before proceeding.

4. Compose retry context — write the Q&A to a temporary context file:

   Question from {Advisor Name}: {question}
   Answer: {answer from project context or user}
   
   Please provide your analysis based on this clarification. Do not ask further questions about this topic.
   

5. Re-invoke the same advisor with the context file:

   bash <skill_dir>/scripts/council_invoke.sh --{advisor}-only --context-file <context_file> <prompt_file> <working_directory>
   

6. Read the new response and check again for questions (loop back to detection)

Retry Guards

• Question tracking: Keep a list of questions already asked by each advisor. If the same question (or substantially similar) appears again after a retry, stop retrying and present the best response received so far with a note about the unresolved question.
• Hard cap: Maximum 3 retries per advisor. After 3 retries, present whatever response was received with a note:

  Note: {Advisor Name} requested clarification {N} times. Presenting the best response received.
  

• Per-advisor tracking: Retry counts and question lists are tracked independently for Codex and Gemini. One advisor hitting its cap does not affect the other.

Retry During Progressive Invocation

When using progressive invocation (Step 3), retries happen per-advisor:

• If one advisor finishes with a question, begin the retry flow for that advisor while the other is still running
• If the other advisor finishes with analysis while the first is retrying, present its result immediately
• Synthesis (Step 4) waits until all retries are complete and both advisors have final responses

4. Analyze and Present

If you presented an early result during progressive polling (Step 3b), the user has already seen one advisor's response. Do not re-print it. Present only the new response and the synthesis.

Full Council Mode (both advisors responded)

Default mode — Synthesis: Read both responses, identify areas of agreement and disagreement, then present:

## Council Synthesis

**Consensus:** [Points both advisors agree on]

**Divergence:** [Points where they disagree, with each position]

**Claude's Recommendation:** [Your assessment integrating all three perspectives — yours plus both advisors'. Note: Codex remains the primary source of truth and the main shipping gate; Gemini is advisory.]

Side-by-side mode (when user requests "show me both" or "side by side"):

## Codex ({codex_model})
[Full Codex response]

## Gemini (Gemini 3.5 Flash)
[Full Gemini response]

## Claude's Take
[Your own assessment]

Single-Advisor Mode (one advisor responded)

Present the single advisor's response with your own assessment.

[!IMPORTANT] If Gemini (agy) dropped out mid-session or failed validation (returning an error log/response), you must explicitly surface this failure as a "degraded one-advisor Council (Codex only)" and never silently ignore it.

If Gemini is the only advisor that responded (e.g. Gemini-only mode or Codex failed), remember that Gemini must never act as a sole shipping gate. Its opinions are strictly advisory, and Codex remains the primary codebase source of truth.

## Advisory Opinion ({Advisor Name} / {model})
[Full response from the available advisor]

## Claude's Assessment
[Your own perspective, noting this was a single-advisor review]

5. Cleanup

CRITICAL: Do NOT clean up until ALL of the following conditions are met:

1. All advisor responses (including retries) have been fully read into your context (i.e., you have used the Read tool on every response file and have the content in your conversation)
2. Synthesis (Step 4) is complete and has been presented to the user
3. If running with run_in_background: true, ensure the background task has finished AND you have read all output files before cleanup

Why this matters: Response files live inside .council-tmp/. If you delete that directory before reading the files, the responses are lost permanently.

Once all conditions above are satisfied, remove temporary files:

• The prompt file
• The .council-tmp/ directory from the working directory (rm -rf <working_directory>/.council-tmp/) — this removes all response files, error logs, context files, and the preflight cache at once
• AGENTS.md from the working directory

Permissions and Safety

Both advisors run with OS-enforced read-only sandboxes on macOS. Neither can write to your project directory; tool calls that try to write fail at the OS layer.

• Codex: --sandbox read-only — Codex's built-in OS-level filesystem deny-write.
• Gemini (agy) on macOS: wrapped in sandbox-exec using a deny-write profile at scripts/council_sandbox.sb. The profile allows reads everywhere; allows writes only to ~/.gemini/, the per-invocation .council-tmp/<...>/ dir, system temp (/tmp, /private/tmp, /private/var/folders), and the agy-specific subdirs under ~/Library/Caches/ (agy/, Google/). All other writes (including the project tree) are blocked at the OS layer.
• Gemini (agy) on non-macOS: sandbox-exec is unavailable. The script REFUSES to run agy unless the caller passes --allow-unsandboxed-gemini, in which case agy runs unsandboxed with a loud warning — the diff safety net below is the only protection in that mode. Or use --codex-only to skip Gemini entirely.

Diff safety net (defense in depth — runs on all platforms)

Before launching either advisor, the script snapshots $WORK_DIR (git: HEAD + status --ignored=traditional + sha256 of tracked + untracked + gitignored files; non-git: find + sha256). After both advisors return, the snapshot is repeated and diffed. The snapshot excludes .council-tmp/ (the script's own response files) and .antigravitycli/ (agy's per-workspace session-metadata directory, created via Apple APIs that bypass sandbox-exec and known not to be a security concern).

Any unauthorized change to the working tree causes the invocation to fail closed with exit code 2 and a [COUNCIL_SAFETY_NET] error banner pointing at the diff. This catches any escape from the sandbox — including writes to gitignored files like .env, dist/, or node_modules/, which the previous --exclude-standard snapshot logic would have missed (Council R1 fix, 2026-05-25).

Historical note (1.2.x ghost-write incident)

Versions 1.2.0 and 1.2.1 documented agy's read-only property as "stdin-EOF + --dangerously-skip-permissions together prevent tool approvals." That reasoning was wrong: agy --help says --dangerously-skip-permissions is "Auto-approve all tool permission requests without prompting" — it grants permission, not withholds it. A 2026-05-24 incident saw agy ghost-write 8 files inside $WORK_DIR during what was supposed to be an advisory Council R1. Upgrade to 1.3.0 or later to get the OS-level sandbox enforcement above.

When you see [COUNCIL_SAFETY_NET] fire

Either (a) an advisor sandbox escape (rare — investigate as a real security issue), or (b) genuine concurrent work in $WORK_DIR by you or another process during the invocation window. Inspect the diff file the banner points at; you'll get response files and a clean before/after snapshot regardless. Do not trust the advisor recommendations until you've audited the diff.

Model and Effort Configuration

Both advisors run at maximum capability:

• Codex: Model auto-selected from ~/.codex/config.toml (override with CODEX_MODEL env var), reasoning effort xhigh (set via ~/.codex/config.toml key model_reasoning_effort = "xhigh")
• Gemini: Runs via agy defaulting to Gemini 3.5 Flash. The session is bounded by setting maxSessionTurns to 100 in the user configuration.

Error Handling

See Section 3c above for detailed failure diagnostics. Key rules:

• Never guess error messages — always read the actual error log files before reporting failures
• Timeout defaults to 5 minutes — suggest increasing COUNCIL_TIMEOUT for large reviews
• Empty responses are caught by the invoke script's validation — the response file will contain the error details from stderr

Learning from the Council (Generalize Knowledge)

After presenting the council synthesis, reflect on what the advisors revealed — gaps, blind spots, better approaches, or project-specific conventions that Claude missed.

Generalize these learnings into CLAUDE.md and AGENTS.md so future agents start with those lessons already loaded. Write down any information that would be useful for a future agent working in this repository, including:

• What the advisors caught that Claude missed
• Why it was missed (root cause, not just symptom)
• The corrected approach or pattern to use next time
• Any project-specific conventions the council surfaced

Template for a council learning entry:

## Council Learning — [date]
- **Insight:** [what the council revealed]
- **Caught by:** Codex / Gemini / both
- **Root cause:** [why this was missed]
- **Lesson:** [concrete rule or pattern for future sessions]

This closes the feedback loop: the council exposes blind spots → learnings become permanent project memory → future sessions start smarter.

When to Convene The Council

• User explicitly asks for it ("ask the council", "get a second opinion", "council review")
• High-stakes architectural decisions affecting multiple systems
• Debugging sessions stuck after multiple failed attempts
• Before finalizing major implementation plans
• Code review of security-sensitive changes