# HiveCode

**Real-time analytics dashboard for Claude Code**

Track sessions, tool usage, file changes, token costs, and more — all from a real-time local dashboard. Built as an MCP server that plugs directly into Claude Code.

![HiveCode Dashboard](https://img.shields.io/badge/version-3.0.0-f59e0b?style=flat-square) ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) ![Node](https://img.shields.io/badge/node-%3E%3D18-blue?style=flat-square)

## Features

- **Real-time Dashboard** — Live WebSocket updates as Claude Code works
- **Session Tracking** — Monitor every Claude Code session with full detail
- **Tool Analytics** — See which tools are used most, average durations, success rates
- **File Change Log** — Track every file created, edited, or deleted
- **Cost Tracking** — Token usage and estimated API costs with daily breakdowns
- **Canvas Charts** — Visual bar and line charts for activity trends
- **Activity Feed** — Live stream of all events as they happen
- **MCP Server** — Plugs directly into Claude Code via Model Context Protocol
- **Update Notifications** — Get notified when a new version is available
- **Mobile Responsive** — Works on phone and tablet
- **100% Local** — All data stored in SQLite on your machine

## Quick Start

```bash
# Clone the repo
git clone https://github.com/ZedoxDevelopment/hivecode.git
cd hivecode

# Install dependencies
npm install

# Start the dashboard
npm start
```

Open **http://localhost:3800** in your browser.

### Seed Demo Data

Want to see the dashboard in action before connecting Claude Code?

```bash
node src/seed-demo.js
```

## Connect to Claude Code

Add HiveCode as an MCP server in your Claude Code settings:

**~/.claude/settings.json**
```json
{
  "mcpServers": {
    "hivecode": {
      "command": "node",
      "args": ["/path/to/hivecode/src/mcp-server.js"],
      "env": {}
    }
  }
}
```

Or run the MCP server standalone:
```bash
npm run mcp
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `hivecode_start_session` | Start tracking a new Claude Code session |
| `hivecode_log_tool` | Log a tool call with duration and success status |
| `hivecode_log_file` | Log a file change (create/edit/delete) |
| `hivecode_log_tokens` | Log token usage for cost tracking |
| `hivecode_end_session` | End the current session with a summary |
| `hivecode_stats` | Get dashboard statistics |

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/stats` | Dashboard overview stats |
| GET | `/api/sessions` | List all sessions |
| GET | `/api/sessions/:id` | Session detail with events |
| GET | `/api/tools` | Tool usage analytics |
| GET | `/api/files` | Recent file changes |
| GET | `/api/daily` | Daily stats for charts |
| POST | `/api/event` | Log events via HTTP |
| GET | `/api/version` | Current version info |
| GET | `/api/version/check` | Check for updates |
| GET | `/api/health` | Health check |

## Dashboard Pages

- **Overview** — Stats grid, 14-day activity chart, recent sessions, top tools
- **Sessions** — Searchable/filterable session list with drill-down detail view
- **Tools** — Usage distribution chart, per-tool bars, performance table
- **Files** — Searchable file change log across all sessions
- **Costs** — Cost/token trend charts with daily breakdown table
- **Activity Feed** — Real-time event stream via WebSocket
- **Settings** — MCP config, data export, seed/clear data

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `HIVECODE_PORT` | `3800` | Dashboard server port |

## Tech Stack

- **Backend:** Express.js, WebSocket (ws), better-sqlite3
- **Frontend:** Vanilla JS, Canvas charts, CSS custom properties
- **Protocol:** MCP (Model Context Protocol) over JSON-RPC stdio
- **Database:** SQLite with WAL mode

## Project Structure

```
hivecode/
  src/
    server.js       # Express + WebSocket server
    db.js           # SQLite schema + prepared statements
    mcp-server.js   # MCP protocol handler + tools
    seed-demo.js    # Demo data generator
  public/
    index.html      # Dashboard shell
    app.js          # Frontend application
    style.css       # Dark theme styles
  data/             # SQLite database (auto-created)
  version.json      # Version + changelog for update checks
  package.json
```

## License

MIT — [Zedox Development](https://github.com/ZedoxDevelopment)