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

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 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)

$ 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 (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.

# 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:

# 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:

# 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.

# 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.

# Replay the Window projection (current chat view)

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

Output is JSON suitable for piping to jq:

$ 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):

# 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 (lines 10-15): The Projection Reader that executes event streams against registered projections
• 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

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:

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
• 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}