> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/websitebutlers/codefire-app/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Monitoring

> Real-time mission control for active coding sessions with token tracking and cost analysis

CodeFire provides real-time monitoring of active Claude Code sessions and maintains a searchable history of all past sessions with detailed analytics.

## Live Session View

The Dashboard tab shows a live feed of your active Claude Code session:

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/websitebutlers-codefire-app/assets/screenshot-10.png" alt="Live session monitoring with cost tracking" />
</Frame>

### Real-Time Metrics

CodeFire polls the session JSONL file every 2 seconds and displays:

* **Context usage** — Current tokens vs. 200k limit with visual meter
* **Cost** — Estimated spend based on model pricing
* **Messages** — Total user + assistant messages
* **Tools** — Number of tool invocations (Read, Edit, Bash, etc.)
* **Elapsed time** — How long the session has been running

<Note>
  CodeFire reads only new bytes from the session file on each poll, making monitoring lightweight even for large sessions.
</Note>

### Tool Usage Breakdown

Expand the "Tool Usage & Files" section to see:

* **Bar chart** of tool invocations (Read, Edit, Bash, Glob, etc.)
* **Files changed** — List of files the agent has touched
* **Tool counts** — How many times each tool was called

### Activity Feed

The live feed shows a chronological stream of events:

* 🔵 **User messages** — Your prompts to the agent
* 🟢 **Assistant text** — Claude's responses
* 🟣 **Tool use** — Each tool invocation with context (file path, command, etc.)

Scroll through the feed to see what the agent is doing in real-time.

## Session History

The Sessions tab shows all past sessions for the current project:

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/websitebutlers-codefire-app/assets/screenshot-09.png" alt="Session history with cost tracking" />
</Frame>

### Session List

Each session displays:

* **Session ID** and **slug** (human-readable name)
* **Started** and **ended** timestamps
* **Model** used (Opus, Sonnet, Haiku)
* **Git branch** the session ran on
* **Token usage** (input, output, cache creation, cache read)
* **Estimated cost** in USD
* **Message count** and **tool count**

### Session Details

Click a session to view:

* **Full conversation** (user prompts and assistant responses)
* **Tool usage patterns** (which tools were called and how often)
* **Files changed** (complete list with diffs)
* **Cost breakdown** (input, output, cache creation, cache read)
* **Timeline** of events

### Cost Tracking

CodeFire calculates cost using model-specific pricing:

| Model  | Input           | Output          | Cache Write      | Cache Read      |
| ------ | --------------- | --------------- | ---------------- | --------------- |
| Opus   | \$15/M tokens   | \$75/M tokens   | \$18.75/M tokens | \$1.50/M tokens |
| Sonnet | \$3/M tokens    | \$15/M tokens   | \$3.75/M tokens  | \$0.30/M tokens |
| Haiku  | \$0.25/M tokens | \$1.25/M tokens | \$0.30/M tokens  | \$0.03/M tokens |

Total cost per session and per project is displayed in the UI.

<Tip>
  Use per-project cost tracking to bill clients accurately or monitor your AI spend.
</Tip>

## How It Works

CodeFire parses Claude Code's session JSONL files:

1. **Project discovery** — Scans `~/.claude/projects/` to find all projects
2. **Session import** — Parses `.jsonl` files to extract metadata and token usage
3. **Live monitoring** — Watches active session files for new events
4. **Incremental updates** — Reads only new bytes (not the entire file) on each poll

### Session File Format

Claude Code writes each event as a JSON line:

```json theme={null}
{"type": "user", "timestamp": "2026-03-04T10:30:00.000Z", "message": {...}}
{"type": "assistant", "model": "claude-sonnet-4", "usage": {...}, "content": [...]}
```

CodeFire parses these lines to extract:

* Session metadata (ID, slug, model, git branch)
* Token usage (input, output, cache)
* Tool invocations (name, input parameters)
* Files changed (from Read, Edit, Write tools)

## Inactivity Detection

CodeFire considers a session ended if no new events appear for 2 minutes. When a session ends:

* Live monitoring stops
* Final token counts and cost are calculated
* Session is marked as complete in the history

## Session Search

Filter sessions by:

* **Date range** — Last 7 days, last month, custom range
* **Model** — Opus, Sonnet, Haiku
* **Git branch** — Filter by branch name
* **Cost** — Sessions above/below a cost threshold

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor context usage during long sessions">
    Keep an eye on the context meter. If it approaches 200k tokens, consider starting a new session to avoid hitting the limit.
  </Accordion>

  <Accordion title="Review tool usage to understand agent behavior">
    Check which tools the agent called most frequently. Heavy Bash usage might indicate complex workflows; heavy Read usage suggests exploration.
  </Accordion>

  <Accordion title="Track costs per client or project">
    Use CodeFire's per-project cost tracking to understand spend patterns and bill clients accurately.
  </Accordion>

  <Accordion title="Export session history for analysis">
    Sessions are stored in SQLite (`~/Library/Application Support/CodeFire/codefire.db`). Query directly for custom reports.
  </Accordion>
</AccordionGroup>

## Agent Status Bar

When Claude Code is running, CodeFire displays an agent status bar in the terminal panel:

* 🟢 **Active** — Claude is running
* 🟡 **Thinking** — Claude is processing your request
* 🔴 **Error** — Claude encountered an error

This provides quick visual feedback without switching to the Dashboard tab.

## Related Features

<CardGroup cols={2}>
  <Card title="Project Management" icon="folder-open" href="/features/project-management">
    View sessions grouped by project
  </Card>

  <Card title="Task Tracking" icon="list-check" href="/features/task-tracking">
    Link sessions to specific tasks
  </Card>

  <Card title="Terminal" icon="terminal" href="/features/terminal">
    Launch Claude sessions from the integrated terminal
  </Card>

  <Card title="Git Integration" icon="code-branch" href="/features/git-integration">
    See which git branch each session ran on
  </Card>
</CardGroup>