### Run cc-lens from source

Source: https://github.com/arindam200/cc-lens/blob/main/README.md

Install dependencies and start the development server for local development.

```bash
npm install
npm run dev
```

--------------------------------

### Build and start cc-lens

Source: https://github.com/arindam200/cc-lens/blob/main/README.md

Compile the project and start the production server.

```bash
npm run build
npm start
```

--------------------------------

### Launch Dashboard via CLI

Source: https://context7.com/arindam200/cc-lens/llms.txt

Starts the Next.js dashboard server and opens the browser automatically without requiring manual installation.

```bash
# Run directly with npx - no installation required
npx cc-lens

# The CLI will:
# 1. Print an ASCII banner
# 2. Set up dependencies on first run (~/.cc-lens/)
# 3. Find an available port starting from 3000
# 4. Launch the dashboard and open your browser
```

--------------------------------

### Run cc-lens via npx

Source: https://github.com/arindam200/cc-lens/blob/main/README.md

Execute the dashboard directly without installation using npx.

```bash
npx cc-lens
```

--------------------------------

### Retrieve Settings API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Fetches current Claude Code configuration, including themes, models, installed skills, and plugins.

```bash
curl http://localhost:3000/api/settings
```

--------------------------------

### Settings API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves Claude Code settings including installed skills, plugins, and storage usage.

```APIDOC
## GET /api/settings

### Description
Retrieves Claude Code settings including installed skills, plugins, and storage usage.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **settings** (object) - Configuration settings for Claude Code.
- **storageBytes** (integer) - Current storage usage in bytes.
- **skills** (array) - List of installed skills.
- **plugins** (array) - List of installed plugins.

#### Response Example
```json
{
  "settings": {
    "theme": "dark",
    "model": "claude-opus-4-6",
    "autoCompact": true
  },
  "storageBytes": 524288000,
  "skills": [
    {
      "name": "commit-reviewer",
      "description": "Reviews git commits for best practices",
      "triggers": "When user asks to review commits or PRs",
      "hasSkillMd": true
    }
  ],
  "plugins": [
    {
      "id": "github-integration",
      "scope": "global",
      "version": "1.2.0",
      "installedAt": "2024-01-10T08:00:00Z"
    }
  ]
}
```
```

--------------------------------

### List all projects with aggregated stats

Source: https://context7.com/arindam200/cc-lens/llms.txt

Use this endpoint to get a list of all projects with their aggregated statistics, including session counts, token usage, languages, and git branch activity. The response provides a high-level overview of project data.

```bash
curl http://localhost:3000/api/projects
```

```json
{
  "projects": [
    {
      "slug": "-Users-dev-my-project",
      "project_path": "/Users/dev/my-project",
      "display_name": "my-project",
      "session_count": 45,
      "total_messages": 890,
      "total_duration_minutes": 1250.5,
      "total_lines_added": 3500,
      "total_lines_removed": 1200,
      "total_files_modified": 89,
      "git_commits": 25,
      "estimated_cost": 125.50,
      "input_tokens": 4500000,
      "output_tokens": 850000,
      "languages": { "typescript": 450, "javascript": 120 },
      "tool_counts": { "Read": 1200, "Edit": 450, "Bash": 180 },
      "last_active": "2024-01-15T10:30:00Z",
      "first_active": "2023-12-01T08:00:00Z",
      "uses_mcp": true,
      "uses_task_agent": true,
      "branches": ["main", "feature/auth", "fix/bug-123"]
    }
  ]
}
```

--------------------------------

### GET /api/sessions

Source: https://context7.com/arindam200/cc-lens/llms.txt

Lists all sessions with enriched metadata including estimated costs, tool usage, and git branches.

```APIDOC
## GET /api/sessions

### Description
Lists all sessions with enriched metadata including estimated costs, tool usage, git branches, and optional facet analysis.

### Method
GET

### Endpoint
/api/sessions

### Response
#### Success Response (200)
- **sessions** (array) - List of session objects containing metadata.
- **total** (number) - Total count of sessions.

#### Response Example
{
  "sessions": [
    {
      "session_id": "abc123-def456",
      "project_path": "/Users/dev/my-project",
      "start_time": "2024-01-15T10:30:00Z",
      "duration_minutes": 45.5,
      "user_message_count": 25,
      "assistant_message_count": 24,
      "input_tokens": 150000,
      "output_tokens": 35000,
      "cache_read_input_tokens": 80000,
      "tool_counts": { "Read": 45, "Edit": 12, "Bash": 8, "Grep": 15 },
      "first_prompt": "Help me refactor the authentication module...",
      "uses_task_agent": true,
      "uses_mcp": false,
      "estimated_cost": 3.25,
      "slug": "my-project",
      "version": "1.0.28",
      "git_branch": "feature/auth-refactor",
      "has_compaction": true,
      "has_thinking": true,
      "facet": {
        "brief_summary": "Refactored auth module with improved error handling",
        "outcome": "success"
      }
    }
  ],
  "total": 156
}
```

--------------------------------

### Get Activity Analytics

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves daily activity, hourly distribution, day-of-week analysis, and streak tracking. Use this endpoint to monitor user engagement and identify peak activity times.

```bash
# Get activity analytics
curl http://localhost:3000/api/activity
```

```json
# Response:
{
  "daily_activity": [
    { "date": "2024-01-15", "messageCount": 150, "sessionCount": 12, "toolCallCount": 890 }
  ],
  "hour_counts": [
    { "hour": 0, "count": 5 },
    { "hour": 9, "count": 145 },
    { "hour": 14, "count": 220 },
    { "hour": 17, "count": 180 }
  ],
  "dow_counts": [
    { "day": "Sun", "count": 25 },
    { "day": "Mon", "count": 180 },
    { "day": "Tue", "count": 195 },
    { "day": "Wed", "count": 210 },
    { "day": "Thu", "count": 185 },
    { "day": "Fri", "count": 160 },
    { "day": "Sat", "count": 45 }
  ],
  "streaks": { "current": 12, "longest": 45 },
  "most_active_day": "2024-01-10",
  "most_active_day_msgs": 320,
  "total_active_days": 65
}
```

--------------------------------

### Get detailed project info

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieve detailed information for a specific project, including session breakdowns, tool counts, cost per session, and branch information. This endpoint requires the project's slug as a path parameter.

```bash
curl http://localhost:3000/api/projects/-Users-dev-my-project
```

--------------------------------

### Get comprehensive cost analytics

Source: https://context7.com/arindam200/cc-lens/llms.txt

This endpoint provides a detailed breakdown of costs across all models and sessions. It includes total costs, savings, model-specific token usage, cache efficiency metrics, and daily cost trends.

```bash
curl http://localhost:3000/api/costs
```

```json
{
  "total_cost": 245.75,
  "total_savings": 68.30,
  "models": [
    {
      "model": "claude-opus-4-6",
      "input_tokens": 8500000,
      "output_tokens": 1500000,
      "cache_write_tokens": 450000,
      "cache_read_tokens": 3200000,
      "estimated_cost": 220.50,
      "cache_savings": 62.40,
      "cache_hit_rate": 0.274
    },
    {
      "model": "claude-sonnet-4-6",
      "input_tokens": 2000000,
      "output_tokens": 400000,
      "cache_write_tokens": 100000,
      "cache_read_tokens": 800000,
      "estimated_cost": 25.25,
      "cache_savings": 5.90,
      "cache_hit_rate": 0.286
    }
  ],
  "daily": [
    { "date": "2024-01-15", "costs": { "claude-opus-4-6": 12.50 }, "total": 12.50 },
    { "date": "2024-01-14", "costs": { "claude-opus-4-6": 8.25 }, "total": 8.25 }
  ],
  "by_project": [
    {
      "slug": "/Users/dev/my-project",
      "display_name": "my-project",
      "estimated_cost": 125.50,
      "input_tokens": 4500000,
      "output_tokens": 850000
    }
  ]
}
```

--------------------------------

### Get tool usage analytics

Source: https://context7.com/arindam200/cc-lens/llms.txt

This endpoint provides analytics on tool usage across all sessions. It categorizes tools by type and offers insights into MCP server breakdowns and feature adoption rates.

```bash
curl http://localhost:3000/api/tools
```

--------------------------------

### GET /api/sessions/:id/replay

Source: https://context7.com/arindam200/cc-lens/llms.txt

Parses a session's JSONL file and returns the full conversation replay with turn-by-turn details.

```APIDOC
## GET /api/sessions/:id/replay

### Description
Parses a session's JSONL file and returns the full conversation replay with turn-by-turn details including tool calls, token usage per turn, compaction events, and thinking blocks.

### Method
GET

### Endpoint
/api/sessions/:id/replay

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
```

--------------------------------

### GET /api/stats

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves aggregated statistics including total costs, token usage, cache efficiency, and activity metrics.

```APIDOC
## GET /api/stats

### Description
Retrieves aggregated statistics including total costs, token usage, cache efficiency, and activity metrics. Combines data from stats-cache.json with live session analysis.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **stats** (object) - Aggregated usage data including daily activity, token usage by model, and model-specific metrics.
- **computed** (object) - Calculated totals including total cost, cache savings, and session metrics.

#### Response Example
{
  "stats": {
    "version": 1,
    "lastComputedDate": "2024-01-15",
    "dailyActivity": [
      { "date": "2024-01-15", "messageCount": 150, "sessionCount": 12, "toolCallCount": 890 }
    ],
    "tokensByDate": [
      { "date": "2024-01-15", "tokensByModel": { "claude-opus-4-6": 500000 } }
    ],
    "modelUsage": {
      "claude-opus-4-6": {
        "inputTokens": 1500000,
        "outputTokens": 250000,
        "cacheReadInputTokens": 800000,
        "cacheCreationInputTokens": 100000,
        "costUSD": 45.50
      }
    },
    "totalSessions": 156,
    "totalMessages": 2340
  },
  "computed": {
    "totalCost": 45.50,
    "totalCacheSavings": 12.30,
    "totalTokens": 2650000,
    "totalToolCalls": 8900,
    "activeDays": 45,
    "avgSessionMinutes": 23.5,
    "sessionsThisMonth": 42,
    "sessionsThisWeek": 15,
    "storageBytes": 524288000,
    "sessionCount": 156
  }
}
```

--------------------------------

### Get Recent Command History

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves Claude Code command history from `~/.claude/history.jsonl`. Supports pagination with a default of 200 entries, extendable up to 10000.

```bash
# Get recent command history (default 200 entries)
curl http://localhost:3000/api/history
```

```bash
# Get more history entries (max 10000)
curl "http://localhost:3000/api/history?limit=500"
```

```json
# Response:
{
  "history": [
    {
      "display": "Help me debug the authentication flow",
      "timestamp": 1705312200000,
      "project": "/Users/dev/my-project",
      "sessionId": "abc123-def456"
    }
  ]
}
```

--------------------------------

### Preview Import API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Performs a dry-run import of exported data to preview changes without modifying the filesystem.

```bash
curl -X POST http://localhost:3000/api/import \
  -H "Content-Type: application/json" \
  -d @exported-data.json
```

--------------------------------

### Import API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Previews import of exported data, showing which sessions would be added. Note: actual file writing is not implemented to prevent data corruption.

```APIDOC
## POST /api/import

### Description
Previews import of exported data, showing which sessions would be added. Note: actual file writing is not implemented to prevent data corruption.

### Method
POST

### Endpoint
/api/import

### Parameters
#### Request Body
- **exported-data.json** (file) - The JSON file containing exported data.

### Request Example
```json
@exported-data.json
```

### Response
#### Success Response (200)
- **total_in_export** (integer) - Total number of items in the export file.
- **already_present** (integer) - Number of items already present in the system.
- **new_sessions** (integer) - Number of new sessions that would be added.
- **sessions_to_add** (array) - Array of new session metadata to be added.

#### Response Example
```json
{
  "total_in_export": 156,
  "already_present": 120,
  "new_sessions": 36,
  "sessions_to_add": [ /* Array of new SessionMeta */ ]
}
```
```

--------------------------------

### List All Saved Plans

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves saved plan files from `~/.claude/plans/` directory. Returns markdown content for each plan.

```bash
# List all plans
curl http://localhost:3000/api/plans
```

```json
# Response:
{
  "plans": [
    {
      "path": "/Users/dev/.claude/plans/refactor-auth.md",
      "name": "refactor-auth",
      "content": "# Auth Refactoring Plan\n\n## Phase 1: Analysis\n- Review current implementation...",
      "mtime": "2024-01-15T09:00:00Z"
    }
  ]
}
```

--------------------------------

### List and Retrieve Sessions via API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Lists all recorded sessions with metadata or retrieves details for a specific session ID.

```bash
# List all sessions with full metadata
curl http://localhost:3000/api/sessions

# Response:
{
  "sessions": [
    {
      "session_id": "abc123-def456",
      "project_path": "/Users/dev/my-project",
      "start_time": "2024-01-15T10:30:00Z",
      "duration_minutes": 45.5,
      "user_message_count": 25,
      "assistant_message_count": 24,
      "input_tokens": 150000,
      "output_tokens": 35000,
      "cache_read_input_tokens": 80000,
      "tool_counts": { "Read": 45, "Edit": 12, "Bash": 8, "Grep": 15 },
      "first_prompt": "Help me refactor the authentication module...",
      "uses_task_agent": true,
      "uses_mcp": false,
      "estimated_cost": 3.25,
      "slug": "my-project",
      "version": "1.0.28",
      "git_branch": "feature/auth-refactor",
      "has_compaction": true,
      "has_thinking": true,
      "facet": {
        "brief_summary": "Refactored auth module with improved error handling",
        "outcome": "success"
      }
    }
  ],
  "total": 156
}

# Get a specific session by ID
curl http://localhost:3000/api/sessions/abc123-def456
```

--------------------------------

### List All Todos

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves todo lists from `~/.claude/todos/` directory, including their status information.

```bash
# List all todos
curl http://localhost:3000/api/todos
```

--------------------------------

### Plans API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves saved plan files from `~/.claude/plans/` directory as markdown content.

```APIDOC
## GET /api/plans

### Description
Retrieves all saved plan files.

### Method
GET

### Endpoint
/api/plans

### Response
#### Success Response (200)
- **plans** (array) - An array of plan objects, each containing path, name, content, and mtime.

#### Response Example
{
  "plans": [
    {
      "path": "/Users/dev/.claude/plans/refactor-auth.md",
      "name": "refactor-auth",
      "content": "# Auth Refactoring Plan\n\n## Phase 1: Analysis\n- Review current implementation...",
      "mtime": "2024-01-15T09:00:00Z"
    }
  ]
}
```

--------------------------------

### Pricing Estimation Utilities

Source: https://context7.com/arindam200/cc-lens/llms.txt

Calculates costs based on token usage and evaluates cache efficiency for various Claude models.

```typescript
import {
  estimateCostFromUsage,
  estimateTotalCostFromModel,
  cacheEfficiency,
  PRICING
} from '@/lib/pricing'

// Current pricing per million tokens
const pricing = {
  'claude-opus-4-6': {
    input: 15.00 / 1_000_000,      // $15/MTok
    output: 75.00 / 1_000_000,     // $75/MTok
    cacheWrite: 18.75 / 1_000_000, // $18.75/MTok
    cacheRead: 1.50 / 1_000_000    // $1.50/MTok
  },
  'claude-sonnet-4-6': {
    input: 3.00 / 1_000_000,
    output: 15.00 / 1_000_000,
    cacheWrite: 3.75 / 1_000_000,
    cacheRead: 0.30 / 1_000_000
  },
  'claude-haiku-4-5': {
    input: 0.80 / 1_000_000,
    output: 4.00 / 1_000_000,
    cacheWrite: 1.00 / 1_000_000,
    cacheRead: 0.08 / 1_000_000
  }
}

// Calculate cost from turn usage
const turnCost = estimateCostFromUsage('claude-opus-4-6', {
  input_tokens: 5000,
  output_tokens: 1200,
  cache_creation_input_tokens: 500,
  cache_read_input_tokens: 3000
})
// Result: ~0.165 USD

// Calculate cache efficiency
const efficiency = cacheEfficiency('claude-opus-4-6', {
  inputTokens: 100000,
  outputTokens: 25000,
  cacheReadInputTokens: 80000,
  cacheCreationInputTokens: 10000,
  costUSD: 0,
  webSearchRequests: 0
})
// Result: { savedUSD: 1.08, hitRate: 0.444, wouldHavePaidUSD: 5.56 }
```

--------------------------------

### Accessing Claude Code Data with Claude Reader

Source: https://context7.com/arindam200/cc-lens/llms.txt

Demonstrates how to import and use the library functions to read stats, sessions, project slugs, and JSONL files from the local ~/.claude/ directory.

```typescript
import {
  claudePath,
  readStatsCache,
  getSessions,
  readSessionMeta,
  listProjectSlugs,
  listProjectJSONLFiles,
  readJSONLLines,
  findSessionJSONL,
  readPlans,
  readTodos,
  readHistory,
  readMemories,
  readSettings,
  readSkills,
  readInstalledPlugins,
  getClaudeStorageBytes
} from '@/lib/claude-reader'

// Build paths within ~/.claude/
claudePath('projects', 'my-project', 'session.jsonl')
// '/Users/dev/.claude/projects/my-project/session.jsonl'

// Read stats cache
const stats = await readStatsCache()  // StatsCache | null

// Get all sessions (prefers JSONL, falls back to session-meta)
const sessions = await getSessions()  // SessionMeta[]

// List all project directory slugs
const slugs = await listProjectSlugs()  // ['project-a', 'project-b']

// Read JSONL file line by line
await readJSONLLines('/path/to/session.jsonl', (line) => {
  if (line.type === 'assistant') {
    console.log('Model:', line.message?.model)
    console.log('Tokens:', line.message?.usage?.input_tokens)
  }
})

// Find session JSONL by ID
const jsonlPath = await findSessionJSONL('abc123-def456')
// '/Users/dev/.claude/projects/my-project/abc123-def456.jsonl'

// Get total storage size
const bytes = await getClaudeStorageBytes()  // 524288000
```

--------------------------------

### Todos API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves todo lists from `~/.claude/todos/` directory with status information.

```APIDOC
## GET /api/todos

### Description
Retrieves all todo lists.

### Method
GET

### Endpoint
/api/todos

### Response
#### Success Response (200)
- **todos** (array) - An array of todo objects, each containing file, projectSlug, projectPath, name, type, description, body, mtime, and isIndex. (Note: The actual structure of the todos response is not fully detailed in the provided text, this is an inferred structure based on similar endpoints.)
```

--------------------------------

### Projects API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Aggregates session data by project, providing summaries including total costs, session counts, tool usage, languages, and git branch activity.

```APIDOC
## GET /api/projects

### Description
Lists all projects with aggregated statistics.

### Method
GET

### Endpoint
/api/projects

### Response
#### Success Response (200)
- **projects** (array) - An array of project objects, each containing aggregated statistics.
  - **slug** (string) - Unique identifier for the project.
  - **project_path** (string) - The file system path to the project.
  - **display_name** (string) - The human-readable name of the project.
  - **session_count** (integer) - The total number of sessions for the project.
  - **total_messages** (integer) - The total number of messages across all sessions.
  - **total_duration_minutes** (number) - The total duration of all sessions in minutes.
  - **total_lines_added** (integer) - Total lines of code added.
  - **total_lines_removed** (integer) - Total lines of code removed.
  - **total_files_modified** (integer) - Total number of files modified.
  - **git_commits** (integer) - Total number of git commits.
  - **estimated_cost** (number) - The estimated cost associated with the project.
  - **input_tokens** (integer) - Total input tokens used.
  - **output_tokens** (integer) - Total output tokens generated.
  - **languages** (object) - An object detailing language usage counts.
    - **[language_name]** (integer) - Count for a specific programming language.
  - **tool_counts** (object) - An object detailing tool usage counts.
    - **[tool_name]** (integer) - Count for a specific tool.
  - **last_active** (string) - Timestamp of the last activity in the project.
  - **first_active** (string) - Timestamp of the first activity in the project.
  - **uses_mcp** (boolean) - Indicates if MCP (Multi-context Processing) is used.
  - **uses_task_agent** (boolean) - Indicates if a task agent is used.
  - **branches** (array) - An array of git branch names associated with the project.

### Request Example
```bash
curl http://localhost:3000/api/projects
```

### Response Example
```json
{
  "projects": [
    {
      "slug": "-Users-dev-my-project",
      "project_path": "/Users/dev/my-project",
      "display_name": "my-project",
      "session_count": 45,
      "total_messages": 890,
      "total_duration_minutes": 1250.5,
      "total_lines_added": 3500,
      "total_lines_removed": 1200,
      "total_files_modified": 89,
      "git_commits": 25,
      "estimated_cost": 125.50,
      "input_tokens": 4500000,
      "output_tokens": 850000,
      "languages": { "typescript": 450, "javascript": 120 },
      "tool_counts": { "Read": 1200, "Edit": 450, "Bash": 180 },
      "last_active": "2024-01-15T10:30:00Z",
      "first_active": "2023-12-01T08:00:00Z",
      "uses_mcp": true,
      "uses_task_agent": true,
      "branches": ["main", "feature/auth", "fix/bug-123"]
    }
  ]
}
```
```

```APIDOC
## GET /api/projects/{slug}

### Description
Retrieves detailed information for a specific project, including a breakdown of sessions.

### Method
GET

### Endpoint
/api/projects/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the project to retrieve.

### Response
#### Success Response (200)
- The response includes detailed project information, similar to the list endpoint, but may also include session-specific breakdowns, tool counts, cost by session, and branches.

### Request Example
```bash
curl http://localhost:3000/api/projects/-Users-dev-my-project
```
```

--------------------------------

### Retrieve Statistics via API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Fetches aggregated metrics including costs, token usage, and cache efficiency from the local stats cache.

```bash
# Get comprehensive stats overview
curl http://localhost:3000/api/stats

# Response structure:
{
  "stats": {
    "version": 1,
    "lastComputedDate": "2024-01-15",
    "dailyActivity": [
      { "date": "2024-01-15", "messageCount": 150, "sessionCount": 12, "toolCallCount": 890 }
    ],
    "tokensByDate": [
      { "date": "2024-01-15", "tokensByModel": { "claude-opus-4-6": 500000 } }
    ],
    "modelUsage": {
      "claude-opus-4-6": {
        "inputTokens": 1500000,
        "outputTokens": 250000,
        "cacheReadInputTokens": 800000,
        "cacheCreationInputTokens": 100000,
        "costUSD": 45.50
      }
    },
    "totalSessions": 156,
    "totalMessages": 2340
  },
  "computed": {
    "totalCost": 45.50,
    "totalCacheSavings": 12.30,
    "totalTokens": 2650000,
    "totalToolCalls": 8900,
    "activeDays": 45,
    "avgSessionMinutes": 23.5,
    "sessionsThisMonth": 42,
    "sessionsThisWeek": 15,
    "storageBytes": 524288000,
    "sessionCount": 156
  }
}
```

--------------------------------

### Activity API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Provides activity metrics including daily patterns, hourly distribution, day-of-week analysis, and streak tracking for gamification.

```APIDOC
## GET /api/activity

### Description
Retrieves activity analytics data.

### Method
GET

### Endpoint
/api/activity

### Response
#### Success Response (200)
- **daily_activity** (array) - Daily activity metrics including date, messageCount, sessionCount, and toolCallCount.
- **hour_counts** (array) - Count of activities per hour.
- **dow_counts** (array) - Count of activities per day of the week.
- **streaks** (object) - Current and longest streaks.
- **most_active_day** (string) - The date of the most active day.
- **most_active_day_msgs** (integer) - The number of messages on the most active day.
- **total_active_days** (integer) - The total number of active days.

#### Response Example
{
  "daily_activity": [
    { "date": "2024-01-15", "messageCount": 150, "sessionCount": 12, "toolCallCount": 890 }
  ],
  "hour_counts": [
    { "hour": 0, "count": 5 },
    { "hour": 9, "count": 145 },
    { "hour": 14, "count": 220 },
    { "hour": 17, "count": 180 }
  ],
  "dow_counts": [
    { "day": "Sun", "count": 25 },
    { "day": "Mon", "count": 180 },
    { "day": "Tue", "count": 195 },
    { "day": "Wed", "count": 210 },
    { "day": "Thu", "count": 185 },
    { "day": "Fri", "count": 160 },
    { "day": "Sat", "count": 45 }
  ],
  "streaks": { "current": 12, "longest": 45 },
  "most_active_day": "2024-01-10",
  "most_active_day_msgs": 320,
  "total_active_days": 65
}
```

--------------------------------

### Tool Categorization Utilities

Source: https://context7.com/arindam200/cc-lens/llms.txt

Provides functions to categorize tools, detect MCP tools, and format display names for analytics.

```typescript
import {
  categorizeTool,
  isMcpTool,
  parseMcpTool,
  toolDisplayName,
  TOOL_CATEGORIES,
  CATEGORY_COLORS
} from '@/lib/tool-categories'

// Built-in tool categories
const categories = {
  'file-io': ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'NotebookEdit'],
  'shell': ['Bash'],
  'agent': ['Task', 'TaskCreate', 'TaskUpdate', 'TaskList', 'TaskOutput'],
  'web': ['WebSearch', 'WebFetch'],
  'planning': ['EnterPlanMode', 'ExitPlanMode', 'AskUserQuestion'],
  'todo': ['TodoWrite'],
  'skill': ['Skill', 'ToolSearch'],
  'mcp': ['mcp__*']  // Auto-detected
}

// Categorize a tool
categorizeTool('Read')      // 'file-io'
categorizeTool('mcp__github__create_pr')  // 'mcp'

// Parse MCP tool names
isMcpTool('mcp__github__create_pr')  // true
parseMcpTool('mcp__github__create_pr')
// { server: 'github', tool: 'create_pr' }

// Display name formatting
toolDisplayName('mcp__github__create_pr')  // 'github · create_pr'
```

--------------------------------

### Retrieve Session Replay via API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Returns the full conversation history for a specific session, including tool calls and token usage per turn.

```bash
# Get full session replay with all turns
curl http://localhost:3000/api/sessions/abc123-def456/replay
```

--------------------------------

### Tools API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Analyzes tool usage patterns across all sessions, categorizing tools by type and providing MCP server breakdowns, feature adoption rates, and version history.

```APIDOC
## GET /api/tools

### Description
Retrieves analytics on tool usage across all sessions.

### Method
GET

### Endpoint
/api/tools

### Response
#### Success Response (200)
- The response typically includes data on tool usage counts, categorization, MCP server usage, feature adoption, and version history. Specific fields are not detailed in the provided text but would be expected here.

### Request Example
```bash
curl http://localhost:3000/api/tools
```
```

--------------------------------

### Pricing Utilities

Source: https://context7.com/arindam200/cc-lens/llms.txt

Provides accurate cost estimation based on Anthropic's official pricing tiers for different Claude models.

```APIDOC
## Pricing Utilities

### Description
The pricing module provides accurate cost estimation based on Anthropic's official pricing tiers for different Claude models.

### Functions
- **estimateCostFromUsage(model: string, usage: object): number**
  Estimates the cost from turn usage.
  - **model** (string) - The Claude model used (e.g., 'claude-opus-4-6').
  - **usage** (object) - Object containing token usage details:
    - **input_tokens** (integer)
    - **output_tokens** (integer)
    - **cache_creation_input_tokens** (integer)
    - **cache_read_input_tokens** (integer)
  - Returns the estimated cost in USD.

- **cacheEfficiency(model: string, usage: object): object**
  Calculates cache efficiency.
  - **model** (string) - The Claude model used.
  - **usage** (object) - Object containing usage details:
    - **inputTokens** (integer)
    - **outputTokens** (integer)
    - **cacheReadInputTokens** (integer)
    - **cacheCreationInputTokens** (integer)
    - **costUSD** (number)
    - **webSearchRequests** (integer)
  - Returns an object with efficiency metrics:
    - **savedUSD** (number)
    - **hitRate** (number)
    - **wouldHavePaidUSD** (number)

### Constants
- **PRICING**: Object containing pricing tiers for different models.
  - Example for 'claude-opus-4-6':
    ```json
    {
      "input": 15.00 / 1_000_000,
      "output": 75.00 / 1_000_000,
      "cacheWrite": 18.75 / 1_000_000,
      "cacheRead": 1.50 / 1_000_000
    }
    ```

### Example Usage (TypeScript)
```typescript
import {
  estimateCostFromUsage,
  cacheEfficiency
} from '@/lib/pricing'

const turnCost = estimateCostFromUsage('claude-opus-4-6', {
  input_tokens: 5000,
  output_tokens: 1200,
  cache_creation_input_tokens: 500,
  cache_read_input_tokens: 3000
})
// Result: ~0.165 USD

const efficiency = cacheEfficiency('claude-opus-4-6', {
  inputTokens: 100000,
  outputTokens: 25000,
  cacheReadInputTokens: 80000,
  cacheCreationInputTokens: 10000,
  costUSD: 0,
  webSearchRequests: 0
})
// Result: { savedUSD: 1.08, hitRate: 0.444, wouldHavePaidUSD: 5.56 }
```
```

--------------------------------

### Export API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Exports session data, facets, and history as JSON for backup or migration purposes. Supports optional date range filtering.

```APIDOC
## POST /api/export

### Description
Exports session data, facets, and history as JSON for backup or migration purposes. Supports optional date range filtering.

### Method
POST

### Endpoint
/api/export

### Parameters
#### Request Body
- **dateRange** (object) - Optional. Specifies the date range for the export.
  - **from** (string) - The start date (YYYY-MM-DD).
  - **to** (string) - The end date (YYYY-MM-DD).

### Request Example
```json
{
  "dateRange": {
    "from": "2024-01-01",
    "to": "2024-01-15"
  }
}
```

### Response
#### Success Response (200)
- **exportedAt** (string) - Timestamp of when the export was generated.
- **version** (string) - Version of the export format.
- **stats** (object) - Statistics about the exported data.
- **sessions** (array) - Array of session metadata.
- **facets** (array) - Array of facets.
- **history** (array) - Array of history entries.

#### Response Example
```json
{
  "exportedAt": "2024-01-15T12:00:00Z",
  "version": "1.0.0",
  "stats": { /* StatsCache object */ },
  "sessions": [ /* Array of SessionMeta */ ],
  "facets": [ /* Array of Facet */ ],
  "history": [ /* Array of HistoryEntry */ ]
}
```
```

--------------------------------

### Export Session Data API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Exports session history and facets as JSON. Supports optional date range filtering via POST body.

```bash
curl -X POST http://localhost:3000/api/export \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash
curl -X POST http://localhost:3000/api/export \
  -H "Content-Type: application/json" \
  -d '{
    "dateRange": {
      "from": "2024-01-01",
      "to": "2024-01-15"
    }
  }'
```

--------------------------------

### History API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Retrieves Claude Code command history from `~/.claude/history.jsonl` with pagination support.

```APIDOC
## GET /api/history

### Description
Retrieves command history with optional pagination.

### Method
GET

### Endpoint
/api/history

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of history entries to retrieve (max 10000). Defaults to 200.

### Response
#### Success Response (200)
- **history** (array) - An array of command history objects, each containing display, timestamp, project, and sessionId.

#### Response Example
{
  "history": [
    {
      "display": "Help me debug the authentication flow",
      "timestamp": 1705312200000,
      "project": "/Users/dev/my-project",
      "sessionId": "abc123-def456"
    }
  ]
}
```

--------------------------------

### List All Memory Entries

Source: https://context7.com/arindam200/cc-lens/llms.txt

Reads all Claude Code memory entries across projects, stored in project-specific `memory/` directories. Supports filtering by type.

```bash
# List all memory entries across projects
curl http://localhost:3000/api/memory
```

```json
# Response:
{
  "memories": [
    {
      "file": "MEMORY.md",
      "projectSlug": "-Users-dev-my-project",
      "projectPath": "/Users/dev/my-project",
      "name": "Memory Index",
      "type": "index",
      "description": "Main memory index for project",
      "body": "# Project Memory\n\n## Key Decisions\n- Use TypeScript strict mode...",
      "mtime": "2024-01-15T10:00:00Z",
      "isIndex": true
    },
    {
      "file": "auth-patterns.md",
      "projectSlug": "-Users-dev-my-project",
      "projectPath": "/Users/dev/my-project",
      "name": "Authentication Patterns",
      "type": "reference",
      "description": "Common auth patterns used in this project",
      "body": "# Auth Patterns\n\n## JWT Implementation...",
      "mtime": "2024-01-14T15:30:00Z",
      "isIndex": false
    }
  ]
}
```

--------------------------------

### Memory API

Source: https://context7.com/arindam200/cc-lens/llms.txt

Reads and updates Claude Code memory files stored in project-specific `memory/` directories. Supports filtering by type.

```APIDOC
## GET /api/memory

### Description
Retrieves memory entries across projects.

### Method
GET

### Endpoint
/api/memory

### Response
#### Success Response (200)
- **memories** (array) - An array of memory objects, each containing file, projectSlug, projectPath, name, type, description, body, mtime, and isIndex.

#### Response Example
{
  "memories": [
    {
      "file": "MEMORY.md",
      "projectSlug": "-Users-dev-my-project",
      "projectPath": "/Users/dev/my-project",
      "name": "Memory Index",
      "type": "index",
      "description": "Main memory index for project",
      "body": "# Project Memory\n\n## Key Decisions\n- Use TypeScript strict mode...",
      "mtime": "2024-01-15T10:00:00Z",
      "isIndex": true
    },
    {
      "file": "auth-patterns.md",
      "projectSlug": "-Users-dev-my-project",
      "projectPath": "/Users/dev/my-project",
      "name": "Authentication Patterns",
      "type": "reference",
      "description": "Common auth patterns used in this project",
      "body": "# Auth Patterns\n\n## JWT Implementation...",
      "mtime": "2024-01-14T15:30:00Z",
      "isIndex": false
    }
  ]
}
```

```APIDOC
## PATCH /api/memory

### Description
Updates a specific memory file.

### Method
PATCH

### Endpoint
/api/memory

#### Request Body
- **projectSlug** (string) - Required - The slug of the project.
- **file** (string) - Required - The name of the memory file to update.
- **content** (string) - Required - The new content for the memory file.

### Request Example
{
  "projectSlug": "-Users-dev-my-project",
  "file": "auth-patterns.md",
  "content": "# Updated Auth Patterns\n\n## New JWT Implementation..."
}
```

--------------------------------

### Tool Categories

Source: https://context7.com/arindam200/cc-lens/llms.txt

Tools are categorized for analytics and visualization purposes. MCP tools are automatically detected and parsed.

```APIDOC
## Tool Categories

### Description
Tools are categorized for analytics and visualization purposes. MCP tools are automatically detected and parsed.

### Functions
- **categorizeTool(toolName: string): string**
  Categorizes a given tool name.

- **isMcpTool(toolName: string): boolean**
  Checks if a tool name is an MCP tool.

- **parseMcpTool(toolName: string): object**
  Parses an MCP tool name into its server and tool components.
  - Returns an object with `server` and `tool` properties.

- **toolDisplayName(toolName: string): string**
  Formats the display name for a tool.

### Constants
- **TOOL_CATEGORIES**: Object mapping category names to arrays of tool names.
  - Example:
    ```json
    {
      "file-io": ["Read", "Write", "Edit", "Glob", "Grep", "NotebookEdit"],
      "shell": ["Bash"],
      "agent": ["Task", "TaskCreate", "TaskUpdate", "TaskList", "TaskOutput"],
      "web": ["WebSearch", "WebFetch"],
      "planning": ["EnterPlanMode", "ExitPlanMode", "AskUserQuestion"],
      "todo": ["TodoWrite"],
      "skill": ["Skill", "ToolSearch"],
      "mcp": ["mcp__*"]
    }
    ```
- **CATEGORY_COLORS**: Object mapping category names to color codes.

### Example Usage (TypeScript)
```typescript
import {
  categorizeTool,
  isMcpTool,
  parseMcpTool,
  toolDisplayName
} from '@/lib/tool-categories'

// Categorize a tool
categorizeTool('Read')      // 'file-io'
categorizeTool('mcp__github__create_pr')  // 'mcp'

// Parse MCP tool names
isMcpTool('mcp__github__create_pr')  // true
parseMcpTool('mcp__github__create_pr')
// { server: 'github', tool: 'create_pr' }

// Display name formatting
toolDisplayName('mcp__github__create_pr')  // 'github · create_pr'
```
```

--------------------------------

### Update a Memory File

Source: https://context7.com/arindam200/cc-lens/llms.txt

Updates a specific Claude Code memory file. Requires `projectSlug`, `file`, and `content` in the request body.

```bash
# Update a memory file
curl -X PATCH http://localhost:3000/api/memory \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "-Users-dev-my-project",
    "file": "auth-patterns.md",
    "content": "# Updated Auth Patterns\n\n## New JWT Implementation..."
  }'
```