# What Events Are Captured in Context-Mode Sessions and How Are They Prioritized?

> Understand context-mode session events and their prioritization. Learn how Claude Code hooks capture and rank events from 1 to 5 for efficient XML snapshot creation.

- Repository: [Mert Köseoğlu/context-mode](https://github.com/mksglu/context-mode)
- Tags: how-to-guide
- Published: 2026-04-24

---

**Context-mode captures structured session events from Claude Code hooks, assigns each a priority level from 1 (critical) to 5 (lowest) based on category, and uses these priorities to guide context compaction when building resumable XML snapshots.**

The `mksglu/context-mode` repository implements a session recording system that tracks every interaction during a Claude Code session. Understanding what events are captured during a session and how they are prioritized in the context-mode snapshot is essential for optimizing context windows and ensuring critical information survives compaction.

## Event Categories and Capture Mechanism

Events are extracted by pure functions in [`src/session/extract.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/extract.ts) and grouped by category in [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts). Each event type receives a specific priority value where lower numbers indicate higher importance.

### File Operations and Rules (Priority 1)

File system interactions and rule applications receive the highest priority (**1**) because they represent direct modifications to the workspace. According to the source code in `extractFileAndRule` (lines 71-100), the following events are captured:

- `file_read`, `file_write`, `file_edit` — Priority **1**
- `rule`, `rule_content` — Priority **1** (critical, must survive compaction)

File glob and search operations receive lower priority (**3**) and are handled separately in `extractFileAndRule` (lines 141-148 for glob, lines 151-160 for grep).

### Working Directory and Environment (Priority 2)

Contextual state changes that affect execution but don't modify files directly receive priority **2**:

- `cwd` — Emitted by `extractCwd` (lines 71-85)
- `env` (setup commands) — Emitted by `extractEnv` (lines 77-92)
- `worktree` (EnterWorktree) — Emitted by `extractWorktree` (lines 88-96)
- `git` operations — Emitted by `extractGit` (lines 39-51)

Error events (`error_tool`) also receive priority **2** via `extractError` (lines 93-110).

### Planning and Task Management (Priority 1-2)

Core workflow events use a mixed priority scheme:

- `task_create`, `task_update`, `task` — Priority **1** (core work items), emitted by `extractTask` (lines 58-73)
- `plan_enter`, `plan_exit`, `plan_file_write` — Priority **2**
- `plan_approved` — Priority **1** (critical milestone)

These plan events are extracted by `extractPlan` (lines 86-133, 135-146).

### Subagents and Decisions (Priority 2-3)

Agent delegation and user decision points:

- `subagent_completed` — Priority **2** (kept), emitted by `extractSubagent` (lines 24-31)
- `subagent_launched` — Priority **3** (may be trimmed), emitted by `extractSubagent` (lines 24-30)
- `decision_question` (AskUserQuestion) — Priority **2**, emitted by `extractDecision` (lines 62-80)
- `decision` (user-message patterns) — Priority **2**, emitted by `extractUserDecision` (lines 14-22)

### Low-Priority Context (Priority 3-5)

Peripheral information that can be sacrificed first during compaction:

- `role` (persona directives) — Priority **3**, emitted by `extractRole` (lines 38-46)
- `skill` (Skill tool) — Priority **3**, emitted by `extractSkill` (lines 2-8)
- `mcp` (any `mcp__*` tool) — Priority **3**, emitted by `extractMcp` (lines 38-55)
- `intent` (session mode) — Priority **4**, emitted by `extractIntent` (lines 62-70)
- `data` (large pasted payload > 1 KB) — Priority **5** (lowest), emitted by `extractData` (lines 78-84)

## How Event Prioritization Works

The priority system is implemented across three core files: [`extract.ts`](https://github.com/mksglu/context-mode/blob/main/extract.ts), [`snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/snapshot.ts), and [`db.ts`](https://github.com/mksglu/context-mode/blob/main/db.ts).

**Priority Assignment**: In [`src/session/extract.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/extract.ts), each extractor function assigns a priority value when creating `SessionEvent` objects. For example, file edits receive priority 1 while data payloads receive priority 5.

**Snapshot Building**: In [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts) (lines 998-1025), events are grouped by category and rendered into XML. The `buildResumeSnapshot` function (lines 981-1004) includes the priority field in each event's representation but does not filter events based on these values.

**Compaction Strategy**: The priority field exists specifically for downstream consumers. When the LLM's context compaction step needs to trim the snapshot to fit a token budget, it uses the priority values to determine which events to preserve (lower numbers) and which to remove (higher numbers).

## Accessing Event Data in Practice

### Extracting Events from Hook Payloads

To capture events from a raw hook input, import the extractor functions from [`src/session/extract.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/extract.ts):

```typescript
import { extractFileAndRule, extractCwd, extractError, extractTask, extractPlan } from "./session/extract";
import type { SessionEvent } from "./types";

function extractAll(input: HookInput): SessionEvent[] {
  const events: SessionEvent[] = [];
  
  // Critical file and rule events (priority 1)
  events.push(...extractFileAndRule(input));
  
  // Environment context (priority 2)
  events.push(...extractCwd(input));
  events.push(...extractEnv(input));
  
  // Workflow tracking (priority 1-2)
  events.push(...extractTask(input));
  events.push(...extractPlan(input));
  
  // Error handling (priority 2)
  events.push(...extractError(input));
  
  // Additional extractors follow the same pattern...
  return events;
}

```

### Building a Resumable Snapshot

Convert stored events into an XML snapshot using the builder from [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts):

```typescript
import { buildResumeSnapshot } from "./session/snapshot";
import type { StoredEvent } from "./session/db";

// Load events from the SQLite session database
const storedEvents: StoredEvent[] = await db.getSessionEvents(sessionId);

const snapshotXml = buildResumeSnapshot(storedEvents, {
  compactCount: 1,
  searchTool: "ctx_search",
});

// snapshotXml contains prioritized event data for the LLM context window
console.log(snapshotXml);

```

### Querying Event Priorities in the Database

Inspect the priority assignments directly via SQL. The `priority` column is defined in [`src/session/db.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/db.ts) (line 70):

```sql
SELECT 
  type, 
  category, 
  priority, 
  data 
FROM session_events 
WHERE session_id = ? 
ORDER BY priority ASC, id ASC;

```

This query returns events sorted by priority, showing critical priority 1 events (file operations, tasks) before lower priority context (intents, data payloads).

## Summary

- **Event capture** occurs in [`src/session/extract.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/extract.ts) through specialized functions like `extractFileAndRule`, `extractTask`, and `extractPlan`.
- **Priority levels** range from 1 (critical file edits, rules, approved plans) to 5 (large data payloads), with intermediate levels for environment state and decisions.
- **Snapshot construction** in [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts) preserves all events but includes priority metadata to guide downstream compaction when token limits are reached.
- **Storage** happens in SQLite with the schema defined in [`src/session/db.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/db.ts), allowing SQL-based inspection of event priorities.

## Frequently Asked Questions

### What priority level is assigned to file operations?

File reads, writes, and edits receive **priority 1** (the highest level), while file glob and search operations receive **priority 3**. This distinction ensures that actual file modifications survive context compaction, while expensive search operations may be trimmed if needed.

### How does context-mode use priority values when building snapshots?

The snapshot builder in [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts) does not drop events based on priority during initial construction. Instead, it embeds the priority field into the XML representation so that downstream context compaction algorithms can use these values to intelligently trim the snapshot when fitting it within token budgets.

### Where are session events stored and how can I query them?

Events persist in a SQLite database with the schema defined in [`src/session/db.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/db.ts). The `session_events` table includes columns for `type`, `category`, `priority`, and `data`, allowing you to query specific event types or filter by priority level using standard SQL.

### What is the difference between event extraction and snapshot building?

**Extraction** happens in [`src/session/extract.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/extract.ts) and transforms raw Claude Code hook payloads into typed `SessionEvent` objects with assigned priorities. **Snapshot building** happens in [`src/session/snapshot.ts`](https://github.com/mksglu/context-mode/blob/main/src/session/snapshot.ts) and groups these events by category to create a resumable XML representation that preserves the priority metadata for later compaction decisions.