feat: --demo mode + README rewrite

[vicarious11]

Summary

• --demo flag for both web and TUI — generates realistic fake data safe for LinkedIn recordings and screenshots
• README rewrite — minimal top (install + run in 3 lines), full architecture bottom

Demo mode

agenttop --demo          # TUI
agenttop web --demo      # web at localhost:8420

265 sessions across Claude/Cursor/Kiro/Codex/Copilot. 10 projects with handwritten prompts (trading engine, search infra, auth, UI components). Realistic cost distribution, work-hour clustering, weekday/weekend patterns. Deterministic — same screenshots every time.

Test plan

• 248 tests passing
• agenttop web --demo starts and shows fake data
• agenttop --demo TUI starts with fake data
• Real mode unchanged (no --demo flag = normal behavior)

🤖 Generated with Claude Code

[AbhilashSri]

@vicarious11

Code Review: PR #22 - agenttop (--demo mode + README rewrite)

Saksham bhai, solid work on this. The demo mode is a great addition for screenshots and recordings.

---

✅ What's Excellent

1. README Rewrite — Phenomenal

• Clean, concise top section: install + run in 3 lines
• Architecture diagram is clear and well-structured
• Sections are logically organized: what → install → run → data sources → architecture → API → config
• Lowercase headings style works well
• The "no telemetry" section is prominent and reassuring

2. Demo Mode Implementation (demo.py)

• Realistic fake data with weighted project distribution
• Handwritten prompts that feel like a real eng team's work (trading engine, auth, search infra)
• Deterministic output via seeded random — same screenshots every time
• Proper clustering: work hours (9-23), weekday/weekend patterns
• 265 sessions across 5 tools — good variety

3. CLI Integration

• Clean --demo flag propagation through TUI and web
• Visual feedback with magenta "DEMO MODE" banner
• Non-breaking — real mode unchanged when flag not set

4. Demo Mode Optimizer Result (server.py:_demo_analysis_result)

• Pre-built analysis with realistic scores and grades
• Good variety in strengths, anti-patterns, recommendations
• Cost forensics with project breakdown

---

⚠️ Issues Found

1. Demo Collector — Unused Import

src/agenttop/collectors/demo.py:14 imports Event but never uses it:

``\python
from agenttop.models import Event, Session, ToolName, ToolStats

`collect_events()` returns `[]` which is fine, but `Event` is unused.

**Fix:** Remove `Event` from the import.

---

**2. TUI Knowledge Graph — hasattr Pattern (Minor)**

`src/agenttop/tui/knowledge_graph.py:59`:

``\python
if hasattr(collector, "get_model_usage") and hasattr(collector, "get_daily_history"):

This is fragile duck-typing. Better to define a protocol or use isinstance checks against known types. Not blocking, but worth noting.

---

3. Demo Data hardcoded days_back=30 (Nitpick)

_make_sessions() defaults to 30 days but if user runs agenttop --demo --days 7, it still shows 30 days of data (just filters in get_stats). This is actually fine behavior for demo mode, but the parameter name is misleading.

---

🔴 CI Status

CI is failing on Python 3.10 — likely the unused Event import triggering ruff. Please check the full CI logs and fix.

---

📊 Code Quality Assessment

Aspect	Grade	Notes
Functionality	A	Demo mode works as intended
Code Quality	A	Clean, well-organized
Documentation	A+	README rewrite is excellent
CI	❌	Failing on 3.10

---

Overall Verdict

REQUEST CHANGES — Please fix:

1. Remove unused Event import in demo.py
2. Ensure CI passes

The demo mode is a brilliant addition for screenshots. The README rewrite makes the project much more approachable. Once the import issue is fixed and CI passes, this is good to merge.

---

Grade: A- (only CI + minor import holding it back from A+)

Great work otherwise! 🚀

[AbhilashSri]

@vicarious11

Code Review: PR #22 - agenttop (--demo mode + README rewrite)

Saksham bhai, solid work on this. The demo mode is a great addition for screenshots and recordings.

---

✅ What's Excellent

1. README Rewrite — Phenomenal

• Clean, concise top section: install + run in 3 lines
• Architecture diagram is clear and well-structured
• Sections are logically organized: what → install → run → data sources → architecture → API → config
• Lowercase headings style works well
• The "no telemetry" section is prominent and reassuring

2. Demo Mode Implementation (demo.py)

• Realistic fake data with weighted project distribution
• Handwritten prompts that feel like a real eng team's work (trading engine, auth, search infra)
• Deterministic output via seeded random — same screenshots every time
• Proper clustering: work hours (9-23), weekday/weekend patterns
• 265 sessions across 5 tools — good variety

3. CLI Integration

• Clean --demo flag propagation through TUI and web
• Visual feedback with magenta "DEMO MODE" banner
• Non-breaking — real mode unchanged when flag not set

4. Demo Mode Optimizer Result (server.py:_demo_analysis_result)

• Pre-built analysis with realistic scores and grades
• Good variety in strengths, anti-patterns, recommendations
• Cost forensics with project breakdown

---

⚠️ Issues Found

1. Demo Collector — Unused Import

src/agenttop/collectors/demo.py:14 imports Event but never uses it:

``\python
from agenttop.models import Event, Session, ToolName, ToolStats

`collect_events()` returns `[]` which is fine, but `Event` is unused.

**Fix:** Remove `Event` from the import.

---

**2. TUI Knowledge Graph — hasattr Pattern (Minor)**

`src/agenttop/tui/knowledge_graph.py:59`:

``\python
if hasattr(collector, "get_model_usage") and hasattr(collector, "get_daily_history"):
``
This is fragile duck-typing. Better to define a protocol or use `isinstance` checks against known types. Not blocking, but worth noting.

---

**3. Demo Data hardcoded days_back=30 (Nitpick)**

`_make_sessions()` defaults to 30 days but if user runs `agenttop --demo --days 7`, it still shows 30 days of data (just filters in `get_stats`). This is actually fine behavior for demo mode, but the parameter name is misleading.

---

### 🔴 CI Status

**CI is failing on Python 3.10** — likely the unused `Event` import triggering ruff. Please check the full CI logs and fix.

---

### 📊 Code Quality Assessment

| Aspect | Grade | Notes |
|--------|-------|-------|
| Functionality | A | Demo mode works as intended |
| Code Quality | A | Clean, well-organized |
| Documentation | A+ | README rewrite is excellent |
| CI | ❌ | Failing on 3.10 |

---

### Overall Verdict

**REQUEST CHANGES** — Please fix:
1. Remove unused `Event` import in `demo.py`
2. Ensure CI passes

The demo mode is a brilliant addition for screenshots. The README rewrite makes the project much more approachable. Once the import issue is fixed and CI passes, this is good to merge.

---

**Grade: A-** (only CI + minor import holding it back from A+)

Great work otherwise! 🚀

[AbhilashSri]

LGTM, full power!