MUSE

Interactive Leader

Spawn and coordinate multiple AI subagents for complex task decomposition

💡

Best Way to Use MUSE

The easiest way to use MUSE is by asking Claude Code or another AI coding agent to run the TRIBE CLI commands for you. Simply describe what you want to accomplish.

Example Prompt

"Use the tribe CLI to start a MUSE session and break down this task into subtasks: [your task description]. Spawn subagents for each subtask and coordinate the work."

Claude will run tribe muse start, tribe muse spawn, and other commands automatically.

What is MUSE?

MUSE (Multi-agent Unified System for Execution) provides an interactive "leader agent" that can spawn and coordinate multiple subagents. The leader understands high-level objectives and delegates tasks to isolated workers, each running in their own git worktree.

Leader + Workers

Architecture Pattern

Git Worktrees

Isolation Model

tmux Sessions

Management

Core Commands

Leader Management

tribe muse start                       # Start leader agent
tribe muse attach                      # Attach to leader session
tribe muse stop                        # Stop leader

Subagent Operations

tribe muse spawn "<task>" [name]       # Spawn subagent for task
tribe muse status                      # Show all subagent status
tribe muse output <session> [lines]    # View subagent output
tribe muse prompt <session> "<msg>"    # Send message to subagent

Iterative Refinement (Negotiate)

tribe muse negotiate "<objective>"     # Start negotiation loop
tribe muse negotiate-refine <s> "<q>"  # Send follow-up question
tribe muse negotiate-accept <session>  # Approve and complete

Agent & System Management

tribe muse agents                      # List all agents with status
tribe muse review <session>            # Review agent work
tribe muse kill <session>              # Kill specific session
tribe muse monitor                     # Health monitoring
tribe muse watchdog                    # Stuck agent recovery
tribe muse cleanup --daemon            # Auto-cleanup daemon
tribe muse autoscale on|off|status     # Warm pool management

Session Lifecycle

Create Worktree & Branch

Creates isolated directory at .muse-worktrees/{name}/ with branch muse/{name}

Create Session & Start Agent

Launches tmux session muse-agent-{name} and starts Claude with the task prompt

Working State

Agent works on the task in isolation. For negotiate mode, enters AWAITING_REVIEW state for iterative refinement.

Completion & Cleanup

Upon CHANGES_COMPLETE, auto-cleanup removes session and worktree

Negotiation Protocol

The negotiate feature enables multi-cycle context gathering with iterative refinement:

Example Workflow

# Phase 1: Initial dispatch
tribe muse negotiate \
  --queries "current auth;pain points;tech debt" \
  --name auth-research \
  "Decide whether to refactor or extend auth system"

# Phase 2: View response (agent outputs AWAITING_REVIEW)
tribe muse output auth-research

# Phase 3: Refine if needed (can repeat up to max-cycles)
tribe muse negotiate-refine auth-research \
  "What does the custom middleware do? Quote the TODO comments."

# Phase 4: Accept when satisfied (sends APPROVED)
tribe muse negotiate-accept auth-research

State Tracking

Negotiation state is persisted at logs/negotiate-{session}.json including objective, queries, cycle count, and refinements.

Warm Pool (Pre-spawned Agents)

Reduces latency by maintaining idle agents ready for tasks:

Configuration

# In circuit.yaml
muse:
  warm_pool:
    enabled: true
    pool_size: 3           # Agents to keep warm
    idle_timeout: "30m"    # Recycle after inactivity
    auto_replenish: true   # Auto-refill pool

Warm Hit

Agent ready instantly - no startup delay

Cold Start

New agent spawned - typical 5-10s startup

Worktree Isolation

Each agent works in an isolated git worktree, preventing conflicts:

Repository Root/
├── .muse-worktrees/
│   ├── fix-login/           # muse-agent-fix-login
│   │   ├── .git -> ...
│   │   ├── CLAUDE.md        # Copied from root
│   │   └── (full codebase)
│   └── add-tests/           # muse-agent-add-tests
└── (main codebase)

Quick Reference

Starting Work

tribe muse start
tribe muse spawn "Fix the login bug" fix-login
tribe muse negotiate "Understand caching" \
  --queries "current;issues"

Monitoring

tribe muse status
tribe muse agents
tribe muse output <session>

Recovery

tribe muse watchdog --once
tribe muse kill <session>

Cleanup

tribe muse clean --force --all
tribe muse cleanup --daemon

Orchestrator Integrations

TRIBE integrates with other AI orchestration systems to provide tribal knowledge retrieval. By using MUSE as a "librarian" or integrating the TRIBE APIs directly, you can significantly improve performance for any orchestrator by leveraging past session context.

MUSE as Librarian

Use MUSE as a dedicated research agent that retrieves relevant past sessions and knowledge before your primary orchestrator begins work. This "librarian" pattern significantly reduces context-building time and prevents repeated mistakes.

# Spawn MUSE as librarian before main task
tribe muse negotiate \
  --queries "authentication patterns;past bugs;code conventions" \
  --name librarian-auth \
  "Gather all relevant context about our auth system"

# View gathered context
tribe muse output librarian-auth

# Accept and use context in your orchestrator
tribe muse negotiate-accept librarian-auth

# The session summary is now available via API for other tools

Why Use MUSE as Librarian?

• Specialized for context retrieval with negotiate protocol
• Iterative refinement until context is sufficient
• Results automatically stored in tribal knowledge
• 40-60% reduction in primary agent context-building time

Sessions & Search APIs

Integrate tribal knowledge directly into your orchestrator's skills using the TRIBE CLI or REST APIs. This enables any agent system to leverage past session context.

CLI Commands for Skills

# Search sessions by keyword
tribe search "authentication bug"
tribe search --project myapp "login flow"

# Recall a specific session's summary
tribe recall <session-id>

# Search the knowledge base
tribe kb search "how to fix CORS"
tribe kb list --category pattern

# List recent sessions
tribe sessions list
tribe sessions search --since 7d

REST API Endpoints

# Search sessions via API
GET /api/sessions/search?q=keyword&project=myapp&since=7d

# Get session summary
GET /api/sessions/{session-id}/summary

# Search knowledge base
GET /api/knowledge?category=pattern&tags=cors

# Filter by subagent type (muse/circuit)
GET /api/tribes/sessions?subagent_type=muse

Example Skill Definition

# Example skill that queries tribal knowledge
name: tribe-recall
description: Recall context from past TRIBE sessions

# Skill implementation
invoke: |
  # Search for relevant past sessions
  RESULTS=$(tribe search "$QUERY" --limit 5 --json)

  # Recall specific session if found
  if [ -n "$SESSION_ID" ]; then
    tribe recall "$SESSION_ID"
  fi

  # Return context for orchestrator
  echo "$RESULTS"

Claude Code Stop Hooks

When using Claude Code, configure stop hooks to automatically trigger TRIBE lookups at key moments. This injects tribal knowledge into the agent's context without manual intervention.

Recommended Hook Configuration

# In your .claude/settings.json or hooks configuration
{
  "hooks": {
    "stop": [
      {
        "name": "tribe-context-lookup",
        "trigger": "before_response",
        "command": "tribe search \"$CURRENT_TASK\" --limit 3 --json"
      },
      {
        "name": "tribe-pattern-check",
        "trigger": "before_code_change",
        "command": "tribe kb search \"$FILE_TYPE patterns\" --limit 5"
      }
    ]
  }
}

Stop Hook Examples

Before Task Start

tribe search "$TASK_DESC" \
  --since 30d \
  --project $PROJECT

Find related past work before starting

Before Code Commit

tribe kb search \
  "commit conventions" \
  --category pattern

Apply team conventions automatically

On Error

tribe search "$ERROR_MSG" \
  --category debugging

Find past solutions to similar errors

Session End

tribe kb save \
  --session-id $SESSION \
  --auto-extract

Auto-extract patterns on completion

Integration Best Practices

Do

• Use MUSE librarian for complex research tasks
• Configure stop hooks for automatic context injection
• Cache frequently-used session lookups
• Filter by project and date range for relevance
• Save useful patterns to knowledge base

Don't

• Overload context with too many session results
• Skip the librarian step for complex domains
• Ignore subagent_type filtering for relevant results
• Forget to sync local knowledge base periodically
• Use raw session output without summary extraction

MUSE

Interactive Leader

Spawn and coordinate multiple AI subagents for complex task decomposition

💡

Best Way to Use MUSE

The easiest way to use MUSE is by asking Claude Code or another AI coding agent to run the TRIBE CLI commands for you. Simply describe what you want to accomplish.

Example Prompt

"Use the tribe CLI to start a MUSE session and break down this task into subtasks: [your task description]. Spawn subagents for each subtask and coordinate the work."

Claude will run tribe muse start, tribe muse spawn, and other commands automatically.

What is MUSE?

Leader + Workers

Architecture Pattern

Git Worktrees

Isolation Model

tmux Sessions

Management

Core Commands

Leader Management

tribe muse start                       # Start leader agent
tribe muse attach                      # Attach to leader session
tribe muse stop                        # Stop leader

Subagent Operations

tribe muse spawn "<task>" [name]       # Spawn subagent for task
tribe muse status                      # Show all subagent status
tribe muse output <session> [lines]    # View subagent output
tribe muse prompt <session> "<msg>"    # Send message to subagent

Iterative Refinement (Negotiate)

tribe muse negotiate "<objective>"     # Start negotiation loop
tribe muse negotiate-refine <s> "<q>"  # Send follow-up question
tribe muse negotiate-accept <session>  # Approve and complete

Agent & System Management

tribe muse agents                      # List all agents with status
tribe muse review <session>            # Review agent work
tribe muse kill <session>              # Kill specific session
tribe muse monitor                     # Health monitoring
tribe muse watchdog                    # Stuck agent recovery
tribe muse cleanup --daemon            # Auto-cleanup daemon
tribe muse autoscale on|off|status     # Warm pool management

Session Lifecycle

Create Worktree & Branch

Creates isolated directory at .muse-worktrees/{name}/ with branch muse/{name}

Create Session & Start Agent

Launches tmux session muse-agent-{name} and starts Claude with the task prompt

Working State

Agent works on the task in isolation. For negotiate mode, enters AWAITING_REVIEW state for iterative refinement.

Completion & Cleanup

Upon CHANGES_COMPLETE, auto-cleanup removes session and worktree

Negotiation Protocol

The negotiate feature enables multi-cycle context gathering with iterative refinement:

Example Workflow

# Phase 1: Initial dispatch
tribe muse negotiate \
  --queries "current auth;pain points;tech debt" \
  --name auth-research \
  "Decide whether to refactor or extend auth system"

# Phase 2: View response (agent outputs AWAITING_REVIEW)
tribe muse output auth-research

# Phase 3: Refine if needed (can repeat up to max-cycles)
tribe muse negotiate-refine auth-research \
  "What does the custom middleware do? Quote the TODO comments."

# Phase 4: Accept when satisfied (sends APPROVED)
tribe muse negotiate-accept auth-research

State Tracking

Negotiation state is persisted at logs/negotiate-{session}.json including objective, queries, cycle count, and refinements.

Warm Pool (Pre-spawned Agents)

Reduces latency by maintaining idle agents ready for tasks:

Configuration

# In circuit.yaml
muse:
  warm_pool:
    enabled: true
    pool_size: 3           # Agents to keep warm
    idle_timeout: "30m"    # Recycle after inactivity
    auto_replenish: true   # Auto-refill pool

Warm Hit

Agent ready instantly - no startup delay

Cold Start

New agent spawned - typical 5-10s startup

Worktree Isolation

Each agent works in an isolated git worktree, preventing conflicts:

Repository Root/
├── .muse-worktrees/
│   ├── fix-login/           # muse-agent-fix-login
│   │   ├── .git -> ...
│   │   ├── CLAUDE.md        # Copied from root
│   │   └── (full codebase)
│   └── add-tests/           # muse-agent-add-tests
└── (main codebase)

Quick Reference

Starting Work

tribe muse start
tribe muse spawn "Fix the login bug" fix-login
tribe muse negotiate "Understand caching" \
  --queries "current;issues"

Monitoring

tribe muse status
tribe muse agents
tribe muse output <session>

Recovery

tribe muse watchdog --once
tribe muse kill <session>

Cleanup

tribe muse clean --force --all
tribe muse cleanup --daemon

Orchestrator Integrations

MUSE as Librarian

# Spawn MUSE as librarian before main task
tribe muse negotiate \
  --queries "authentication patterns;past bugs;code conventions" \
  --name librarian-auth \
  "Gather all relevant context about our auth system"

# View gathered context
tribe muse output librarian-auth

# Accept and use context in your orchestrator
tribe muse negotiate-accept librarian-auth

# The session summary is now available via API for other tools

Why Use MUSE as Librarian?

• Specialized for context retrieval with negotiate protocol
• Iterative refinement until context is sufficient
• Results automatically stored in tribal knowledge
• 40-60% reduction in primary agent context-building time

Sessions & Search APIs

Integrate tribal knowledge directly into your orchestrator's skills using the TRIBE CLI or REST APIs. This enables any agent system to leverage past session context.

CLI Commands for Skills

# Search sessions by keyword
tribe search "authentication bug"
tribe search --project myapp "login flow"

# Recall a specific session's summary
tribe recall <session-id>

# Search the knowledge base
tribe kb search "how to fix CORS"
tribe kb list --category pattern

# List recent sessions
tribe sessions list
tribe sessions search --since 7d

REST API Endpoints

# Search sessions via API
GET /api/sessions/search?q=keyword&project=myapp&since=7d

# Get session summary
GET /api/sessions/{session-id}/summary

# Search knowledge base
GET /api/knowledge?category=pattern&tags=cors

# Filter by subagent type (muse/circuit)
GET /api/tribes/sessions?subagent_type=muse

Example Skill Definition

# Example skill that queries tribal knowledge
name: tribe-recall
description: Recall context from past TRIBE sessions

# Skill implementation
invoke: |
  # Search for relevant past sessions
  RESULTS=$(tribe search "$QUERY" --limit 5 --json)

  # Recall specific session if found
  if [ -n "$SESSION_ID" ]; then
    tribe recall "$SESSION_ID"
  fi

  # Return context for orchestrator
  echo "$RESULTS"

Claude Code Stop Hooks

When using Claude Code, configure stop hooks to automatically trigger TRIBE lookups at key moments. This injects tribal knowledge into the agent's context without manual intervention.

Recommended Hook Configuration

# In your .claude/settings.json or hooks configuration
{
  "hooks": {
    "stop": [
      {
        "name": "tribe-context-lookup",
        "trigger": "before_response",
        "command": "tribe search \"$CURRENT_TASK\" --limit 3 --json"
      },
      {
        "name": "tribe-pattern-check",
        "trigger": "before_code_change",
        "command": "tribe kb search \"$FILE_TYPE patterns\" --limit 5"
      }
    ]
  }
}

Stop Hook Examples

Before Task Start

tribe search "$TASK_DESC" \
  --since 30d \
  --project $PROJECT

Find related past work before starting

Before Code Commit

tribe kb search \
  "commit conventions" \
  --category pattern

Apply team conventions automatically

On Error

tribe search "$ERROR_MSG" \
  --category debugging

Find past solutions to similar errors

Session End

tribe kb save \
  --session-id $SESSION \
  --auto-extract

Auto-extract patterns on completion

Integration Best Practices

Do

• Use MUSE librarian for complex research tasks
• Configure stop hooks for automatic context injection
• Cache frequently-used session lookups
• Filter by project and date range for relevance
• Save useful patterns to knowledge base

Don't

• Overload context with too many session results
• Skip the librarian step for complex domains
• Ignore subagent_type filtering for relevant results
• Forget to sync local knowledge base periodically
• Use raw session output without summary extraction

MUSE

Best Way to Use MUSE

What is MUSE?

Core Commands

Leader Management

Subagent Operations

Iterative Refinement (Negotiate)

Agent & System Management

Session Lifecycle

Create Worktree & Branch

Create Session & Start Agent

Working State

Completion & Cleanup

Negotiation Protocol

Example Workflow

State Tracking

Warm Pool (Pre-spawned Agents)

Configuration

Warm Hit

Cold Start

Worktree Isolation

Quick Reference

Starting Work

Monitoring

Recovery

Cleanup

Orchestrator Integrations

MUSE as Librarian

Why Use MUSE as Librarian?

Sessions & Search APIs

CLI Commands for Skills

REST API Endpoints

Example Skill Definition

Claude Code Stop Hooks

Recommended Hook Configuration

Stop Hook Examples

Before Task Start

Before Code Commit

On Error

Session End

Integration Best Practices

Do

Don't

Related Documentation

CIRCUIT System

CLI Commands

API Reference

Getting Started

MUSE

Best Way to Use MUSE

What is MUSE?

Core Commands

Leader Management

Subagent Operations

Iterative Refinement (Negotiate)

Agent & System Management

Session Lifecycle

Create Worktree & Branch

Create Session & Start Agent

Working State

Completion & Cleanup

Negotiation Protocol

Example Workflow

State Tracking

Warm Pool (Pre-spawned Agents)

Configuration

Warm Hit

Cold Start

Worktree Isolation

Quick Reference

Starting Work

Monitoring

Recovery

Cleanup

Orchestrator Integrations

MUSE as Librarian

Why Use MUSE as Librarian?

Sessions & Search APIs

CLI Commands for Skills

REST API Endpoints