Introduction
Claude Session Tools is a suite of CLI tools for logging, orchestrating, and analyzing Claude Code sessions. Run parallel sessions, delegate tasks between them, and review your AI collaboration history.
Overview
When working with Claude Code on complex projects, you often need:
- Multiple sessions working on different parts of a codebase
- Coordination between sessions (manager delegates to workers)
- History tracking to review what was done and when
- Real-time monitoring to track session status
Claude Session Tools provides a complete toolkit for these workflows.
Tool Suite
┌─────────────────────────────────────────────────────────────────────┐
│ CLI TOOLS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ logsession │ │ messenger │ │ log-parser │ │
│ │ (core) │ │ (comms) │ │ (parsing) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Start logged Send tasks Parse turns │
│ tmux sessions between from logs │
│ sessions │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ logsession-monitor │ │
│ │ (real-time dashboard) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Core Tools
| Tool | Purpose | Install |
|---|---|---|
| logsession | Start auto-logged Claude sessions in tmux | gitlab-install @session-tools/loggable-session |
| messenger | Send prompts/tasks between sessions | gitlab-install @session-tools/session-messenger |
| log-parser | Parse logs into structured turns | gitlab-install @session-tools/log-parser |
Monitoring Tools
| Tool | Purpose | Install |
|---|---|---|
| logsession-monitor | Real-time web dashboard | gitlab-install @session-tools/logsession-monitor |
| VSCode Extension | IDE integration (planned) | Coming soon |
Quick Start
Install packages using glpkg - a CLI for GitLab Package Registry:
# 1. Install glpkg (one-time)
npm install -g @glpkg/installer
# 2. Configure GitLab access (one-time)
gitlab-config save <your-gitlab-token>
gitlab-config scope set @session-tools microwiseai
# 3. Install core tools
gitlab-install @session-tools/loggable-session
gitlab-install @session-tools/session-messenger
# 4. Start sessions
logsession start manager-1
logsession start worker-1 --detach
logsession start worker-2 --detach
# 5. Orchestrate (from manager session)
messenger discover
messenger send worker-1 "Implement the auth API"
messenger send worker-2 "Write tests for auth"
# 6. Review history
gitlab-install @session-tools/log-parser
log-parser parse worker-1
log-parser read worker-1 --last 5
Use Cases
Solo Development
Use logsession to keep a complete history of your Claude conversations:
logsession start my-project
# Work with Claude...
# All output is logged
# Later, review what happened
log-parser read my-project --last 10
Manager-Worker Pattern
Delegate tasks across multiple sessions:
# Manager orchestrates
messenger send frontend --submit "Build the login form"
messenger send backend --submit "Create auth endpoints"
messenger send tests --submit "Write integration tests"
Coming Soon
- sesh CLI: Simplified session configuration and management
- TDA Pattern: Structured Manager-Worker orchestration
- VSCode Extension: Visual session management in your IDE
Requirements
- Node.js 18 or later
- tmux
- Linux or macOS (Windows via WSL)
Next Steps
- Getting Started - Full installation guide
- logsession - Core session logging
- messenger - Inter-session communication
- Session Monitoring - Real-time dashboard