Parallel Coding Agents with Tmux: 4-8 Agents Setup Guide

Manuel Schipper has been running parallel coding agents with a lightweight setup using tmux, Markdown files, bash aliases, and six slash commands. These are vanilla agents without subagent profiles or orchestrators, using a role naming convention per tmux window: Planner (builds Markdown specs), Worker (implements from finished specs), and PM (backlog grooming and idea dumping).

Feature Design System

Most code writing happens from finished specs called Feature Designs (FDs). An FD is a Markdown file containing:

The problem being solved
All solutions considered with pros and cons for each
The final solution with implementation plan including files to update
Verification steps

After adopting this system, Schipper can work in parallel with 4-8 agents. Beyond 8 agents, decision quality suffers. The system was built manually in one project with 300+ specs, then ported to new projects using a /fd-init command that bootstraps the setup into any repository.

FD Tracking and Lifecycle

Each FD gets a numbered spec file (FD-001, FD-002...) tracked in an index across all FDs. Files live in docs/features/ and move through 8 stages:

Planned: Identified, not yet designed
Design: Actively designing the solution
Open: Designed, ready for implementation
In Progress: Currently being implemented
Pending Verification: Code complete, awaiting runtime verification
Complete: Verified working, ready to archive
Deferred: Postponed indefinitely
Closed: Won't do

Slash Commands

Six slash commands handle the full lifecycle:

/fd-new: Create a new FD from an idea dump
/fd-status: Show the index: what's active, pending verification, and done
/fd-explore: Bootstrap a session: load architecture docs, dev guide, FD index
/fd-deep: Launch 4 parallel Opus agents to explore a hard design problem
/fd-verify: Proofread code, propose a verification plan, commit
/fd-close: Archive the FD, update the index, update the changelog

Every commit ties back to its FD (e.g., "FD-049: Implement incremental index rebuild"). The changelog accumulates automatically as FDs complete.

FD File Example

FD-051: Multi-label document classification Status: Open Priority: Medium Effort: Medium Impact: Better recall for downstream filtering

Problem

Incoming documents get a single category label, but many span multiple topics. Downstream filters miss relevant docs because the classifier forces a single best-fit.

Solution

Replace single-label classification with multi-label:

Use an LLM to assign confidence scores per category.
Accept all labels above 0.90 confidence.
For ambiguous scores (0.50-0.90), run a second LLM pass with few-shot examples to confirm.
Store all labels with scores so downstream queries can threshold flexibly.

Files to Modify

src/classify/multi_label.py (new: LLM-based multi-label logic)
src/classify/prompts.py (new: few-shot templates for ambiguous cases)
sql/01_schema.sql (add document_labels table with scores)
sql/06_classify_job.sql (new: scheduled classification after ingestion)

Verification

Run classifier on staging document table
Verify no errors in operation log, run health checks
Spot-check: docs with known multi-topic content have expected labels
Run tests, confirm downstream filters respect confidence threshold

System Initialization

Running /fd-init in any repository:

Infers project context from CLAUDE.md, package configs, and git log
Creates directory structure (docs/features/, docs/features/archive/)
Generates a FEATURE_INDEX.md customized to the project
Creates an FD template
Installs the six slash commands
Appends FD lifecycle conventions to the project's CLAUDE.md

Files created include docs/features/FEATURE_INDEX.md (feature index), docs/features/TEMPLATE.md (FD file template), docs/features/archive/ (archive directory), CHANGELOG.md (Keep a Changelog format), and updates to CLAUDE.md with project conventions including FD system.

📖 Read the full source: HN AI Agents