claude-agent-monitor

KO | EN

gitlite — search

#hacktoberfest #react #ai #go #android #machine-learning #deep-learning #linux #docker #java #cli #kubernetes #security #openai

claude-agent-monitor

(★ 11)

Real-time monitoring dashboard for Claude Code subagents. Cross-platform: Linux, macOS, Windows, WSL.

claude-agent-monitor Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claude Agent Monitor

Real-time monitoring dashboard for Claude Code subagents. See what your agents are doing, their prompts, tool calls, and outputs - all in a beautiful web dashboard.

![Platform Support](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20WSL-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-green)

## Features

- **Real-time Dashboard** - Watch agents as they work
- **Click for Details** - Click any agent card to see full activity timeline
- **Cross-Platform** - Works on Linux, macOS, Windows, and WSL
- **Auto-Launch** - Dashboard opens automatically when agents spawn
- **Zero Config** - Just install and go

## Quick Install

### Option 1: Let Claude Do It

After cloning, just paste this prompt into Claude Code:

```
Install the Claude Agent Monitor from this repo. Run python install.py, verify it worked
by checking ~/.claude/hooks/ has the files and ~/.claude/settings.json has the hooks
configured, then test by starting the dashboard manually. If anything fails, diagnose and fix it.
```

### Option 2: Manual Install

```bash
# Clone the repository
git clone https://github.com/rcolman6/claude-agent-monitor.git
cd claude-agent-monitor

# Run the installer
python install.py
```

That's it! The monitor will automatically activate next time you use Claude Code with subagents.

## What Gets Installed

The installer copies hook files to `~/.claude/hooks/` and configures your `~/.claude/settings.json`:

```
~/.claude/
├── hooks/
│   ├── agent_state.py         # Shared state management
│   ├── agent_web_dashboard.py # The web UI
│   ├── browser_utils.py       # Cross-platform browser opening
│   ├── on_task_start.py       # Hook: agent starts
│   └── on_task_stop.py        # Hook: agent stops
└── settings.json              # Updated with hook config
```

## Usage

### Automatic Mode (Default)

Just use Claude Code normally. When you (or Claude) spawn subagents, the dashboard will:

1. Launch automatically on `http://localhost:7685`
2. Open your browser to the dashboard
3. Show all running agents with live updates
4. Auto-close 10 seconds after all agents complete

### Manual Mode

Start the dashboard manually:

```bash
python ~/.claude/hooks/agent_web_dashboard.py
```

Then open `http://localhost:7685` in your browser.

## Troubleshooting

If something isn't working, run in Claude Code:

```
/setup-agent-monitor
```

Claude will diagnose and fix common issues.

### Common Issues

**Dashboard doesn't open:**
- Check if port 7685 is in use: `lsof -i :7685`
- Verify hooks are in settings.json: `cat ~/.claude/settings.json`

**"Module not found" errors:**
- Re-run: `python install.py`
- Check files exist: `ls ~/.claude/hooks/`

**WSL: Browser doesn't open:**
- The dashboard opens via `cmd.exe` - make sure it's accessible
- Try manually: `cmd.exe /c start http://localhost:7685`

## Uninstall

```bash
python install.py --uninstall
```

Or manually:
```bash
rm ~/.claude/hooks/agent_*.py ~/.claude/hooks/browser_utils.py ~/.claude/hooks/on_task_*.py
```

## Platform Support

| Platform | Status | Browser Opening |
|----------|--------|-----------------|
| Linux    | ✅     | xdg-open        |
| macOS    | ✅     | open            |
| Windows  | ✅     | os.startfile    |
| WSL      | ✅     | cmd.exe start   |

## Requirements

- Python 3.10+
- Claude Code installed (`~/.claude/` directory exists)
- A web browser

## How It Works

1. **PreToolUse Hook**: When Claude spawns a subagent (Task tool), `on_task_start.py` runs
2. **State Tracking**: Agent info is saved to a temp file
3. **Dashboard Launch**: If not running, the web dashboard starts
4. **Browser Open**: Your browser opens to the dashboard (once per session)
5. **Live Updates**: Dashboard polls for updates every second
6. **Auto-Close**: Dashboard stops 10s after last agent completes

## License

MIT

## Contributing

Issues and PRs welcome! Please test on your platform before submitting.

claude-agent-monitor

claude-agent-monitor Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

claude-agent-monitor

claude-agent-monitor Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README