# How to Inspect Sessions and Replay State Using `bun session` in Magnitude

> Inspect Magnitude sessions with bun session. List, search, and replay events to debug and reconstruct projection state. Stream raw events and search payloads.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Use `bun session` to list, search, and replay event-sourced sessions stored in `~/.magnitude/sessions/`, with commands to stream raw events, search payloads, and reconstruct any projection state via the event-core projection engine.**

Magnitude's **event-sourced architecture** persists every interaction as a durable log of events. The `bun session` CLI provides direct access to these session stores, enabling developers to debug, audit, or programmatically reconstruct the state of any Magnitude run. This guide covers all available commands and their underlying implementation in the [magnitudedev/magnitude](https://github.com/magnitudedev/magnitude) repository.

---

## Listing Sessions with `bun session list`

The `bun session list` command enumerates all session folders in the `~/.magnitude/sessions/` directory. Each folder name is a **UTC timestamp** identifying when the session began.

Output includes:

- **Session ID** (the timestamp folder name)
- **Title** (human-readable summary of the session goal)
- **Date** (formatted for readability)

```bash
$ bun session list

```

This command reads directly from the filesystem. The same data powers the UI through the SDK's `Sessions.ListSessions` RPC, consumed by the `useSessionPages` hook in [`packages/client-common/src/hooks/use-session-pages.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/client-common/src/hooks/use-session-pages.ts) (lines 44-53).

---

## Streaming Raw Events with `bun session events`

Session events are stored in **JSON-L format** — one JSON object per line, chronologically ordered. The `bun session events` command streams these events to stdout for inspection or piping.

```bash

# Stream all events for a session

$ bun session events 2024-09-01T12-34-56Z

```

### Filtering Event Types

Use `--type` to narrow output to specific event categories:

```bash

# Show only turn starts and user messages

$ bun session events 2024-09-01T12-34-56Z --type turn_started,user_message

```

Common event types include `turn_started`, `user_message`, `system_message`, `tool_call`, and internal state transitions.

### Slicing Time Ranges

Use `--from` and `--to` (event indices, not timestamps) to extract a subset:

```bash

# Events 100 through 200

$ bun session events 2024-09-01T12-34-56Z --from 100 --to 200

```

---

## Searching Session Payloads with `bun session search`

For debugging specific behaviors, `bun session search` performs **fast text search** across all event payloads without requiring full JSON parsing.

```bash

# Find all events containing "git"

$ bun session search git 2024-09-01T12-34-56Z

```

Returns: event index, snippet of matching text, and event type for context.

---

## Replaying Projection State with `bun session projection`

The most powerful `bun session` capability is **state reconstruction**. Magnitude's projections (derived views like `Window`, `Display`, `TaskGraph`) are computed by replaying the event stream through the **event-core projection engine**. The `bun session projection` command runs this replay offline, materializing any projection's state at any point in the session.

```bash

# Replay the Window projection (current chat view)

$ bun session projection 2024-09-01T12-34-56Z Window

```

Output is **JSON** suitable for piping to `jq`:

```bash
$ bun session projection 2024-09-01T12-34-56Z Window | jq .

```

### Available Projections

| Projection | Description |
|------------|-------------|
| `Window` | Current chat/message view state |
| `Display` | UI display and rendering state |
| `TaskGraph` | Structured task decomposition |
| `all` | All projections as a composite object |

### Replaying at Specific Event Indices

Use `--at` to reconstruct state **as of a specific event** (useful for debugging when something went wrong):

```bash

# State after event 42 completes

$ bun session projection 2024-09-01T12-34-56Z all --at 42 | jq .

```

### Implementation Details

The projection replay delegates to the core engine in `packages/event-core`. Key implementation files:

- [`packages/agent/src/observables/projection-reader.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/observables/projection-reader.ts) (lines 10-15): The **Projection Reader** that executes event streams against registered projections
- [`packages/event-core/src/event-engine/projection-snapshot-service.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/event-core/src/event-engine/projection-snapshot-service.ts): Defines `ProjectionSnapshotEnvelopeInvalid` and snapshot validation logic used during replay

The CLI wraps these internals, requiring no running Magnitude daemon.

---

## Programmatic Session Access via SDK

For applications or custom tooling, the Magnitude SDK exposes the same capabilities as the CLI.

### Fetching a Projection

```typescript
import { MagnitudeClient } from "@magnitudedev/sdk";

async function getWindowProjection(sessionId: string) {
  const projection = await MagnitudeClient.sessions.projection({
    sessionId,
    projection: "Window",
  });
  return projection;
}

```

The `sessions.projection` method mirrors `bun session projection` and returns the identical JSON structure.

### Paginated Session Lists

The UI and CLI share pagination logic through `useSessionPages`:

```tsx
import { useSessionPages } from "@magnitudedev/client-common";

function SessionHistory() {
  const { sessions, loading, loadMore, hasMore } = useSessionPages({ 
    pageSize: 20 
  });

  if (loading) return <p>Loading sessions...</p>;

  return (
    <>
      <ul>
        {sessions.map(s => (
          <li key={s.sessionId}>{s.title} — {s.createdAt}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore}>Load more</button>
      )}
    </>
  );
}

```

This hook constructs the query payload for `Sessions.ListSessions` and subscribes to real-time updates.

---

## Session Storage Layout

Understanding the on-disk format enables custom tooling:

```

~/.magnitude/sessions/
├── 2024-09-01T12-34-56Z/
│   ├── events.jsonl      # Chronological event log

│   └── metadata.json     # Session title, goal, agent version

└── 2024-09-01T13-45-12Z/
    └── ...

```

The `events.jsonl` file is append-only and safe to read while Magnitude is running. No file locking is used; atomic appends ensure consistency.

---

## Summary

- **`bun session list`** enumerates all stored sessions from `~/.magnitude/sessions/`
- **`bun session events`** streams JSON-L event logs with optional type and range filters
- **`bun session search`** performs fast text search across event payloads
- **`bun session projection`** reconstructs any projection state by replaying the event stream through `packages/event-core` and [`packages/agent/src/observables/projection-reader.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/observables/projection-reader.ts)
- **SDK equivalents** (`MagnitudeClient.sessions.projection`, `useSessionPages`) provide programmatic access for building custom UIs or automation

---

## Frequently Asked Questions

### Where are Magnitude sessions stored on disk?

Sessions are stored in `~/.magnitude/sessions/` as timestamped folders, each containing an `events.jsonl` file (append-only event log) and [`metadata.json`](https://github.com/magnitudedev/magnitude/blob/main/metadata.json) (session configuration). This location is fixed and not currently configurable via environment variables.

### Can I replay a session without running the Magnitude daemon?

Yes. The `bun session projection` command operates entirely offline by reading the event log and executing it through the local projection engine. No database, server, or daemon connection is required.

### What is the difference between `events.jsonl` and `projection` output?

`events.jsonl` contains the **raw append-only log** of every state change. A `projection` is a **derived view** computed by folding those events through a projection function — for example, the `Window` projection accumulates messages into a chat view. Projections can be reconstructed at any time; they are not stored, only computed.