Stop Trusting One AI Opinion! counselors Runs 5 Agents in Parallel
Stop Trusting One AI Opinion! counselors Runs 5 Agents in Parallel
What if your AI coding assistant is confidently wrong—and you have no way to know?
Here's a scenario that keeps senior engineers awake: you ask Claude to review a critical authentication refactor. It greenlights everything. You merge. Two days later, production burns because Claude missed a race condition that Gemini would have caught in seconds. The brutal truth? Every AI model has blind spots. Claude hallucinates APIs. Codex misses edge cases. Gemini conflates similar-sounding concepts. And when you're flying solo with one agent, you're betting your entire codebase on a single perspective.
The cost of these blind spots isn't theoretical. In the repository's own examples, Gemini Pro incorrectly claimed that "ghostty-web's built-in Kitty support" could render images—when Claude Opus and Codex correctly identified that the Canvas/WASM build lacks any image rendering paths. One developer, trusting that single opinion, could have wasted 40-80 hours on a doomed implementation.
Enter counselors—the open-source CLI from Aaron Francis that transforms how elite developers leverage AI. Instead of praying one agent gets it right, counselors fans out the same prompt to multiple AI coding agents in parallel, collects their independent responses, and writes structured reports for comparison. Think of it as assembling a council of advisors rather than relying on a single consultant. And the best part? No MCP servers, no API integrations, no infrastructure gymnastics. It simply calls the CLI tools you already have installed.
Ready to stop gambling with your code reviews? Let's dive into why top developers are quietly adopting this pattern—and how you can too.
What is counselors?
counselors is a command-line orchestrator created by Aaron Francis, the developer behind Faster.dev and Solo. Its core mission is elegantly simple: dispatch identical prompts to multiple AI coding agents simultaneously, then structure their responses for easy comparison and synthesis.
Unlike most "multi-agent" tools that parallelize different tasks across git worktrees, counselors pursues a fundamentally different strategy. It sends the same prompt to diverse models and collects their independent perspectives. This "council of advisors" pattern surfaces disagreements, validates consensus, and exposes the blind spots any single agent inevitably carries.
The tool exploded in relevance because AI coding assistants have proliferated rapidly. Claude Code, OpenAI Codex, Gemini CLI, Amp—each brings distinct strengths. Claude excels at architectural reasoning. Codex dominates implementation detail. Gemini offers broad knowledge. But switching between them manually is friction-heavy. counselors eliminates that friction entirely.
Critically, counselors operates through first-party CLI tools only. It doesn't call provider APIs directly, doesn't extract auth tokens, and doesn't perform any "tricky" orchestration. It literally executes the official binaries you installed—claude, codex, gemini, amp—the same way you would from your terminal. This architectural choice matters: you're still subject to each provider's terms and rate limits, but you avoid the compliance gray zones of unofficial API wrappers.
The project is built with TypeScript/ESM, distributed via npm and Homebrew, and requires only Node 20+. It's lightweight, fast, and designed for both human-driven workflows and agentic orchestration—where your primary AI agent can invoke counselors as a skill via slash commands.
Key Features That Make counselors Insanely Powerful
counselors isn't just a "run multiple AIs" wrapper. Its feature set reveals deep thinking about how developers actually work with AI assistants.
True Parallel Fan-Out with Structured Outputs
When you execute counselors run, the tool simultaneously launches all configured agents against your prompt. Each agent operates independently—no shared state, no cross-contamination. Results land in a predictable directory structure: prompt.md, run.json manifest, per-tool response files, and stderr captures. For multi-round loop executions, each round gets its own subdirectory with augmented prompts referencing prior outputs.
Zero-Configuration Agent Discovery
Run counselors init --auto and the tool automatically detects which AI CLIs exist on your system. No manual API key juggling. No config file archaeology. It validates binaries, tests connectivity, and produces a working configuration in seconds.
Read-Only Sandboxing by Default
Security-conscious teams will appreciate the three-tier read-only system: enforced (tool is sandboxed to read operations), bestEffort (tool is asked to avoid writes), and none (full access). By default, counselors operates in bestEffort mode—agents can review your code without risking modifications. For critical audits, strict mode ensures only tools with guaranteed read-only support participate.
Multi-Round Iterative Analysis with loop
The loop command is where counselors transcends simple parallelization. Each round dispatches to all tools with access to prior rounds' outputs. Agents build on previous findings, challenge earlier claims, and explore deeper. Built-in presets like bughunt, security, invariants, regression, contracts, and hotspots provide domain-specific workflows. Set --rounds 5 or --duration 30m and let agents iteratively converge on comprehensive analysis.
Agentic Skill Integration
The /counselors slash command installs directly into Claude Code or compatible agents. Your primary agent gathers context, selects which other agents to consult, dispatches via counselors, and synthesizes results—all without you leaving your editor. This isn't just convenience; it's a new paradigm where agents orchestrate agents.
Atomic, Secure Operations
Config writes use temp+rename with 0o600 permissions. Child processes receive only allowlisted environment variables—no full process.env leaks. Tool IDs are validated against [a-zA-Z0-9._-] to prevent path traversal. No shell execution: all spawning uses execFile/spawn without shell: true.
Use Cases Where counselors Absolutely Shines
Cross-Model Validation for Critical Refactors
Before merging that 1200-line module split, run counselors across Claude, Gemini, and Codex. The repository documents a real case where all three agreed on splitting a detection module into a directory structure, replacing boolean fields with lazy file checks, and avoiding premature rule engine abstraction. But Codex alone caught two bugs in dedup logic and orchestration-skip behavior that the others missed. Consensus gives you confidence; disagreement gives you investigation targets.
Security Audits with Defense in Depth
Use counselors loop --preset security for multi-round vulnerability hunting. Round 1 establishes the attack surface. Round 2 challenges round 1's findings and probes deeper. Round 3 validates exploitability. Each agent independently builds on prior work without duplication. The structured output lets your security team trace every claim to specific file paths and control flows.
Architecture Decisions with Disagreement Exposure
The ghostty-web examples reveal how models diverge on implementation strategy. For escape-to-dismiss in stacked modals, Codex proposed a parallel string array alongside the existing Set; Gemini suggested replacing the Set entirely; Amp recommended a complex global dispatcher with handler registry. Seeing these alternatives side-by-side prevents premature commitment to suboptimal designs.
API Upgrade Risk Assessment
Before that major dependency bump, counselors surfaces hidden breaking changes. In the ghostty-web 0.3.0 → 0.4.0 upgrade analysis, all three agents agreed on five critical concerns—including a high-risk renderer.metrics hack—while independently verifying that a WASM bug was likely fixed. The synthesizing agent could proceed with confidence on consensus items and heightened scrutiny on the metrics hack.
Test Gap Hunting with Progressive Deepening
counselors loop --preset bughunt --scope src/auth/ --rounds 3 creates a systematic excavation: round 1 maps the test landscape, round 2 hunts edge cases round 1 missed, round 3 goes deeper on remaining uncovered territory. Each agent reads prior reports to avoid repetition and build on leads. This mimics how senior engineers actually review code—iteratively, with expanding scope—but automates the parallelization.
Step-by-Step Installation & Setup Guide
Getting counselors running takes under two minutes. Choose your installation path:
Option 1: npm (requires Node 20+)
npm install -g counselors
Option 2: Homebrew
brew install aarondfrancis/homebrew-tap/counselors
Option 3: Standalone Binary
curl -fsSL https://github.com/aarondfrancis/counselors/raw/main/install.sh | bash
Initial Configuration
Once installed, discover and configure your AI tools:
# Interactive setup wizard—discovers installed CLIs, lets you pick tools and models
counselors init
# Or non-interactive: auto-discover, use defaults, output JSON
counselors init --auto
The init command detects which of Claude Code, OpenAI Codex, Gemini CLI, and Amp CLI exist on your $PATH. It validates each binary, tests basic connectivity, and writes your ~/.config/counselors/config.json.
Verify Your Setup
# Check configuration health—verifies config file, tool binaries, versions, read-only capabilities
counselors doctor
# List configured tools with full details
counselors tools list -v
# Test tools with a quick "reply OK" prompt
counselors tools test
Project-Level Overrides
For per-project customization, create .counselors.json in your project root:
{
"defaults": {
"outputDir": "./ai-output",
"readOnly": "enforced"
}
}
Security note: Project configs can only override defaults, never inject new tools. This prevents malicious repositories from executing arbitrary binaries.
Upgrade When Needed
# Auto-detect installation method and upgrade
counselors upgrade
# Preview without executing
counselors upgrade --dry-run
Supported upgrade paths: Homebrew, npm global, pnpm global, yarn global (classic), and standalone binaries in safe paths (~/.local/bin, ~/bin).
REAL Code Examples from the Repository
Example 1: Basic Parallel Dispatch with run
The simplest counselors invocation fans out a prompt to all configured tools:
# Send a prompt to all configured AI agents simultaneously
counselors run "Trace the state management flow in the dashboard and flag any brittleness or stale state bugs"
# Target specific tools only—here, Claude and Codex for security review
counselors run -t claude,codex "Review src/api/ for security issues and missing edge cases"
# Read prompt from a file—useful for complex, multi-line prompts
counselors run -f prompt.md
# Pipe prompt from stdin for shell scripting integration
echo "prompt" | counselors run
# Preview execution plan without running—verify your setup before burning API credits
counselors run --dry-run "Show plan"
# Run the same tool multiple times for independent perspectives
counselors run -t opus,opus,opus "Review this module for edge cases"
What's happening here: The -t flag selects specific tools by their configured IDs. The --dry-run flag is essential for workflow validation—it shows exactly which commands would execute without consuming API quota. Running the same tool multiple times (opus,opus,opus) exploits statistical diversity: even identical models with temperature > 0 produce varied responses, and you get multiple independent reasoning paths.
Example 2: Multi-Round Iterative Analysis with loop
For deep investigations, loop enables progressive refinement across rounds:
# Hunt test gaps with 5 rounds of progressive deepening
counselors loop "Find and fix test gaps in src/auth/" --rounds 5
# Time-bounded analysis—run unlimited rounds until 30 minutes expire
counselors loop --duration 30m "Hunt for edge cases"
# Use built-in preset for bug hunting with specific tools
counselors loop --preset bughunt "src/api" --tools opus,codex
# Apply hotspot detection to critical request paths
counselors loop --preset hotspots "critical request path" --group smart
# List all available presets before choosing
counselors loop --list-presets
The loop mechanics are sophisticated: Round 1 dispatches the base execution prompt to all selected tools. Starting round 2, each agent receives the base prompt plus a "Prior Round Outputs" section with @refs to recent tool outputs. They're explicitly instructed to avoid duplicate findings, challenge or refine prior claims, and expand from prior leads. This creates genuine iterative analysis—not just repeated execution.
Example 3: Custom Preset for Domain-Specific Audits
Built-in presets cover common scenarios, but custom presets ground analysis in your specific domain:
# File: ./presets/auth-audit.yml
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
# Apply custom preset to specific code areas
counselors loop --preset ./presets/auth-audit.yml "src/auth and middleware"
# Dry-run to validate preset application before execution
counselors loop --preset ./presets/auth-audit.yml "session + token flows" --dry-run
Why this matters: The description field becomes part of every agent's prompt. By requiring concrete evidence, separating observations from assumptions, and demanding reproducible checks, you transform generic AI opinions into auditable engineering analysis. The defaultReadOnly: bestEffort balances safety with capability—agents can read test files to verify claims without modifying source.
Example 4: Configuration and Tool Management
# Print full resolved configuration as JSON—debug your setup
counselors config
# Discover new AI CLIs installed after initial setup
counselors tools discover
# Add a custom tool beyond the built-in adapters
counselors tools add my-custom-llm
# Create logical groups for common tool combinations
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
# Use group shorthand in commands
counselors run -g smart "Complex architectural review"
Example 5: Agentic Skill Integration
For AI-native workflows, install the /counselors slash command:
# Print the skill template for your agent
counselors skill
# Print full agent setup instructions
counselors agent
The skill template enables this workflow inside Claude Code:
/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.
Behind the scenes: Your primary agent gathers relevant code and recent commits, assembles a detailed prompt, asks which other agents to consult, dispatches via counselors, then synthesizes the independent responses into a unified report. You're not copy-pasting between chat windows—you're orchestrating a multi-agent council from a single command.
Advanced Usage & Best Practices
Exploit Model Diversity Strategically
Don't just run multiple instances of your favorite model. The real power emerges from qualitative diversity: Claude's architectural depth, Codex's implementation precision, Gemini's broad knowledge, Amp's specific strengths. When models disagree, you learn something. When they agree, you gain confidence.
Master the Preset System
Built-in presets encode domain expertise. bughunt focuses on bugs, edge cases, and missing coverage. security hunts exploitable vulnerabilities. invariants finds impossible states. hotspots identifies O(n²)+ complexity. For recurring analysis types, invest in custom presets with strict "truth of the code" guidelines—require file path citations, separate observations from assumptions, demand reproducible checks.
Use --dry-run Religiously
Before burning API credits on a 5-round loop with 4 tools, preview the execution. counselors run --dry-run and counselors loop --dry-run show exactly which commands would execute, which tools participate, and where outputs land. This is especially critical when experimenting with custom presets or group configurations.
Structure Output for Synthesis
counselors writes predictable output directories. Build tooling that reads run.json manifests, parses per-tool .md files, and surfaces disagreements automatically. The JSON manifest includes status, timing, and cost data—feed this into your CI dashboards to track AI-assisted review coverage.
Handle SIGINT Gracefully
Long-running loops respect your interruptions. First Ctrl+C finishes the current round cleanly and writes outputs. Second Ctrl+C force-exits immediately. This prevents losing partial analysis when you realize you've asked the wrong question.
Clean Up Old Runs
# Delete outputs older than default (1 day)
counselors cleanup
# Preview cleanup scope
counselors cleanup --dry-run --older-than 7d
# Auto-confirm deletion
counselors cleanup --older-than 36h --yes
Comparison with Alternatives
| Tool | Parallelization Strategy | Infrastructure | Read-Only Default | Agentic Integration | Key Differentiator |
|---|---|---|---|---|---|
| counselors | Same prompt to multiple agents | None—uses local CLIs | Yes (bestEffort) |
Native /counselors skill |
Cross-model consensus/disagreement |
| Uzi | Different tasks per agent | Git worktrees | No | Limited | Throughput for parallel tasks |
| FleetCode | Different tasks per agent | Git worktrees | No | Limited | Multi-agent task splitting |
| AI Fleet | Different tasks per agent | Containers | No | Limited | Containerized agent isolation |
| Superset | Different tasks per agent | Infrastructure | No | Limited | Managed multi-agent platform |
The fundamental distinction: counselors is a quality tool, not a throughput tool. Others parallelize work distribution—each agent handles a separate file or feature. counselors parallelizes perspective—each agent examines the same problem through different model architectures and training data. You're not shipping faster; you're shipping better.
Additionally, counselors requires zero infrastructure. No git worktrees, no containers, no managed platforms. It calls your existing CLI binaries and writes markdown↗ Smart Converter files. This simplicity makes it viable for individual developers, not just teams with DevOps↗ Bright Coding Blog support.
FAQ
Will counselors get me banned from AI providers?
No. counselors only invokes providers' first-party CLI tools—the same claude, codex, gemini, and amp binaries you run manually. It doesn't call APIs directly, extract auth tokens, or perform any "tricky" orchestration. You're still subject to each provider's terms and rate limits, but counselors itself is just a local process orchestrator.
Do I need API keys or MCP servers?
No API keys, no MCP servers, no complex configuration. counselors calls the CLI tools you've already installed and authenticated. If claude works in your terminal, it works with counselors.
Can I run the same model multiple times?
Absolutely. counselors run -t opus,opus,opus "Review this" dispatches three independent Claude Opus instances. Even with identical parameters, temperature sampling produces varied responses. More importantly, you get multiple independent reasoning paths through the same problem space.
How does loop differ from run?
run is single-round parallel dispatch—fire all agents once, collect responses. loop is multi-round iterative analysis where each subsequent round feeds prior outputs back to agents. They build on findings, challenge earlier claims, and explore deeper. Use run for quick consensus checks; use loop for thorough investigations.
What's the output structure?
Each run creates a timestamped directory with prompt.md, run.json manifest, per-tool response files, and stderr captures. For loop, each round gets a subdirectory. This structured output enables programmatic synthesis, diffing, and archival.
Can I customize which tools participate?
Yes. Use -t for specific tools, -g for predefined groups, or configure defaults in ~/.config/counselors/config.json. Groups like smart (premium models) and fast (cheaper models) streamline common selection patterns.
Is there a risk of agents modifying my code?
counselors defaults to bestEffort read-only mode, and many tools support enforced read-only sandboxing. However, the Amp deep model uses Bash for file reading, which is write-capable—counselors injects read-only instructions, but this is best-effort. For safety-critical audits, use strict read-only mode or prefer amp-smart.
Conclusion
The era of trusting single AI opinions is ending. As codebases grow more complex and AI assistants more capable, the bottleneck shifts from "can AI help?" to "can I trust this specific answer?" counselors solves this trust problem not with more infrastructure, but with elegant parallelization of perspectives.
Aaron Francis has built something genuinely differentiated: a tool that respects your existing workflow, requires zero new infrastructure, and delivers immediate value through cross-model validation. The real-world examples in the repository—where Gemini conflated native and web Ghostty capabilities, where Codex alone caught dedup bugs, where all three models converged on high-risk upgrade concerns—demonstrate that this isn't theoretical. Model disagreement is a feature, not a bug, and counselors makes it exploitable.
My take? If you're making architectural decisions, reviewing security-critical code, or validating major refactors without multiple AI perspectives, you're flying blind in a fog that counselors clears instantly. The CLI-first approach, read-only defaults, and agentic skill integration show product thinking that understands how elite developers actually work.
Stop gambling with single opinions. Install counselors today, run counselors init --auto, and experience what a council of advisors actually feels like. Your future self—reviewing that merged PR with confidence—will thank you.
npm install -g counselors
counselors init --auto
counselors run "Review my most critical code with fresh eyes"
Outils recommandés
Tags
Explore on the BrightCoding network
Hand-picked resources from our other sites.
wuyoscar/gpt_image_2_skill: Curated GPT Image 2 Prompts, Agent Skills & CLI
wuyoscar/gpt_image_2_skill is an open-source Python project combining 162+ curated GPT Image 2 prompts, installable agent skills for Claude Code/Codex/OpenClaw,...
moazbuilds/CodeMachine-CLI: Orchestrate AI Coding Agents into Repeatable Workflows
moazbuilds/CodeMachine-CLI is an open-source TypeScript tool with 2,509 GitHub stars that orchestrates AI coding agents into repeatable, long-running workflows...
alibaba-flyai/flyai-skill: Travel Search Inside Claude Code
FlyAI skill embeds real-time flight, hotel, and attraction search into Claude Code and OpenClaw via natural language commands. Zero-config startup, eight search...
Continuez votre lecture
Why Alexandrie is the Ultimate Markdown Note-Taking App
Why CrossPaste is the Ultimate Game Changer for Clipboard Management
Why Chandra is the Ultimate OCR Tool for Handwriting and Tables
Stop Coding Alone: OPC-Skills Gives Your AI Agent Superpowers
Commentaires 0
Aucun commentaire pour l'instant. Soyez le premier à réagir !