agent-queue

Multi-agent work queue with tag-based coordination, merge locking, and orchestration. Run multiple AI agents (Claude Code, Cursor, etc.) on the same repo in parallel.

Install

Clone this repo and add the scripts to your PATH, or reference them directly:

AQ=~/development/github.com/jschell12/agent-queue/scripts

No dependencies beyond Python 3.11+ and git.

Quick Start

AQ=~/development/github.com/jschell12/agent-queue/scripts

# 1. Initialize a queue for your project
cd ~/your-project
"$AQ/agent-queue" init

# 2. Write tasks in markdown
cat > tasks.md << 'EOF'
## Backend
- [ ] Add auth middleware -- JWT validation
- [ ] Add rate limiting -- per-IP throttling

## Frontend
- [ ] Add login page -- email + password form
- [ ] Add dashboard -- show user stats
EOF

# 3. Load them (## headers become tags automatically)
"$AQ/agent-queue" add-file tasks.md

# 4. Fire off agents (each in a separate terminal)
claude -p "You are queue worker agent-1. Read the queue, claim tasks, work in a git worktree, merge, repeat."
claude -p "You are queue worker agent-2. Read the queue, claim tasks, work in a git worktree, merge, repeat."

How It Works

• Queue stored at ~/.agent-queue/<project>/queue.json (outside repo, no merge conflicts)
• Tags group related tasks. Agents automatically avoid tag conflicts and cluster related work.
• Merge lock serializes rebase+push to main — only one agent merges at a time.
• Orchestrator can assign, hold, reorder, and prioritize items in real time.
• Source sync — completed items get checked off in your tasks.md automatically.

Scripts

agent-queue — Work Queue

# Worker commands
agent-queue init                              # Create queue for current project
agent-queue add "title" ["desc"] --tags a,b   # Add item with tags
agent-queue add-file tasks.md                 # Bulk add from markdown
agent-queue claim --agent ID                  # Claim next item (tag-aware)
agent-queue yield <id> --agent ID             # Release + claim non-conflicting
agent-queue complete <id>                     # Mark done (checks off in source file)
agent-queue complete <id> --clean             # Mark done (removes from source file)
agent-queue fail <id> --reason "..."          # Mark failed
agent-queue release <id>                      # Return to pending
agent-queue status                            # Queue summary
agent-queue list [--status S] [--tag T]       # List items

# Orchestrator commands
agent-queue plan [--json]                     # Full analysis
agent-queue assign <id> <agent-id>            # Pre-assign to agent
agent-queue unassign <id>                     # Remove assignment
agent-queue priority <id> high|normal|low     # Set priority
agent-queue hold <id>                         # Pause item
agent-queue unhold <id>                       # Resume item
agent-queue reorder <id> --before|--after <id>  # Move in queue

agent-merge — Serialized Merge Lock

agent-merge <branch>                  # Rebase + merge to main (locked)
agent-merge <branch> --delete-branch  # Merge + cleanup
agent-merge <branch> --no-rebase      # --no-ff merge instead
agent-merge status                    # Lock status + history

agent-orchestrate — Automated Queue Optimizer

agent-orchestrate --once              # One-shot check
agent-orchestrate --interval 30       # Loop every 30s
agent-orchestrate --dry-run           # Preview without acting

Tags

Tags reduce merge conflicts by routing related work to the same agent.

Claim priority:

1. Items assigned to this agent
2. High priority items first
3. Tags that don't overlap with other agents' active work
4. Tags that do overlap with this agent's past work (affinity)

Define tags in markdown:

## Sources                            <-- header = tag "sources"
- [ ] Add Reddit source               <-- inherits: sources
- [ ] Add HN source #api              <-- tags: sources, api

## Analysis
- [ ] Improve scoring                 <-- tag: analysis

Agent Isolation

Every agent must work in its own git worktree. Add .worktrees/ to your .gitignore.

WORKTREE="$REPO_ROOT/.worktrees/agent-1"
git worktree add "$WORKTREE" -b "$BRANCH" main
cd "$WORKTREE"
# ... work ...
cd "$REPO_ROOT" && git worktree remove "$WORKTREE"

Claude Code agents: use isolation: "worktree" when spawning via the Agent tool.

Locking

• Queue lock — fcntl.flock, held milliseconds during claim/complete. Auto-released on crash.
• Merge lock — fcntl.flock, held during fetch→rebase→push. 5-min timeout. Auto-released on crash.