Building a Multi-Agent Claude Code Setup with SmolkAI

It started with a simple problem: Raycast doesn't work on macOS 12 Monterey. I'd just set up a new-to-me MacBook Pro for coding and the first thing I needed was a clipboard history manager—something like Ditto on Windows. Nothing I could find worked on older macOS. So the first thing I did was build one.

Rather than settle for “good enough,” I decided to make it genuinely great: lightweight (native Rust, no Electron), security-conscious (AES-256-GCM encryption, auto-detection of passwords and API keys), and blazing fast. The result is ClipVault—a native macOS clipboard manager that honestly may be better than Raycast’s clipboard at this point. But the reason it exists is simply that I couldn't find a tool that did what I needed on the hardware I had.

To build ClipVault properly, I needed better tooling. That’s where the multi-agent system came in. Instead of one Claude instance doing everything sequentially, I set up a team of specialized agents that can work in parallel—each with its own role, tools, and priority rules. Here's what I built and how I got there.

Research Phase: Using Claude to Study Claude

Before writing any agent configs, I needed to understand what Claude Code's multi-agent system could actually do. I used Claude.ai's Deep Research feature to generate three comprehensive guides covering the full landscape of Claude Code parallelization:

1. Subagents & Custom Agents — the Task tool, .claude/agents/*.md YAML frontmatter, and the experimental Agent Teams feature
2. Multiple Agents & Orchestration — the Claude Agent SDK, git worktree isolation, and inter-agent communication patterns
3. All 6 Parallelization Methods — from native subagents to Claude Squad to headless claude -p fan-out in worktrees

These Deep Research reports became the reference material for everything that followed. Having Claude research its own capabilities turned out to be an effective way to get a structured, comprehensive overview of the tooling.

The 12-Agent Roster

The system has 12 agents organized into two groups: engineering (9 agents) and marketing (3 agents, including the pre-existing site orchestrator).

Engineering Agents

• Architect (Opus, plan mode) — system design, API contracts, file ownership maps. Read-only, never writes code.
• Builder (Sonnet, acceptEdits) — core implementation. Follows the architect's design doc exactly.
• Test Engineer (Sonnet) — proactive test writing. Runs security tests first, then correctness, then everything else.
• Code Reviewer (Sonnet) — proactive quality review. Findings weighted by a P0–P5 priority system.
• Security Auditor (Opus) — OWASP-based vulnerability scanning with technology-specific checklists.
• Performance Analyst (Sonnet) — architecture-level and code-level bottleneck identification.
• Debugger (Sonnet) — five-step root cause analysis: reproduce, localize, hypothesize, fix, verify.
• Hardener (Sonnet) — input validation, error handling, resilience patterns (timeouts, retries, circuit breakers).
• DevOps Engineer (Sonnet) — CI/CD pipelines, Docker configs, deployment and monitoring.

Marketing Agents

• Trend Researcher (Sonnet) — discovers trending formats, sounds, and hashtags on Instagram and TikTok via web search.
• Content Strategist (Sonnet) — writes video scripts, hooks, captions, and AI creative prompts (Midjourney, Runway, Kling, Pika).
• Site Orchestrator — manages smolkin.org: blog posts, SEO, sitemap, git operations.

The Priority Hierarchy

Every agent enforces the same weighted priority system when reporting findings or making trade-offs:

Priority	Category	Weight	Rule
P0	Security	2x	Any vulnerability is critical. Always blocks.
P1	Correctness	1.5x	Bugs that corrupt data or break functionality.
P2	Performance	1x	Blocks if measurably degrades UX or scalability.
P3	Robustness	1x	Missing error handling at system boundaries.
P4	Maintainability	0.5x	Only blocks if egregious (100+ line functions).
P5	Style	0.25x	Never blocks merge. Suggestions only.

The key insight: security at 2x weight means a clean security audit always takes priority over code style. When time or budget is limited, agents must address P0 fully before spending effort on lower tiers.

Real Parallelism: Three Layers

The native Claude Code subagent system (the Task tool) runs agents sequentially in the same directory. That's fine for read-only work like code review, but it's not real parallelism for implementation tasks. I set up three layers:

Layer 1: Native Subagents

Read-only agents (reviewers, analysts, auditors) that don't modify files. Safe to run in parallel since there are no file conflicts.

Layer 2: Agent Teams

Enabled via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json. Provides peer-to-peer coordination with shared task lists and messaging between agents running in tmux panes. This only appeared in early February, and I enabled it as soon as it popped up. It hadn't affected the workflow too much, as I already had so much of it set up.

Layer 3: Git Worktrees

Physical file isolation. Each agent gets its own copy of the repo on its own branch. Two tools for this:

• Claude Squad (cs) — a TUI that manages parallel Claude instances, each in its own git worktree.
• parallel-agents.sh — a custom script that launches N headless claude -p processes, each in a timestamped worktree branch, and collects JSON results.

The worktree approach eliminates file conflicts entirely during development. When agents finish, their branches get squash-merged back to main for a clean history.

Orchestration Workflows

The system defines standard pipelines for common tasks:

• New Feature: architect → parallel builders → parallel (test + review + security) → hardener → devops
• Bug Fix: debugger → parallel (test + review)
• Security Hardening: auditor → hardener → test → review
• Performance: analyst → builder → parallel (test + analyst verify)
• Marketing: trend-researcher → content-strategist → deliverables

Infrastructure Installed

Getting this running on macOS 12 (Monterey, Homebrew Tier 3) required some effort:

• tmux 3.6a — installed via brew install tmux --build-from-source (binary bottles aren't available for Tier 3)
• Claude Squad 1.0.14 — installed via Homebrew. Provides the cs command for the worktree TUI.
• Agent Teams — enabled via experimental environment variable in Claude Code settings
• LibreOffice — installed for headless DOCX-to-PDF conversion of the setup report

Git Discipline and Attribution

Every agent commits after each logical unit of work in its worktree branch. When merging back to main, git merge --squash collapses the micro-commits into one clean commit. All commits carry custom SmolkAI attribution configured via the attribution field in settings.json.

What's Next

The system is configured and documented. The full setup—all 12 agent configs, the orchestration rules, the priority hierarchy, the parallelism scripts, and the detailed report—is available as a PDF report. The next step is to use it on a real project and see how the agents coordinate in practice.

The only bottlenecks are local compute and final product quality. That was the goal from the start.

---