Claude Code Lens

Because cc-lens reads local Claude Code files directly, the accuracy of the displayed data is subject to the following constraints:

• Cost Estimates: Cost values are estimates based on lib/pricing.ts and are not official billing records. They may lag behind actual provider pricing changes.
• Metadata Availability: Older sessions might lack metadata for model, usage, branch, or compaction.
• Inferred Data: Session duration is inferred from timestamps in local files rather than being explicitly recorded.
• Project Metrics: Language, line, and file-change counts are dependent on what Claude Code has recorded in its local logs.

The cc-lens security model is built on the principle of local-first operation. Key privacy guarantees include:

• No Telemetry: The application does not collect usage data.
• No Accounts/Backend: There is no account system or hosted backend.
• No API Keys: No external API keys are required for operation.
• Local Data Residency: All Claude Code data remains on your local machine.
• Default Local Binding: The CLI binds to 127.0.0.1 by default to prevent external access.
• Opt-in LAN Access: To expose the dashboard on your local network, you must explicitly use the --host 0.0.0.0 flag or set the CC_LENS_HOST=0.0.0.0 environment variable.

For teams using Claude Code, cc-lens provides visibility into usage patterns:

• Team Adoption View: Shows per-member usage of features like plan mode, agents, skills, and MCP. It includes cost per session and 'idle' badges to help identify efficient workflows.
• MCP Governance: Provides an inventory of MCP (Model Context Protocol) servers used across the team, showing which servers are wired up and who is using them.

The cc-lens dashboard provides detailed financial insights into your Claude Code usage via the costs page:

• Monthly Spend: View your total estimated API-equivalent cost for the month.
• Breakdown: See costs categorized by specific models and individual projects.
• Cache Savings: View a specific panel showing how much money you saved through context caching (the difference between full input pricing and cached input pricing).

cc-lens analyzes your local history to provide high-level patterns and statistics:

• Insights: Identifies patterns such as un-reused cache, model overpayment, or compaction patterns.
• Tool Usage: Ranks tools used by the agent, categorized by type (e.g., Bash, file edits) and including breakdowns for MCP (Model Context Protocol) servers and slash-commands.
• Activity Heatmap: A GitHub-style heatmap showing session frequency, streaks, and peak usage hours.

cc-lens 0.4.0 provides tools to audit and control Claude Code costs:

• Insights: Detects waste such as low cache hit rates, using expensive models for simple tasks, or compaction thrash. Each insight includes an estimated dollar figure.
• Budgets: Allows you to set a monthly budget. The tool provides pacing projections and spend-spike detection to alert you if a single day's spend jumps significantly above your normal usage (e.g., due to a runaway agent loop).

When using the import and export features, be aware of these security and functional limitations:

• Sensitive Data: Exported .cclens.json files can contain sensitive local workflow data. Always treat these files as private.
• Import Behavior: Importing data is a preview-only operation. It does not write or merge sessions back into your ~/.claude/ directory.
• Redaction: There is currently no support for redacted exports.

You can review exactly what the Claude Code agent did during past sessions using the replay feature:

• Session Recording: Replay past sessions with rendered markdown and grouped tool calls.
• Granular Detail: View tokens used and cost incurred per individual turn.
• Context Events: See where compaction events occurred inline within the session history.
• Navigation: Scrub back through the timeline to inspect specific agent actions.

By default, cc-lens reads data from the standard Claude Code directory. It tracks the following file patterns:

• ~/.claude/projects/<slug>/*.jsonl
• ~/.claude/stats-cache.json
• ~/.claude/usage-data/session-meta/
• ~/.claude/history.jsonl
• ~/.claude/todos/
• ~/.claude/plans/
• ~/.claude/projects/*/memory/
• ~/.claude/settings.json

The cc-lens managed service uses a Postgres schema (via Drizzle) to track organizational usage and developer activity. The data is split into two main layers:

• Deep-dive layer (sessions): Contains detailed session data (tokens, cost, tool usage, model usage) typically populated via push operations.
• Real-time layer (usage_daily): Contains aggregated daily metrics (cost, tokens, sessions, commits, etc.) populated via OTLP deltas and nightly rollups.

Key entities include orgs, users, org_members, ingest_tokens, devs, and cc_versions.

The managed version of cc-lens is a multi-tenant hub designed for teams. Unlike the OSS version which uses file-based storage, the managed version uses a centralized Postgres database to store org-scoped data.

Key components for each customer organization:

• A unique push token for data ingestion.
• An OTLP ingestion endpoint for metrics.
• A hosted team dashboard for visibility and governance.

Data Flow Architecture:

1. Member machines / CI send data via cc-lens push (HTTPS push) or OTel (OTLP http/json).
2. The Managed Hub (Next.js app) receives data at /api/team/push (using the org token) and /api/otel/v1/metrics.
3. Data is stored in Postgres with org_id scoping on every row.
4. Backups are performed via nightly pg_dump to an object store.