heretic-cli

Sessions

Run multiple isolated agent instances from the same project with session-specific containers, temp directories, and filtering

How It Works

  • Default session: When --session is omitted, the session name is "default"
  • Session directory: Temp files are stored in .heretic/temp/<session>/
  • Container naming: heretic-<agent>-<session>-<hash8> where hash is derived from the project directory
  • Container label: Every container gets a heretic.session=<name> label for filtering

Usage

# Run two agents in parallel in different sessions
heretic-cli run claude -s feature-a
heretic-cli run claude -s feature-b

# List all containers (shows SESSION column)
heretic-cli ps

# Filter by session
heretic-cli ps -s feature-a

# Stop a specific session
heretic-cli stop -s feature-a

# Attach to a session-specific container
heretic-cli attach claude -s feature-a

File Structure

your-project/
  .heretic/
    temp/
      default/                  # Default session temp files
        .mcp.json
        claude-settings.json
        compose.yaml
      feature-a/                # Named session temp files
        .mcp.json
        claude-settings.json

Each session maintains isolated:

  • MCP configuration
  • Claude settings
  • Compose files (for compose runner)
  • Onboarding seeds