Skip to content

Commit 7fbeb48

Browse files
AbhilashSriAbhilashSri
authored
Merge pull request #22 from vicarious11/docs/readme-rewrite
feat: --demo mode + README rewrite
2 parents f876d37 + e79154e commit 7fbeb48

9 files changed

Lines changed: 610 additions & 62 deletions

File tree

‎README.md‎

Lines changed: 130 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,161 @@
11
# agenttop
22

3-
`htop` for AI coding agents. See where your tokens and money actually go.
3+
`htop` for AI coding agents.
44

5-
![agenttop web dashboard](assets/screenshots/optimizer.png)
5+
```bash
6+
git clone https://github.com/vicarious11/agenttop && cd agenttop && ./setup.sh
7+
./run.sh # localhost:8420
8+
```
9+
10+
![agenttop dashboard](assets/screenshots/optimizer.png)
611

7-
## The problem
12+
Monitors **Claude Code**, **Cursor**, **Kiro**, **Codex**, **Copilot**. Reads the local files they already write (`~/.claude/`, `~/.cursor/`, etc). Read-only. Nothing leaves your machine.
813

9-
You use Claude Code, Cursor, Copilot — maybe all three. You're spending $500+/month and have zero visibility. Each tool buries usage data in local files nobody reads. You don't know which sessions waste money, which model is overkill, or if you're even getting better at prompting.
14+
## what it does
1015

11-
## The fix
16+
- unified dashboard across all your AI coding tools
17+
- every session, every prompt, every token, every dollar — one place
18+
- search sessions by project, sort by cost, view full prompt history
19+
- AI analysis: scores you 0-100 on session hygiene, prompt quality, cost efficiency, cache usage, tool utilization
20+
- cost forensics: spend by project, by model, estimated waste from marathon sessions
21+
- detects anti-patterns: correction spirals, context blowup, repeated prompts, model overkill
22+
23+
## install
1224

1325
```bash
1426
git clone https://github.com/vicarious11/agenttop && cd agenttop && ./setup.sh
15-
./run.sh
16-
# open localhost:8420
1727
```
1828

19-
That's it. Reads your local AI tool data. Shows everything in one dashboard. Nothing leaves your machine.
29+
or `pip install agenttop`
2030

21-
## What you get
31+
## run
2232

23-
**One dashboard for all your AI tools** — Claude Code, Cursor, Kiro, Codex, Copilot. Total tokens, total cost, session history, model usage, hourly patterns. All in one place.
33+
```bash
34+
./run.sh # web dashboard
35+
.venv/bin/agenttop # terminal dashboard
36+
agenttop init # set up LLM for analysis (ollama/anthropic/openai)
37+
```
2438

25-
**Session-level analysis** — Browse every session. Search by project. Sort by cost. Click any session to see the full prompt history. Select sessions and run AI analysis to find correction spirals, wasted tokens, and bad prompting patterns.
39+
## data sources
2640

27-
**A score (0-100)** — Deterministic. Computed from 5 dimensions: session hygiene, prompt quality, cost efficiency, cache hit rate, tool utilization. Not vibes — actual data ratios.
41+
```
42+
~/.claude/projects/**/*.jsonl exact token counts per message
43+
~/.cursor/ai-tracking/*.db conversations, models, AI vs human ratio
44+
~/.codex/.codex-global-state.json prompts, automations
45+
~/.config/github-copilot/ session state
46+
~/Library/.../Kiro/state.vscdb workspace data
47+
```
2848

29-
**Cost forensics** — Which project burned the most money. Which model is overkill. How much you wasted in marathon sessions where context degraded. Dollar amounts, not percentages.
49+
## architecture
3050

31-
**Recommendations that reference your data** — "Session X cost $31 and had 3 correction spirals. Use /compact after 50 messages." Not generic tips.
51+
```
52+
┌──────────────────────────────────────────────┐
53+
│ YOUR MACHINE (read-only) │
54+
│ │
55+
│ ~/.claude/ ~/.cursor/ ~/.codex/ ... │
56+
└──────┬───────────┬────────────┬──────────────┘
57+
│ │ │
58+
▼ ▼ ▼
59+
┌──────────────────────────────────────────────┐
60+
│ COLLECTORS │
61+
│ │
62+
│ ClaudeCodeCollector → JSONL parser │
63+
│ CursorCollector → SQLite + workspace │
64+
│ KiroCollector → VS Code state DB │
65+
│ CodexCollector → JSON + SQLite │
66+
│ CopilotCollector → session JSON │
67+
│ │
68+
│ Each: collect_sessions() → list[Session] │
69+
│ get_stats(days) → ToolStats │
70+
└──────────────────┬───────────────────────────┘
71+
│
72+
┌────────────┴────────────┐
73+
▼ ▼
74+
┌─────────────┐ ┌─────────────┐
75+
│ WEB (D3) │ │ TUI (term) │
76+
│ port 8420 │ │ textual │
77+
│ │ │ │
78+
│ FastAPI │ │ 5 tabs: │
79+
│ WebSocket │ │ dashboard │
80+
│ 3 tabs: │ │ sessions │
81+
│ overview │ │ explorer │
82+
│ sessions │ │ analysis │
83+
│ analyze │ │ graph │
84+
└──────┬──────┘ └──────────────┘
85+
│
86+
▼
87+
┌──────────────────────────────────────┐
88+
│ OPTIMIZER (map-reduce-generate) │
89+
│ │
90+
│ MAP: per-session LLM calls │
91+
│ (cached, concurrent) │
92+
│ intent, spirals, quality │
93+
│ │
94+
│ REDUCE: pure python, deterministic │
95+
│ score 0-100, 5 dimensions │
96+
│ cost forensics, anti-pats │
97+
│ │
98+
│ GENERATE: single LLM call │
99+
│ profile, recs, insights │
100+
│ │
101+
│ LLM: ollama / anthropic / openai │
102+
└──────────────────────────────────────┘
103+
```
32104

33-
## Install
105+
**collectors** parse tool-specific local files into a unified `Session` model (id, tool, project, messages, tokens, cost, prompts, timestamps). each collector handles one tool's quirks — JSONL for Claude, SQLite for Cursor, JSON blobs for Codex.
34106

35-
```bash
36-
# from source (recommended)
37-
git clone https://github.com/vicarious11/agenttop && cd agenttop && ./setup.sh
107+
**web dashboard** is vanilla JS + D3, no frameworks. FastAPI serves the API and static files. WebSocket for live updates. three tabs: overview (knowledge graph + panels), sessions (paginated browser with detail pane), analyze (select sessions → LLM analysis → score + cost forensics + recommendations).
38108

39-
# or pip
40-
pip install agenttop
41-
```
109+
**TUI** is built on textual. plotext for charts. five tabs: dashboard (stats + charts), sessions (project aggregates + history), explorer (interactive search/select/analyze), analysis (model usage + intent distribution), graph (tree view).
42110

43-
## Run
111+
**optimizer** is the interesting part. three phases:
44112

45-
```bash
46-
./run.sh # web dashboard at localhost:8420
47-
.venv/bin/agenttop # terminal dashboard
48-
agenttop init # configure LLM for AI analysis
49-
```
113+
1. **MAP** — takes your top 30 sessions (by cost), sends each to an LLM with full prompt history. classifies: intent (debugging/greenfield/exploration/...), had correction spirals?, prompt quality, wasted effort. results cached per session ID at `~/.agenttop/session_cache.json` — sessions are immutable so they're never re-analyzed. max 10 new sessions per run. concurrent: 1 worker for ollama, 4 for cloud.
50114

51-
## How it works
115+
2. **REDUCE** — pure python. no LLM. computes a deterministic score from 5 dimensions (0-20 points each):
116+
- session hygiene: `sessions_without_spirals / total × 20`
117+
- prompt quality: `sessions_without_waste / total × 20`
118+
- cost efficiency: `(1 - waste_pct/100) × 20`
119+
- cache efficiency: `cache_hit_rate/100 × 20`
120+
- tool utilization: `features_used/features_available × 20`
52121

53-
Reads local files your tools already create. Read-only. No API keys needed. No Docker. No cloud.
122+
also computes cost forensics (spend by project, by model, waste estimation from marathon sessions) and anti-pattern counts.
54123

55-
```
56-
~/.claude/projects/**/*.jsonl → Claude Code sessions, tokens, costs
57-
~/.cursor/ai-tracking/*.db → Cursor conversations, models, code stats
58-
~/.codex/.codex-global-state.json → Codex prompts, automations
59-
~/.config/github-copilot/ → Copilot session state
60-
~/Library/.../Kiro/state.vscdb → Kiro workspace data
61-
|
62-
v
63-
agenttop (localhost:8420)
64-
|
65-
v
66-
dashboard + AI analysis (optional, local Ollama or cloud LLM)
124+
3. **GENERATE** — single LLM call with ~2K tokens of pre-computed metrics. LLM writes prose (developer profile, recommendations, project insights). it does NOT compute any numbers — those come from REDUCE.
125+
126+
the score is fully traceable. "session hygiene: 14/20 — 23/30 sessions had no correction spirals." not a vibe check.
127+
128+
## API
129+
130+
| endpoint | what |
131+
|----------|------|
132+
| `GET /api/stats?days=N` | aggregated stats from all collectors |
133+
| `GET /api/sessions?days=N` | all sessions (paginated client-side) |
134+
| `GET /api/sessions/{id}` | full session detail with prompts |
135+
| `GET /api/models` | claude model usage (input/output/cache) |
136+
| `GET /api/hours` | hourly token distribution |
137+
| `GET /api/graph` | D3-compatible knowledge graph |
138+
| `POST /api/analyze-sessions` | LLM analysis on selected sessions |
139+
| `POST /api/optimize` | full optimizer pipeline |
140+
| `GET /api/optimize-stream` | SSE streaming progress + result |
141+
| `WS /ws` | real-time stat updates |
142+
143+
## config
144+
145+
zero config by default. `agenttop init` for interactive setup, or:
146+
147+
```toml
148+
# ~/.agenttop/config.toml
149+
[llm]
150+
provider = "ollama" # ollama | anthropic | openai | openrouter
151+
model = "ollama/gemma3:4b"
152+
map_concurrency = 0 # 0 = auto
67153
```
68154

69-
## No telemetry
155+
## no telemetry
70156

71-
Zero. Your data stays on your machine. If you use Ollama for analysis, nothing leaves your laptop at all.
157+
zero. local only. ollama = nothing leaves your machine.
72158

73-
## License
159+
## license
74160

75161
Apache 2.0

‎src/agenttop/cli.py‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,19 @@
1818
@click.group(invoke_without_command=True)
1919
@click.version_option(version=__version__)
2020
@click.option("--days", default=0, help=DAYS_HELP)
21+
@click.option("--demo", is_flag=True, help="Demo mode with fake data (safe for recordings).")
2122
@click.pass_context
22-
def main(ctx: click.Context, days: int) -> None:
23+
def main(ctx: click.Context, days: int, demo: bool) -> None:
2324
"""agenttop — htop for AI coding agents.
2425
2526
Monitor token usage, costs, and workflows across Claude Code,
2627
Cursor, Kiro, and any AI tool via local proxy.
2728
"""
2829
ctx.ensure_object(dict)
2930
ctx.obj["days"] = days
31+
ctx.obj["demo"] = demo
3032
if ctx.invoked_subcommand is None:
31-
_launch_tui(days)
33+
_launch_tui(days, demo=demo)
3234

3335

3436
@main.command()
@@ -184,6 +186,7 @@ def analyze(days: int) -> None:
184186
@main.command()
185187
@click.option("--port", default=8420, help="Port for the web dashboard.")
186188
@click.option("--no-browser", is_flag=True, help="Don't auto-open browser.")
189+
@click.option("--demo", is_flag=True, help="Demo mode with fake data (safe for recordings).")
187190
@click.option(
188191
"--provider",
189192
type=click.Choice(
@@ -199,6 +202,7 @@ def analyze(days: int) -> None:
199202
def web(
200203
port: int,
201204
no_browser: bool,
205+
demo: bool,
202206
provider: str | None,
203207
model: str | None,
204208
) -> None:
@@ -209,6 +213,12 @@ def web(
209213

210214
_apply_cli_overrides(provider, model)
211215

216+
if demo:
217+
from agenttop.web.server import enable_demo_mode
218+
219+
enable_demo_mode()
220+
click.echo(click.style(" DEMO MODE", fg="magenta", bold=True) + " — fake data, safe for screenshots")
221+
212222
# Quick non-blocking LLM check — dashboard starts immediately
213223
# regardless of LLM availability. Optimizer gracefully degrades.
214224
config = load_config()
@@ -511,9 +521,9 @@ def _range_label(days: int) -> str:
511521
return labels.get(days, f"last {days} days")
512522

513523

514-
def _launch_tui(days: int = 0) -> None:
524+
def _launch_tui(days: int = 0, demo: bool = False) -> None:
515525
"""Launch the Textual TUI."""
516526
from agenttop.tui.app import AgentTop
517527

518-
app = AgentTop(days=days)
528+
app = AgentTop(days=days, demo=demo)
519529
app.run()

0 commit comments

Comments
 (0)