Session Monitoring

claudectl Session Monitoring

You have access to claudectl, a local session supervisor for Claude Code. Use it when the user asks about:

• How many sessions are running, their status, or what they're doing
• Session costs, burn rates, or budget tracking
• Session health (cognitive rot, loops, stalls, context saturation)
• Brain decisions, learning progress, or accuracy
• File conflicts between sessions
• Multi-session orchestration

Available CLI Flags

# Setup
claudectl --init                   # Wire up Claude Code hooks (one-time)
claudectl --init -s project        # Wire up hooks for this project only
claudectl --uninstall              # Remove claudectl hooks

# Session status
claudectl --list                   # Human-readable session list
claudectl --json                   # Machine-readable JSON with full data
claudectl --watch                  # Stream status changes

# Cost and history
claudectl --stats --since 24h     # Aggregated statistics
claudectl --history --since 24h   # Completed session history
claudectl --summary --since 8h    # Activity summary

# Brain
claudectl --mode status     # Show current brain gate mode
claudectl --mode on         # Brain evaluates tool calls (default)
claudectl --mode off        # Disable brain gate
claudectl --mode auto       # Brain auto-approves above threshold
claudectl --brain-stats accuracy  # Per-tool accuracy breakdown
claudectl --brain-stats learning-curve  # Correction rate over time
claudectl --brain-stats baseline  # Brain vs static rules comparison
claudectl --brain-stats false-approve   # Safety: false positive rate

# Diagnostics
claudectl --doctor                # Check terminal integration
claudectl --brain-prompts         # List prompt template sources

Health Check Icons

When reporting session health from JSON output, these are the severity indicators:

• Critical: cognitive rot (score > 70), context > 90%, error loops
• Warning: context > 80%, cost spikes, stalls, early decay
• Info: proactive compaction suggestion, low cache

Key Fields in JSON Output

Each session in --json output includes:

• status: NeedsInput, Processing, Waiting, Idle, Finished
• cost_usd: total session cost
• burn_rate_per_hr: current spend rate
• context_tokens / context_max: context window usage
• decay_score: 0-100 cognitive health score
• has_file_conflict: boolean for cross-session conflicts
• pending_tool_name / pending_tool_input: what's waiting for approval

Source: mercurialsolo/claudectl — distributed by TomeVault.