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:

1. You invoke the Counselors skill with a prompt
2. Your agent gathers context from the codebase
3. Your agent asks which other agents you want to consult
4. Counselors fans out to those agents in parallel for independent research
5. Each agent writes a structured markdown report
6. 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).

mkdir [prompt]

Create a counselors output directory and optionally write prompt.md without dispatching.

If you do not provide a prompt (arg, -f, or stdin), mkdir creates only the containing directory.

Useful when an orchestrating agent wants counselors to own output-dir creation and just return paths.

counselors mkdir --json
counselors mkdir "Review the auth flow for edge cases" --json
echo "prompt" | counselors mkdir --json
cat prompt.md | counselors mkdir --json
counselors mkdir -f prompt.md --json

The JSON output includes: - outputDir - promptFilePath (null when no prompt was provided) - slug - promptSource (none, inline, file, or stdin)

init

Interactive setup wizard. Discovers installed AI CLIs, lets you pick tools and models, runs validation tests.

counselors init          # Interactive
counselors init --auto   # Non-interactive: discover tools, use defaults, output JSON

doctor

Check configuration health — verifies config file, tool binaries, versions, and read-only capabilities.

counselors doctor

upgrade

Detect how counselors was installed and upgrade using the matching method when possible.

Supported: - Homebrew - npm global - pnpm global - yarn global (classic) - Standalone binary installs (safe paths only: ~/.local/bin, ~/bin)

counselors upgrade
counselors upgrade --check        # Show method/version only
counselors upgrade --dry-run      # Show what would run
counselors upgrade --force        # Force standalone self-upgrade outside safe locations

cleanup

Delete run output directories older than a given age. Defaults to older than 1 day and uses your configured output directory (defaults.outputDir).

counselors cleanup
counselors cleanup --dry-run --older-than 7d
counselors cleanup --older-than 36h --yes

config

Print the config file path and the full resolved configuration as JSON.

counselors config

tools

Manage configured tools.

Command	Description
tools discover	Find installed AI CLIs on your system
tools add [tool]	Add a built-in or custom tool
tools remove [tool]	Remove tool(s) — interactive if no argument
tools rename <old> <new>	Rename a tool ID
tools list / ls	List configured tools (-v for full config)
tools test [tools...]	Test tools with a quick "reply OK" prompt

groups

Manage predefined groups of tool IDs for easier reuse.

counselors groups list
counselors groups add smart --tools claude-opus,codex-5.3-xhigh,gemini-3-pro
counselors groups add fast --tools codex-5.3-high,gemini-3-flash
counselors groups add opus-swarm --tools claude-opus,claude-opus,claude-opus
counselors groups remove fast

agent

Print setup and skill installation instructions.

skill

Print a /counselors slash-command template for use inside Claude Code or other agents.

Configuration

Global config

~/.config/counselors/config.json (respects XDG_CONFIG_HOME)

{
  "version": 1,
  "defaults": {
    "timeout": 540,
    "outputDir": "./agents/counselors",
    "readOnly": "bestEffort",
    "maxContextKb": 50,
    "maxParallel": 4
  },
  "tools": {
    "claude": {
      "binary": "/usr/local/bin/claude",
      "adapter": "claude",
      "readOnly": { "level": "enforced" },
      "extraFlags": ["--model", "opus"]
    }
  },
  "groups": {
    "smart": ["claude-opus", "codex-5.3-xhigh", "gemini-3-pro"],
    "fast": ["codex-5.3-high", "gemini-3-flash"],
    "opus-swarm": ["claude-opus", "claude-opus", "claude-opus"]
  }
}

Running the same tool multiple times

If you want multiple independent responses from the same configured tool, just repeat it in --tools (or inside a group). Counselors will automatically fan it out as separate instances.

counselors run -t opus,opus,opus "Review this module for edge cases"

Project config

Place a `.co