A modular configuration system for Claude Code CLI. Includes an automated loop driver, multi-agent parallel orchestration via git worktrees, custom slash commands, multi-model council automation, MCP browser bridge, and portfolio governance.
- Automated Loop Driver - Run Claude Code in autonomous loops with session continuity, budget enforcement, stagnation detection, and model-aware scaling (Sonnet recommended — near Opus quality at lower cost)
- Custom Slash Commands - 31 reusable commands for research, planning, code review, testing, and deployment workflows
- Orchestrator Suite - Three orchestrator commands for greenfield bootstrapping (
/orchestrator-new), single-loop execution (/orchestrator), and multi-agent parallel work (/orchestrator-multi) - Frontend E2E Testing - 7-tier browser-based testing with visual/UX quality checks via MCP Browser Bridge
- Council Automation - Multi-model queries via Perplexity (GPT, Claude, Gemini) with Opus synthesis
- MCP Browser Bridge - Chrome extension bridge for browser automation through Claude Code
- Portfolio Governance - Project tier system with phase restrictions and complexity budgets
- Perplexity Integration - Playwright-based research queries using your Perplexity Pro subscription ($0/query)
~/.claude/
├── CLAUDE.md.example # Global Claude Code instructions (template)
├── LICENSE # MIT License
├── NOTICE # Trademark disclaimers
├── README.md # This file
├── perplexity-selectors.json # Perplexity UI selectors for automation
│
├── automated-loop/ # Automated Claude Code loop driver
│ ├── loop_driver.py # Main entry point
│ ├── config.py # Pydantic config with model-aware scaling
│ ├── ndjson_parser.py # Claude CLI NDJSON stream parser
│ ├── research_bridge.py # Perplexity research via Playwright
│ ├── state_tracker.py # Workflow state persistence + budget
│ ├── log_redactor.py # API key scrubbing from logs
│ ├── loop_driver.ps1 # PowerShell wrapper
│ └── tests/ # 377 pytest tests
│
├── agents/ # Agent definitions (Task tool subagent types)
│ ├── orchestrator.md # Single-loop orchestrator agent
│ ├── orchestrator-multi.md # Multi-agent parallel orchestrator agent
│ ├── architect.md # System design specialist
│ ├── backend.md # API development agent
│ ├── frontend.md # UI development agent
│ ├── database.md # Database specialist agent
│ ├── devops.md # CI/CD and infrastructure agent
│ ├── testing.md # Test development agent
│ └── research.md # Research specialist agent
│
├── hooks/ # PreToolUse / session hooks
│ ├── inject-time.py # Time sync injection
│ └── orchestrator-guard.py # Orchestrator mode path guard (supports multi-agent worktrees)
│
├── commands/ # Custom slash commands (31 total)
│ ├── orchestrator-new.md # Greenfield project bootstrapper
│ ├── orchestrator.md # Single-loop task execution
│ ├── orchestrator-multi.md # Multi-agent parallel orchestration
│ ├── research-perplexity.md # Deep research via Perplexity
│ ├── frontend-e2e.md # Frontend E2E with visual/UX testing
│ ├── smart-plan.md # Multi-phase project planning
│ ├── council-refine.md # Multi-model plan refinement
│ ├── export-to-council.md # Export session for council review
│ ├── creative-research.md # 3-stage creative feature discovery
│ ├── fix-issue.md # GitHub issue resolution
│ ├── implement.md # Feature implementation
│ ├── review.md # Code review
│ ├── handoff.md # Agent handoff
│ ├── init.md # Project bootstrap & health check
│ ├── solve-perplexity.md # Iterative problem solver via Perplexity
│ ├── stub-check.md # Implementation completeness audit
│ ├── spreadsheet-audit.md # Excel spreadsheet audit
│ ├── gba-build.md # GBA game builder
│ ├── gba-build-develop.md # Self-driving GBA development pipeline
│ ├── gba-test.md # GBA integration test runner
│ ├── gba-smoke.md # GBA emulator smoke test
│ ├── gba-ai-full.md # GBA AI behavior regression test
│ ├── nds-build.md # NDS game builder
│ ├── nds-test.md # NDS emulator test runner
│ ├── profiles/ # Game profile configs
│ │ ├── brain-attic.md
│ │ └── pokemon-embergold.md
│ └── ... # + 8 more (research, council, perplexity commands)
│
├── council-automation/ # Multi-model council system
│ ├── council_browser.py # Playwright-based Perplexity automation
│ ├── council_config.py # Council configuration
│ ├── council_query.py # Query orchestration
│ ├── session_context.py # Session/cookie management
│ ├── refresh_session.py # Session cookie refresh script
│ └── synthesis_prompt.md # Opus synthesis prompt template
│
├── mcp-servers/
│ └── browser-bridge/ # MCP Browser Bridge server
│ ├── server.js # MCP protocol handler
│ ├── extension/ # Chrome extension (load unpacked)
│ │ ├── manifest.json # MV3 manifest
│ │ ├── background.js # Service worker + WebSocket client
│ │ ├── content.js # DOM interaction helpers
│ │ └── popup.html # Connection status popup
│ ├── lib/ # Server modules
│ │ ├── websocket-bridge.js
│ │ ├── context-manager.js
│ │ ├── rate-limiter.js
│ │ └── ...
│ └── test-*.js # Integration tests
│
└── portfolio/ # Portfolio governance
├── PORTFOLIO.md.example # Project registry + tier system (template)
├── DECISIONS.md # Architecture decision records
└── PROJECT_TEMPLATE.md # New project template
┌──────────────────────────────────────────────────────────┐
│ Claude Code CLI │
│ (claude -p --stream-json) │
├──────────────┬────────────────────────┬───────────────────┤
│ │ │ │
│ ┌──────────▼──────────┐ ┌────────▼────────┐ │
│ │ Loop Driver │ │ Slash Commands │ │
│ │ (loop_driver.py) │ │ (commands/*.md) │ │
│ │ │ └────────┬────────┘ │
│ │ ┌──────────────┐ │ │ │
│ │ │ NDJSON Parser │ │ ┌────────▼────────┐ │
│ │ └──────┬───────┘ │ │ Council Automation│ │
│ │ │ │ │ (Playwright → │ │
│ │ ┌──────▼───────┐ │ │ Perplexity) │ │
│ │ │ State Tracker │ │ └─────────────────┘ │
│ │ │ + Budget │ │ │
│ │ └──────┬───────┘ │ ┌─────────────────┐ │
│ │ │ │ │ MCP Browser Bridge│ │
│ │ ┌──────▼───────┐ │ │ (WebSocket ↔ │ │
│ │ │Research Bridge│ │ │ Chrome Extension)│ │
│ │ └──────────────┘ │ └─────────────────┘ │
│ └──────────────────────┘ │
└──────────────────────────────────────────────────────────┘
- Claude Code CLI installed and authenticated
- Python 3.11+ (for automated loop and council automation)
- Node.js 18+ (for MCP browser bridge)
- Perplexity Pro subscription (for research features, optional)
# Clone to ~/.claude (or your Claude Code config directory)
git clone https://github.com/intellegix/intellegix-code-agent-toolkit.git ~/.claude
# Install automated loop dependencies
cd ~/.claude/automated-loop
pip install -r requirements.txt
# Install council automation dependencies
cd ~/.claude/council-automation
pip install -r requirements.txt
# Install MCP browser bridge dependencies
cd ~/.claude/mcp-servers/browser-bridge
npm installcd ~/.claude/automated-loop
# Smoke test (1 iteration, safe defaults)
python loop_driver.py --smoke-test --verbose
# Run against a project
python loop_driver.py --project /path/to/your/project --max-iterations 10 --verbose
# With model selection (sonnet recommended, opus for complex architecture only)
python loop_driver.py --project /path/to/project --model sonnet --timeout 600 --verboseCouncil, research, and labs features use Perplexity browser automation. Setup is required before first use.
| Feature | Subscription |
|---|---|
/council (multi-model) |
Perplexity Max |
/research (deep research) |
Perplexity Pro or Max |
/labs (experimental) |
Perplexity Pro or Max |
The toolkit types /council, /research, and /labs into Perplexity's input to activate modes. These must exist as Perplexity shortcuts:
- Go to perplexity.ai/settings > Shortcuts
- Create three custom shortcuts:
/council— Activates Model Council (queries 3 models simultaneously)/research— Activates Deep Research mode/labs— Activates Labs (experimental) mode
The toolkit uses your browser login session — no Perplexity API key needed ($0/query).
- Install the MCP Browser Bridge Chrome extension included in this repo:
- Open
chrome://extensions→ enable Developer mode → Load unpacked → select~/.claude/mcp-servers/browser-bridge/extension/ - See MCP Browser Bridge below for full setup (server + Claude Code config)
- Note: Anthropic's official "Claude in Chrome" extension is still in beta and has known Bun runtime issues on Windows that prevent the native host from connecting. The team is actively working on fixes. This toolkit uses its own extension to avoid those issues.
- Open
- Log into perplexity.ai in Chrome
- From Claude Code, run:
/cache-perplexity-session - Session saves to
~/.claude/config/perplexity-session.json(24h TTL)
Refresh expired sessions:
cd ~/.claude/council-automation
python refresh_session.py # headful refresh (~6s)
python refresh_session.py --validate # refresh + test queryRuns Claude Code CLI in autonomous loops with NDJSON streaming, session continuity, and safety guardrails.
# Basic usage
python loop_driver.py --project . --max-iterations 50
# With budget limit
python loop_driver.py --project . --max-iterations 50 --max-cost 25.00
# Dry run (no Claude invocation)
python loop_driver.py --project . --dry-run --verbose
# Run tests
pytest tests/ -vExit codes: 0 = complete, 1 = max iterations, 2 = budget exceeded, 3 = stagnation
Key features:
- Model-aware scaling (Sonnet recommended; Opus: 2x timeout, 25-turn cap)
- Model fallback (Opus→Sonnet after 2 consecutive timeouts, reverts on productive iteration)
- Exponential backoff with timeout cooldown
- Session continuity via
--resume - Stagnation detection with two-strike system
- Budget enforcement per-iteration and cumulative
The loop driver is autonomous, but the human operator remains in control. Claude Code is your control plane — you launch the loop, monitor its progress, and steer the project between runs.
Run loop_driver.py from a Claude Code session or a separate terminal. The loop spawns Claude Code CLI as a worker:
claude -p "<prompt>" --output-format stream-json --dangerously-skip-permissions --resume <sessionId>
Each iteration streams NDJSON events (init, assistant, result, system). The driver extracts cost, turns, and completion markers automatically.
The loop writes state to <project>/.workflow/:
| File | Purpose |
|---|---|
state.json |
Full cycle history — iteration count, cost per cycle, turns, session IDs |
trace.jsonl |
Append-only event log (loop_start, claude_invoke, claude_complete, research_start, timeout_detected, model_fallback, stagnation_exit, etc.) |
metrics_summary.json |
Written on every exit — total cost, iterations, turns, error count |
research_result.md |
Latest Perplexity research response |
Review these between runs (or during, via tail -f trace.jsonl) to decide whether the loop is making progress.
The loop exits automatically on:
PROJECT_COMPLETEmarker in output → exit 0- Max iterations reached → exit 1
- Budget exceeded → exit 2
- Stagnation detected → exit 3
Between runs, read the loop's output and state.json to audit what was accomplished. If more phases remain, restart the loop. If the work needs course correction, revise CLAUDE.md first.
The loop's default prompt instructs Claude to "Read CLAUDE.md first" — it's the project's source of truth for what to build. The operator edits CLAUDE.md between loop runs to add/remove/reorder phases, update status markers, or change priorities.
The loop never modifies CLAUDE.md itself — the human retains full editorial control. This is how you steer multi-session projects: update CLAUDE.md, restart the loop.
Concurrent Perplexity Research Queries
Concurrent research queries now work in most cases, thanks to a 3-layer fix:
- Process cleanup (
council_browser.py): Snapshots Chrome PIDs before/after browser launch. Afterplaywright.stop(), any survivingchrome.exeprocesses are force-killed after a 1-second grace period, preventing orphaned instances from blocking subsequent queries. - Profile isolation: Each browser session gets a unique temp user-data-dir (
tempfile.mkdtemp(prefix="council_np_")), eliminating ChromeSingletonLockconflicts. Node.js subprocess calls useexecFileAsyncfor non-blocking concurrent execution. - DevTools protocol coordination:
/research-perplexity,/labs-perplexity, and/export-to-councilcommands include a mandatory "Close Browser Bridge Sessions" step before launching Playwright, preventing DevTools Protocol collisions between browser-bridge and Playwright.
The SessionSemaphore limits concurrency to 3 browser slots. Very high concurrency (4+ simultaneous queries) may still hit Perplexity's own session limits when using the same account.
Research Query Retries
Failed research queries automatically retry up to 3 times with exponential backoff:
- Delay schedule: ~1s → ~2s → ~4s (base 1.0s × 2^attempt, with random jitter ±50%, capped at 30s)
- Retryable errors: timeouts, Playwright errors, parse failures
- A circuit breaker trips after 5 consecutive failures, pausing research for 120s before allowing retries
Transient Perplexity/Cloudflare issues are handled automatically — the loop continues even if research fails.
Three commands for managing projects at different scales. All three enforce role separation — the orchestrator writes CLAUDE.md instructions and launches loops, never touching source code directly.
| Command | Use Case |
|---|---|
/orchestrator-new |
Greenfield projects — idea → Perplexity research (2 passes) → BLUEPRINT.md → routes to single or multi |
/orchestrator |
Single-loop execution — task → research → CLAUDE.md → loop_driver.py |
/orchestrator-multi |
Multi-agent parallel — task → Appropriateness Gate → research → git worktrees → parallel agents |
# Greenfield: bootstrap a new project from an idea
/orchestrator-new Build a CLI tool that converts CSV to JSON with streaming support
# Single-loop: execute a task against an existing project
/orchestrator C:\Projects\my-app Add user authentication
# Multi-agent: parallelize work across git worktrees
/orchestrator-multi C:\Projects\my-app Refactor auth, add tests, update docs
# Status / deactivate
/orchestrator status
/orchestrator offAll three orchestrators run /research-perplexity before writing agent instructions, providing research-informed CLAUDE.md files. /orchestrator-new runs two research passes: one for technology landscape and one for architecture decisions.
- Sentinel file: Activation creates
.workflow/orchestrator-mode.jsonin the target project (24-hour expiration for crash recovery) - PreToolUse hook:
~/.claude/hooks/orchestrator-guard.pyfires on every Read/Edit/Write/Grep/Glob/Bash call. If a sentinel is active, it blocks access to source code files while allowing CLAUDE.md, BLUEPRINT.md, markdown, and.workflow/files - Workflow phases: PLANNING (gather context, write CLAUDE.md) → LAUNCHING (start loop_driver.py) → MONITORING (10-min checks) → REPORTING (summarize results)
- Persistent mode: Stays active until
/orchestrator off— supports multiple sequential tasks without reactivation - Handoff protocol: Uses
## Project Genesismarker in CLAUDE.md, BLUEPRINT.md for architecture, and a 3-file handoff package for agent transitions
{
"active": true,
"started": "2026-02-24T14:00:00",
"expires": "2026-02-25T14:00:00",
"project": "C:\\Projects\\my-app",
"orchestrator_cwd": "C:\\Users\\...\\automated claude"
}The hook is fail-open: if the sentinel is missing, expired, or malformed, all operations are allowed. Normal (non-orchestrator) sessions have zero overhead — the hook exits immediately when no sentinel is found.
The /frontend-e2e command runs comprehensive browser-based end-to-end tests using the MCP Browser Bridge. Tests are organized into 7 tiers:
| Tier | Focus |
|---|---|
| T1 Universal | Page loads, content renders, no console errors |
| T1.5 Accessibility | ARIA labels, focus management, color contrast |
| T1.7 Visual/UX | Layout consistency, visual hierarchy, spacing |
| T2 Navigation | Links, routing, back/forward behavior |
| T3 Responsive | Mobile, tablet, desktop breakpoints |
| T4 Interactive | Forms, buttons, dynamic content, state management |
| T5 Performance | Load times, resource sizes, paint metrics |
Each tier produces a pass/fail report with screenshots for failures. Run against any frontend project with localhost or a deployed URL.
Place in ~/.claude/commands/ and invoke from Claude Code with /<command-name>.
Orchestrator Suite
| Command | Description |
|---|---|
/orchestrator-new |
Greenfield project bootstrapper with Perplexity research |
/orchestrator |
Single-loop task execution with research-informed CLAUDE.md |
/orchestrator-multi |
Multi-agent parallel orchestration via git worktrees |
Research & Council
| Command | Description |
|---|---|
/research-perplexity |
Deep research via Perplexity (mandatory context preamble) |
/export-to-council |
Multi-model council analysis |
/council-refine |
Multi-model plan refinement with Opus synthesis |
/council-extract |
Extract council response to markdown |
/creative-research |
3-stage creative feature discovery |
/solve-perplexity |
Iterative problem solver (Tier 2.5 escalation) |
/labs-perplexity |
Labs query via Perplexity |
/automate-perplexity |
Unified Perplexity automation |
/cache-perplexity-session |
Refresh Perplexity session cookies |
/ensure-space |
Add Perplexity thread to project space |
Development Workflow
| Command | Description |
|---|---|
/smart-plan |
Multi-phase project planning |
/implement |
Feature implementation |
/fix-issue |
GitHub issue resolution |
/review |
Code review |
/init |
Project bootstrap & health check |
/stub-check |
3-phase implementation completeness audit (research recon ∥ local scan ∥ research validation) |
/handoff |
Agent handoff documentation |
/portfolio-status |
Portfolio-wide status review |
/spreadsheet-audit |
Excel spreadsheet audit |
Testing
| Command | Description |
|---|---|
/frontend-e2e |
Frontend E2E with visual/UX quality checks |
/gba-build |
GBA game builder |
/gba-build-develop |
Self-driving GBA development pipeline |
/gba-test |
GBA integration test runner |
/gba-smoke |
GBA emulator smoke test |
/gba-ai-full |
GBA AI behavior regression test |
/nds-build |
NDS game builder |
/nds-test |
NDS emulator test runner |
Legacy
| Command | Description |
|---|---|
/research |
Deep research (legacy) |
Create a markdown file in ~/.claude/commands/ — Claude Code auto-discovers all .md files in this directory. No YAML frontmatter needed; the file is pure markdown.
Use $ARGUMENTS as a placeholder for whatever the user types after the command name:
# Explain Code
Explain the following code in detail: $ARGUMENTS
## Instructions
- Identify the language and framework
- Describe the overall purpose
- Walk through the logic step by step
- Note any potential issues or improvementsSave this as ~/.claude/commands/explain.md, then invoke it from Claude Code:
/explain src/utils/parser.py
The $ARGUMENTS variable is replaced with src/utils/parser.py at invocation time.
Queries multiple AI models through Perplexity and synthesizes results with Opus.
# Setup: cache your Perplexity login session
# (run /cache-perplexity-session from Claude Code)
# Direct CLI usage
cd ~/.claude/council-automation
python council_browser.py --headful --perplexity-mode research "your query here"WebSocket bridge between Claude Code CLI and Chrome. Both the server and extension are required.
- Open
chrome://extensionsin Chrome - Enable Developer mode (top-right toggle)
- Click Load unpacked → select
~/.claude/mcp-servers/browser-bridge/extension/ - Pin the extension — popup shows connection status (green = connected)
cd ~/.claude/mcp-servers/browser-bridge
npm install # first time only
npm startThe extension auto-connects to ws://127.0.0.1:8765.
MCP servers are configured in ~/.claude/mcp.json (global) or .mcp.json (project-level), not in settings.json.
{
"mcpServers": {
"browser-bridge": {
"command": "node",
"args": ["C:\\Users\\YourName\\.claude\\mcp-servers\\browser-bridge\\server.js"]
}
}
}A more complete example with multiple servers:
{
"mcpServers": {
"browser-bridge": {
"command": "node",
"args": ["C:\\Users\\YourName\\.claude\\mcp-servers\\browser-bridge\\server.js"]
},
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}Each server entry supports command (executable), args (argument array), and optionally env (environment variable overrides).
Windows note: Use absolute paths with double-backslash escaping in JSON. The
~shorthand does not expand inside JSON values.
CLI shortcut: You can also add servers via the command line:
claude mcp add browser-bridge -- node ~/.claude/mcp-servers/browser-bridge/server.jsVerify connection: Run /mcp inside Claude Code to list connected MCP servers and their status.
A tier-based project management system that constrains complexity per project.
| Tier | Effort | Tests | CI | Monitoring |
|---|---|---|---|---|
| T1 Production | 60% | Existing only | Existing only | Existing only |
| T2 Strategic | 30% | Unit tests | Optional | None |
| T3 Experimental | 10% | None | None | None |
| T4 Archive | 0% | None | None | None |
Copy portfolio/PORTFOLIO.md.example to portfolio/PORTFOLIO.md and register your projects.
Copy CLAUDE.md.example to CLAUDE.md and customize. Claude Code loads CLAUDE.md files at multiple levels, merging them in order:
- Managed — enterprise-managed config (if applicable)
- Project —
CLAUDE.mdfiles found by walking fromcwdup to the repo root (all are loaded, closest wins on conflicts) - User global —
~/.claude/CLAUDE.md - Local —
CLAUDE.local.md(same directory as a projectCLAUDE.md, for personal overrides)
Project vs. local: Commit CLAUDE.md to git so the whole team shares it. Use CLAUDE.local.md (add to .gitignore) for personal preferences that shouldn't be shared.
Key sections and what they control:
| Section | Effect |
|---|---|
| Identity | Sets persona (name, role, org) for response style |
| Code Standards | Enforced during code generation — naming, patterns, type hints |
| Agent Behavior | Controls planning discipline, verification steps, autonomous patterns |
| Add-ons | Domain-specific context modules activated per-project |
| Portfolio Governance | Project tier constraints — complexity budgets, testing requirements |
| Commands | Documents available slash commands for discoverability |
The template at CLAUDE.md.example has all sections with placeholder values — fill in your details.
Located at ~/.claude/settings.json. Controls global permissions and plugin management. MCP servers are not configured here — use mcp.json instead.
Permissions — allow and deny lists control which tools Claude Code can use without prompting:
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(pytest:*)",
"Read(**/*.py)",
"Write(**/*.py)",
"Edit(**/*.py)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(sudo:*)",
"Read(.env)",
"Read(**/*.pem)"
]
}
}Permission patterns use the format Tool(pattern):
Bash(command:*)— allow a CLI command with any argumentsRead(**/*.ext)— allow reading files matching a globWrite(**/*.py)— allow writing Python files- Deny rules take precedence over allow rules
Plugins — enable or disable plugins from the official registry:
{
"enabledPlugins": {
"code-review@claude-plugins-official": true,
"commit-commands@claude-plugins-official": true,
"superpowers@claude-plugins-official": true
}
}The loop driver reads .workflow/config.json from your project directory:
{
"limits": {
"max_iterations": 50,
"timeout_seconds": 300,
"max_cost_per_iteration": 5.0,
"max_total_cost": 50.0,
"model_timeout_multipliers": { "opus": 2.0, "sonnet": 1.0, "haiku": 0.5 },
"model_fallback": { "opus": "sonnet" }
},
"stagnation": {
"window_size": 3,
"low_turn_threshold": 2,
"max_consecutive_timeouts": 2
}
}- Never commit API keys, tokens, or credentials
- All secrets load from environment variables (see
.env.examplefiles) --dangerously-skip-permissionsis used by the loop driver for autonomous operation. Understand the implications before using it.- Session files (
playwright-session.json) contain auth cookies and are excluded from git - The
log_redactor.pymodule scrubs API keys from all log output
"Claude" is a trademark of Anthropic, PBC. This project is not affiliated with, endorsed by, or sponsored by Anthropic. See NOTICE for full details.
Issues and pull requests are welcome. Please:
- Follow existing code patterns (see
CLAUDE.md.examplefor standards) - Include tests for new functionality
- Never commit secrets or credentials
- Keep CLAUDE.md files under 150 lines