agent-tracker

Agent Tracker

A CLI TUI tool for tracking active Claude Code sessions. Never lose track of your Claude windows again!

🌐 Visit the Homepage - Learn why I built this and see it in action.

Features

• Real-time Session Tracking: Automatically detects when Claude Code sessions start and end
• Activity Monitoring: Real-time tracking of tool usage, prompts, and Claude responses
• Smart Session States: Distinguishes between active, inactive, and ended sessions based on actual activity
• Visual Dashboard: Beautiful 2-column TUI showing all your Claude sessions
• Web Dashboard: Browser-based monitoring with HTTP Basic Auth and optional TLS support
• Rich Terminal Context:
  • iTerm2 integration showing tab names, window names, and profiles
  • Docker container detection
  • Modular terminal provider system (easily extensible to other terminals)
• Redux-Style State Management: Predictable, type-safe state updates with pure reducers
• Session Details: View working directory, terminal info, timestamps, and session metadata
• Keyboard Navigation: Vim-style navigation (j/k or arrow keys)

Documentation

📚 Full Documentation - Visit our documentation site for detailed guides and tutorials.

Problem

Have you ever lost track of Claude Code windows? They get left in tabs, suspended with Ctrl+Z, or hidden in background terminals. Agent Tracker solves this by giving you a live dashboard of all your Claude sessions.

How It Works

Agent Tracker uses Claude Code's plugin system to capture session and activity events in real-time:

1. Hooks capture events from Claude sessions (start, end, tool usage, prompts)
2. Terminal providers extract context (iTerm tab names, profiles, etc.)
3. Events stream to ~/.agent-tracker/sessions.jsonl
4. TUI watches the file and updates the display in real-time
5. Smart states track whether sessions are actively working or idle

For detailed technical architecture, see ARCHITECTURE.md.

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g agent-tracker

# Run the TUI
agent-tracker

Option 2: Install from Source

Step 1: Install Dependencies and Build

# Clone the repository
git clone https://github.com/yourusername/agent-tracker.git
cd agent-tracker

# Install dependencies
npm install

# Build the project
npm run build

# Run the TUI
npm start

Step 2: Install the Claude Hooks Plugin

The plugin enables automatic session tracking by installing hooks that fire when Claude sessions start and end.

From within this repository directory, run these commands in Claude:

# Add this repository as a plugin marketplace
/plugin marketplace add .

# Install the agent-tracker plugin
/plugin install agent-tracker

Important: After installing the plugin, you need to restart any running Claude sessions (or start new ones) for the hooks to be active. The current session won't have the hooks loaded.

Usage

Start the Agent Tracker TUI

If installed globally:

agent-tracker

If running from source:

npm run dev
# or
npm start

Command-Line Options

You can specify a custom events file path for testing or multiple instances:

# Use default events file (~/.agent-tracker/sessions.jsonl)
agent-tracker

# Use a custom events file
agent-tracker --events-file /tmp/test-sessions.jsonl
# or short form:
agent-tracker -e /tmp/test-sessions.jsonl

# Show help
agent-tracker --help

Use cases for custom events files:

• Testing the empty state without deleting your real sessions
• Running multiple independent Agent Tracker instances
• Isolating test sessions from production tracking

Test with Demo Repository

# Terminal 1: Start Agent Tracker
npm run dev

# Terminal 2: Start a test Claude session
npm run demo:session
# or manually:
cd demo-repo && claude

Keyboard Controls

• ↑/↓ or j/k: Navigate between sessions
• q or Ctrl+C: Quit

Web Dashboard

The web dashboard provides browser-based session monitoring with built-in security features.

Starting the Web Dashboard

# Start with auto-generated password (displayed on startup)
npm run start:web

# Or from the web package directory
cd packages/web
npm run start

On startup, credentials are displayed:

============================================
  Agent Tracker Web Dashboard
============================================

  Authentication: ENABLED
  Username: admin
  Password: ZhQpgcM7BFr-BJX5

  URL: http://localhost:3000/

  Test with:
  curl -H "Authorization: Basic YWRtaW46..." http://localhost:3000/

============================================

Web Dashboard Options

# Custom credentials
npm run start:web -- -c admin:mysecretpassword