sub-claude

sub-claude

A session-oriented pool of persistent Claude Code sessions backed by tmux.

The Problem

Running a claude command while another Claude session has a Bash tool call in flight silently destroys that call's output. This is a fundamental Claude Code limitation - the transcript-directory file watcher reacts to new sessions, breaking active ones. You can't reliably run parallel Claude work by spawning new claude processes.

The Solution

sub-claude pre-starts Claude TUI sessions in tmux panes before any work begins. New conversations use /clear, session switches use /resume - all typed into existing sessions, no new processes ever launched.

The result: reliable parallel Claude work with fire-and-forget, blocking, and multi-turn patterns.

Quick Start

# Install CLI
git clone https://github.com/EliasSchlie/sub-claude.git
cd sub-claude
./install.sh

# Initialize a pool (5 slots by default)
sub-claude pool init

# Fire-and-forget
id=$(sub-claude start "refactor auth module")

# Blocking - wait for result
result=$(sub-claude -v response start "summarize this file" --block)

# Multi-turn conversation
id=$(sub-claude start "analyze the codebase")
sub-claude wait "$id"
sub-claude followup "$id" "now suggest improvements" --block

# Parallel fan-out
id1=$(sub-claude start "task one")
id2=$(sub-claude start "task two")
sub-claude wait  # waits for first to finish
sub-claude wait  # waits for the next

Installation

Claude Code Plugin (recommended)

The plugin teaches Claude how to use sub-claude automatically via skills and hooks.

# Per-session (development/testing):
claude --plugin-dir /path/to/sub-claude

# Persistent (via marketplace):
# Inside Claude Code, run:
#   /plugin marketplace add EliasSchlie/claude-plugins
#   /plugin install sub-claude@elias-tools

CLI Binary

The plugin handles Claude Code integration. The CLI binary needs a separate install:

git clone https://github.com/EliasSchlie/sub-claude.git
cd sub-claude
./install.sh          # copies to ~/.local/{bin,lib}
# or
./install.sh --link   # symlinks binary - updates via git pull, no reinstall

Use --prefix /usr/local for system-wide install.

Prerequisites

• bash >= 4.x
• tmux
• jq
• claude CLI (installed and authenticated)

Architecture

         Caller A              Caller B
            |                       |
      start "prompt"        followup $id "prompt"
            |                       |
            v                       v
    +------------------------------------------+
    |          sub-claude orchestrator          |
    |                                          |
    |  Queue (FIFO): [job-3, job-4, ...]       |
    |                                          |
    |  Session mapping:                        |
    |    ID a1b2c3d4 -> slot-0 (busy)          |
    |    ID e5f6a7b8 -> slot-1 (idle)          |
    |    ID c9d0e1f2 -> offloaded (snapshot)   |
    +-------------------+----------------------+
                        |
        +---------------+---------------+
        v                               v
Background watcher            Shared tmux server
(polls every 2s)              +-- slot-0  (busy)
- done detection              +-- slot-1  (idle)
- queue dispatch              +-- slot-2  (fresh)
- crash recovery              +-- slot-3  (fresh)
- pin expiry                  +-- slot-4  (fresh)

Key concepts:

• Pool - pre-started Claude TUI sessions in tmux panes, scoped per project
• Slots - individual tmux panes running persistent Claude sessions
• Job IDs - 8-char hex identifiers for tracking work across slots
• Offloading - idle sessions are snapshot-saved and their slots reused when all are busy
• Queue - excess work is queued FIFO and dispatched as slots free up
• Watcher - background process that monitors slots, dispatches jobs, and handles crash recovery

CLI Reference

sub-claude [-v response|conversation|full|raw] [-C <dir>] <command> [args]