npm package: @mdayan896/cc-radar
Description: Real-time token radar for Claude Code
Author: MD Ayan
Latest version: 0.1.0

# 📡 @mdayan896/cc-radar

[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![SQLite](https://img.shields.io/badge/SQLite-local%20storage-003B57?logo=sqlite&logoColor=white)](https://www.sqlite.org/)
[![Server-Sent Events](https://img.shields.io/badge/SSE-live%20updates-1f6feb)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-local%20logs-111827)](https://www.anthropic.com/)
[![License-MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![Follow on X](https://img.shields.io/badge/X-%40mdayan24X-black?logo=x&logoColor=white)](https://www.x.com/mdayan24X)

### The Industrial Operator Console for your AI Agents.

`@mdayan896/cc-radar` is a lightweight, local-first control center for monitoring **Claude Code**, **Codex**, **Cursor**, and other Agentic tools. It transforms silent log files and local databases into a high-density, real-time telemetry dashboard.

![Cc-Radar Dashboard Preview](./docs/img/preview.png)

---

## ⚡ Why `cc-radar`?

*   **100% Local & Private**: No data ever leaves your machine. It reads the logs your CLIs already write.
*   **Real-Time Telemetry**: Uses Server-Sent Events (SSE) for instant dashboard updates without polling.
*   **Agent Agnostic**: Supports Claude Code, Codex, Cursor, and OpenCode out of the box.
*   **Industrial Aesthetic**: Designed like a mission control console for maximum focus and data density.
*   **Optimized Workflows**: Built-in "Action Center" with copy-ready payloads to optimize your agent's context and cost.

---

## 🛠️ Features

*   ✅ **Live Session Monitoring**: Track active sessions across multiple sources.
*   📊 **Token Analytics**: Detailed burn-rate and time-left estimates (when token data is available).
*   🚨 **Error Tracking**: Instant alerts for API failures, system errors, and redundant reads.
*   ⚡ **Burn-Rate Alerts**: High-usage notifications to keep your budget in check.
*   🕰️ **Session History**: Persistent local storage powered by SQLite (with JSON fallback).
*   📉 **Redundancy Detection**: Highlighting when agents are stuck rereading the same files.

---

## 🚀 Quick Start

Ensure you have [Node.js 18+](https://nodejs.org/) installed.

### Zero-Install Workflow (Recommended)
Run the console immediately without cluttering your global space:
```bash
npx @mdayan896/cc-radar
```
This will automatically launch the **Industrial Operator Console** at `http://localhost:7331`.

### Global Installation
If you use `cc-radar` frequently, install it globally to invoke it from any shell:
```bash
npm install -g @mdayan896/cc-radar
@mdayan896/cc-radar
```

---

## 🎮 Command Line Interface

```bash
npx @mdayan896/cc-radar \
  --root ~/.claude/projects \
  --history ~/.claude/history.jsonl \
  --db ~/.cc-radar/history.sqlite3 \
  --port 7331 \
  --no-open
```

---

## 🕵️ How it Works

1.  **Discovery**: Automatically detects local telemetry locations for all supported agents.
2.  **Streaming**: Watches for file changes and read only the newly appended data (minimal I/O).
3.  **Aggregation**: Normalizes raw JSONL/SQLite records into unified session models.
4.  **Broadcast**: Pushes live state updates to the browser-based Operator Console.

---

## 📂 Project Structure

*   `bin/cc-radar.js`: CLI Entry point.
*   `src/radar.js`: Core service and file-watcher orchestration.
*   `src/scanner.js`: Incremental data ingestion engine.
*   `src/aggregator.js`: Logic for session modeling and metric derivation.
*   `public/`: Frontend assets (Vanilla CSS & JS).

---

## 🤝 Contributing

Contributions are welcome! Please check the [Implementation Roadmap](./docs/roadmap.md) for planned features.

1.  Clone the repo: `git clone https://github.com/mdayan81/cc-radar.git`
2.  Install dependencies: `npm install`
3.  Run tests: `npm test`
4.  Launch dev mode: `npm run dev`

---

## 📜 License

Distributed under the **MIT License**. See `LICENSE` for more information.

---

## 💬 Social

Follow for updates and feature drops: [**@mdayan24X**](https://www.x.com/mdayan24X)