feat(intelligence): efficiency scoring, AI smell detection, burn rate forecasting

[Yagnasena1999]

Summary

Three new analytical capabilities built on top of the existing session data — all pure computation, no new required dependencies.

1. Agent Efficiency Score (backend/scoring.py)

A 0–100 score per session measuring how productively tokens were used:

score = output_ratio × error_penalty × turn_penalty × 100

• output_ratio = output tokens / total tokens (more output = more productive)
• error_penalty = 1 / (1 + errors × 0.15) — penalises tool failures
• turn_penalty = 1 / (1 + log(turns) × 0.18) — rewards concise prompts

Every session in /sessions now includes efficiency: 73.2 and efficiency_label: good | fair | poor.

2. AI Smell Detection (backend/smells.py)

Rule-based detection of 5 anti-patterns:

Smell	Threshold	Severity
context_rot	> 200 turns	warning → critical at 400
loop_trap	≥ 8 consecutive identical tool calls	critical
tool_thrash	≥ 25 reads of the same file	warning
high_error_rate	errors > 20% of turns	warning → critical at 40%
massive_session	> 2M total tokens	warning → critical at 5M

Every session includes smells: [{type, title, detail, severity}]. New endpoint GET /smells?project=<path> returns only sessions with warnings.

3. Burn Rate Forecasting (backend/forecast.py)

Linear projection of token usage toward monthly subscription limits:

• Daily token buckets over 60 days
• 7-day average vs prior-7-day average → trend detection (accelerating / steady / slowing)
• Projects tokens to end of month at current pace
• Calculates days-until-limit for Claude Pro (500M), Claude Max (2B), Codex Plus (200M), Copilot (100M)
• Exposed via GET /forecast?plan=claude_pro

Frontend (frontend/src/app/page.tsx)

• Efficiency badge: new ⚡ Score column in the Recent Activity table — colour-coded pill (green ≥70, amber ≥40, red <40)
• Smell indicator: ⚠ icon on session rows with smell count and critical/warning colour
• Burn Rate card in the dashboard sidebar:
  • Daily token rate (7d avg) + projected monthly total
  • Progress bar vs plan limit with urgency colouring
  • Alert when limit is ≤7 days away at current pace
  • Trend label with week-over-week percentage

No new required dependencies

All Python modules use stdlib only (math, datetime, collections). Lucide icons used are already in the project's icon set.

Test plan

• Start backend — confirm /sessions response includes efficiency and smells fields
• Hit GET /forecast — confirm JSON with daily_avg_7d, trend, days_until_limit
• Hit GET /smells — confirm only sessions with warnings are returned
• Hit GET /efficiency — confirm sessions sorted by efficiency score descending
• Open dashboard — confirm Score column appears with coloured badges
• Open dashboard — confirm ⚠ icon appears on sessions with high error rate or many turns
• Open dashboard — confirm Burn Rate card renders in right sidebar

🤖 Generated with Claude Code

[VasiHemanth]

Thanks for the big effort on the Intelligence Layer! This is a substantial set of new capabilities on top of the existing session data — efficiency scoring (0-100), AI smell detection (context rot, loop traps, tool thrashing, etc.), burn rate forecasting with plan limits and trends, Prompt DNA analysis, multi-model comparison, project health grades, recommendations, anomalies, and more. The approach (pure stdlib, in-memory post-scan enrichment, no new dependencies) aligns well with the project's local-first philosophy, and the README documentation for the new layer is excellent.

I reviewed this using our pr-validate process (which enforces our project rules from .claude/CLAUDE.md) and spun up the exact changes from the PR head in an isolated test environment (backend on :8010 with the new modules + routes, frontend on :3001 wired to it via NEXT_PUBLIC_API_PORT=8010) to exercise the new endpoints and UI live.

Key findings

Policy blocker (hard requirement):

• The PR title and several commits are conventional feat: / feat(intelligence):.
• UPDATE.json was not touched. Per our rules, every push/branch with at least one feat: commit that targets main must add (or update) a top-of-releases[] entry. This keeps the in-app "What's new" banner useful and is enforced by the pre-push hook.
• Without this change the hook will block the push. This is non-negotiable for feat: work.

Compatibility & integration work needed (this is why full validation will take time):

• The core new features (especially efficiency scoring and the 5 smells) depend on session fields that the existing parsers do not populate for most agents: turns, error_count, tool_calls_detail (with input hashes), and file_read_paths.
• As a result, in live testing many scores come back as degenerate defaults and most smells do not trigger. The advertised value of the Intelligence Layer won't be fully realized until we add enrichment for these fields during _scan_sessions_sync across the different agent sources (Claude, Codex, Copilot, Hermes, Grok, Antigravity, etc.). This is non-trivial work and will require coordinated changes.
• Hardcoded fetch("http://localhost:8000${url}") in the new intelligence page (model comparison filter). This completely bypasses the project's dynamic API base/port handling, lib/api.ts, token auth for remote/tailnet access, etc. It needs to go through the existing client.

Other observations:

• Very large single PR (18 files, ~191 kB diff, 14 new backend analysis modules + an 872-line monolithic frontend page). For reviewability, testing, and incremental shipping it would be much better split (e.g. core scoring + smells + enrichment first, then forecasting + trends, then the full UI + nav).
• A few smaller issues around edge cases, date arithmetic in forecasting, and consistency of session dict mutation.
• On the positive side: the new routes are clean and read-only, the UI direction looks promising, and the feature set (once the data model catches up) will be genuinely useful for understanding agent efficiency, catching problematic patterns, and forecasting spend.

Because this introduces so many new features and touches both the data model and UI, making everything properly compatible and robust is going to take some dedicated follow-up time (parser enrichment, integration fixes, tests, possibly splitting the work).

Suggested next steps

1. Add the required UPDATE.json entry at the top (newest first) describing the Intelligence Layer with concrete user benefits and an href to /intelligence.
2. Either split the PR or land the backend enrichment + core modules first.
3. Fix the hardcoded localhost URL and start addressing the missing session fields so the new capabilities actually produce useful output on real data.
4. Add basic tests for the pure analysis modules.

I'm happy to help review pieces, pair on the enrichment work, or re-run validation once updates are in. Let me know how you'd like to move forward.

(Full internal validation report with file:line details is available if needed.)

[VasiHemanth]

@Yagnasena1999

Tagging you on the review of this PR (full details in the previous comment: #85 (comment)).

Quick summary of what we found:

• Policy blocker: Multiple commits but no update. This is required by our project rules (see .claude/CLAUDE.md and the pre-push hook). The hook will block landing without it.
• Many new features (Intelligence Layer: efficiency scoring, AI smell detection, burn rate forecasting, Prompt DNA, model comparison, project health, recommendations, etc.). The implementation looks thoughtful (pure stdlib, no new deps).
• Compatibility work will take time: The new scoring and smell features rely on session data fields (, , , ) that most existing parsers do not populate. In live testing with the PR code, many of the advertised capabilities return degenerate/empty results. This will require non-trivial enrichment work across the agent parsers in .
• Hardcoded in the frontend intelligence page (bypasses our dynamic port/base/token handling).
• Large scope (18 files / 14 new modules + big new page) — would be easier to review/ship if split.

We're happy to help with the compatibility work, parser enrichment, or splitting the PR. Let us know how you'd like to proceed!

[VasiHemanth]

@Yagnasena1999

Tagging you on the review of this PR (full details in the previous comment: #85 (comment)).

Quick summary of what we found:

• Policy blocker: Multiple feat: commits but no UPDATE.json update. This is required by our project rules (see .claude/CLAUDE.md and the pre-push hook). The hook will block landing without it.
• Many new features (Intelligence Layer: efficiency scoring, AI smell detection, burn rate forecasting, Prompt DNA, model comparison, project health, recommendations, etc.). The implementation looks thoughtful (pure stdlib, no new deps).
• Compatibility work will take time: The new scoring and smell features rely on session data fields (turns, error_count, tool_calls_detail, file_read_paths) that most existing parsers do not populate. In live testing with the PR code, many of the advertised capabilities return degenerate/empty results. This will require non-trivial enrichment work across the agent parsers in backend/main.py.
• Hardcoded localhost:8000 in the frontend intelligence page (bypasses our dynamic port/base/token handling).
• Large scope (18 files / 14 new modules + big new page) — would be easier to review/ship if split.

We're happy to help with the compatibility work, parser enrichment, or splitting the PR. Let us know how you'd like to proceed!