counselors

By Aaron Francis, creator of Faster.dev and Solo.

Fan out prompts to multiple AI coding agents in parallel.

counselors dispatches the same prompt to Claude, Codex, Gemini, Amp, or custom tools simultaneously, collects their responses, and writes everything to a structured output directory.

No MCP servers, no direct API integrations, no complex configuration. It just calls your locally installed CLI tools.

Will this get me banned from my provider?

Counselors only uses providers' first-party CLI tools. It does not call provider APIs directly, it does not extract or reuse auth tokens, and it does not do anything "tricky" behind the scenes. It literally runs the official CLI binaries you already installed, the same way you would from your terminal.

You are still subject to each provider's terms and rate limits. Counselors is just an orchestrator around the CLIs.

Agentic quickstart

Install the CLI yourself first (pick one):

npm (requires Node 20+): npm install -g counselors
Homebrew: brew install aarondfrancis/homebrew-tap/counselors
Standalone binary: curl -fsSL https://github.com/aarondfrancis/counselors/raw/main/install.sh | bash

Then paste this to your AI coding agent:

Run `counselors init --auto` to discover and configure installed AI CLIs. Then run `counselors skill` to see how to create a skill for the counselors CLI.

Your agent will configure available tools and set up the /counselors slash command.

Updating your skill

The recommended skill template changes over time. If you already installed /counselors in your agent system, don’t blindly overwrite it.

Copy/paste this into your AI coding agent:

The counselors CLI has an updated skill template.

1. Run `counselors skill` and capture the full output.
2. Open my existing counselors skill file and compare VERY CAREFULLY for anything that changed.
3. Apply the updates manually; do not blindly overwrite.
4. If you need more context, check the git history for the skill template here:
   https://github.com/aarondfrancis/counselors/commits/main/src/commands/skill.ts

How it works:

You invoke the Counselors skill with a prompt
Your agent gathers context from the codebase
Your agent asks which other agents you want to consult
Counselors fans out to those agents in parallel for independent research
Each agent writes a structured markdown report
Your main agent synthesizes and presents the results

Example: after a big refactor, ask your agents for a second opinion:

/counselors We just completed a major refactor of the authentication module.
Review the changes for edge cases, test gaps, or regressions we might have missed.

Your main agent handles the rest — it gathers relevant code, recent commits, and assembles a detailed prompt before dispatching to the counselors.

Human quickstart

Install the CLI (pick one):

npm (requires Node 20+): npm install -g counselors
Homebrew: brew install aarondfrancis/homebrew-tap/counselors
Standalone binary: curl -fsSL https://github.com/aarondfrancis/counselors/raw/main/install.sh | bash

# Discover installed AI CLIs and create a config
counselors init

# Send a prompt to all configured tools
counselors run "Trace the state management flow in the dashboard and flag any brittleness or stale state bugs"

# Send to specific tools only
counselors run -t claude,codex "Review src/api/ for security issues and missing edge cases"

Supported tools

| Tool | Adapter | Read-Only | Install | |------|---------|-----------|---------| | Claude Code | claude | enforced | docs | | OpenAI Codex | codex | enforced | github | | Gemini CLI | gemini | enforced | github | | Amp CLI | amp | enforced | ampcode.com | | Custom | user-defined | configurable | — |

Commands

`run [prompt]`

Dispatch a prompt to configured tools in parallel.

counselors run "Your prompt here"
counselors run -f prompt.md              # Use a prompt file
echo "prompt" | counselors run           # Read from stdin
counselors run --dry-run "Show plan"     # Preview without executing
counselors run -t opus,opus,opus "Review this"  # Run the same tool multiple times

| Flag | Description | |------|-------------| | -f, --file <path> | Use a prompt file (no wrapping) | | -t, --tools <tools> | Comma-separated tool IDs | | -g, --group <groups> | Comma-separated group name(s) (expands to tool IDs) | | --context <paths> | Gather context from paths (comma-separated, or . for git diff) | | --read-only <level> | strict, best-effort, off (defaults to config readOnly) | | --dry-run | Show what would run without executing | | --json | Output manifest as JSON | | -o, --output-dir <dir> | Base output directory |

`loop [prompt]`

Multi-round dispatch — agents iterate, seeing prior outputs each round.

Each round dispatches to all tools in parallel. Starting from round 2, each agent receives the outputs from all prior rounds, so it can build on previous analysis and avoid repeating findings.

input: user prompt/focus (e.g.: "focus on the auth module", "look at the sidebar component")
  |
  +--> with --preset:
  |      [repo discovery phase] --> [prompt-writing phase] --> execution prompt (includes boilerplate)
  +--> without --preset:
         inline arg prompt:
           default: [repo discovery phase] --> [prompt-writing phase] --> enhanced execution prompt
           opt-out: --no-inline-enhancement (skip discovery/prompt-writing)
         file/stdin prompt: used as provided (discovery/prompt-writing skipped)

all modes: execution boilerplate is always appended

execution prompt
      |
      v
+------------------------------- loop rounds -------------------------------+
| round 1: dispatch to all selected tools in parallel                       |
|          write per-tool outputs + round notes                             |
|                                                                           |
| round N>1: execution prompt + references to prior round outputs           |
|            (new findings, challenge/refine prior findings)                |
|            dispatch in parallel, write outputs + notes                    |
|                                                                           |
| stop when:                                                                |
| - max rounds reached, or                                                  |
| - duration expires, or                                                    |
| - convergence threshold reached, or                                       |
| - user aborts (Ctrl+C after current round)                                |
+---------------------------------------------------------------------------+
      |
      v
final notes + run manifest

Round behavior:

round 1 prompt = base execution prompt


round N prompt = base execution prompt
               // Base execution prompt is amended with...
               + "Prior Round Outputs" section
               + @refs to recent prior tool outputs
               + instruction to avoid duplicate findings, challenge/refine 
                 prior claims, and expand from prior leads

counselors loop "Find and fix test gaps in src/auth/" --rounds 5
counselors loop --duration 30m "Hunt for edge cases"
counselors loop --preset bughunt "src/api" --tools opus,codex
counselors loop --preset hotspots "critical request path" --group smart
counselors loop --list-presets

| Flag | Description | |------|-------------| | --rounds <N> | Number of dispatch rounds (default: 3) | | --duration <time> | Max total duration (e.g. "30m", "1h"). If set without --rounds, runs unlimited rounds until time expires | | --preset <name-or-path> | Use a built-in preset (e.g. "bughunt") or a custom .yml/.yaml preset file | | --list-presets | List built-in presets and exit | | --no-inline-enhancement | For non-preset inline prompts, skip discovery + prompt-writing enhancement |

Plus all run flags: -f, -t, -g, --context, --read-only, --dry-run, --json, -o.

SIGINT handling: First Ctrl+C finishes the current round gracefully. Second Ctrl+C force-exits immediately.

Presets provide domain-specific multi-round workflows.

Built-ins:

bughunt — bugs, edge cases, and missing test coverage
security — exploitable vulnerabilities and high-impact security flaws
invariants — impossible states and state synchronization problems
regression — behavior changes likely to break existing callers/users
contracts — mismatches between API producers and consumers
hotspots — high-impact bottlenecks, including O(n^2)+ patterns

Custom presets (code-grounded):

name: auth-audit
description: |
  Audit authentication and authorization code paths for real issues.
  Ground every claim in repository evidence.
  For each finding, include concrete file paths and explain the exact control/data flow.
  Do not speculate about behavior that is not visible in code.
defaultRounds: 3
defaultReadOnly: bestEffort

counselors loop --preset ./presets/auth-audit.yml "src/auth and middleware"
counselors loop --preset ./presets/auth-audit.yml "session + token flows" --dry-run

Guidelines for "truth of the code" presets:

Write description so findings must cite concrete evidence (file paths, functions, branches, tests).
Require the agent to separate observed behavior from assumptions and call out unknowns explicitly.
Ask for reproducible checks (commands/tests) for each high-confidence claim.
Keep the focus target narrow in the prompt argument (specific dirs, modules, or request paths).

Counselors

Install / Use

README