Session Discovery

Utility skill that finds Claude Code conversation sessions stored on the local machine. Runs a bun script and returns a JSON manifest.

How to invoke

Run the discovery script from the harness root:

bash
1bun "$(cat ~/.config/weft/root)/scripts/session-discovery.ts" [flags]

Flags

Examples

bash
1SCRIPT="$(cat ~/.config/weft/root)/scripts/session-discovery.ts"
2
3# Today's sessions
4bun "$SCRIPT"
5
6# Sessions since last review
7bun "$SCRIPT" --since 2026-02-25
8
9# Only sessions in the roger project
10bun "$SCRIPT" --project roger
11
12# Two-day window, specific project
13bun "$SCRIPT" --since 2026-02-27 --until 2026-02-28 --project weft-dev

Output format

JSON to stdout. Diagnostics to stderr.

json
1{
2  "meta": {
3    "claudeDir": "/Users/name/.claude",
4    "since": "2026-02-28",
5    "until": "2026-02-28",
6    "filesScanned": 258,
7    "sessionsMatched": 6,
8    "errors": []
9  },
10  "sessions": [
11    {
12      "sessionId": "uuid",
13      "project": "/Users/name/code/project",
14      "projectEncoded": "-Users-name-code-project",
15      "filePath": "/Users/name/.claude/projects/.../uuid.jsonl",
16      "start": "2026-02-28T00:21:36.816Z",
17      "end": "2026-02-28T01:56:48.087Z",
18      "messageCount": 178,
19      "userMessageCount": 59,
20      "firstPrompt": "first 120 chars of first real user message...",
21      "gitBranch": "feature-branch",
22      "schemaVersion": "2.1.59"
23    }
24  ]
25}

How consuming skills should use the manifest

1. Run the script, parse the output

bash
1bun "$(cat ~/.config/weft/root)/scripts/session-discovery.ts" --since <last-review-date> 2>/dev/null

Parse the JSON from stdout. The meta object tells you how many sessions were found and whether errors occurred.

2. Decide what to read

The manifest gives you file paths and message counts. Use this to decide whether to analyze inline or delegate to sub-agents (per the context management gate in session-review).

• Small window (1-2 sessions, < 200 total messages): read the JSONL files directly
• Large window (3+ sessions, or > 500 messages): dispatch sub-agents with specific file paths from the manifest

3. Read session content

Each filePath is a JSONL file. Each line is a JSON object. The relevant message types:

Filter to user and assistant types for conversation analysis.

4. Filter noise from user messages

User message content often starts with IDE-injected metadata. Skip blocks matching these patterns:

• <ide_opened_file>...
• <system-reminder>...
• <command-message>...
• <command-name>...
• <local-command...

Resilience notes

CLAUDE_CONFIG_DIR: The script checks this environment variable first. If set, it uses that path instead of ~/.claude/. Most users won't have this set.

Path encoding: The / → - encoding for project directories is undocumented and could change. The script doesn't depend on decoding being perfect — it just needs to find JSONL files under projects/. The decoded project field is best-effort for display.

Schema changes: The JSONL format is internal to Claude Code and undocumented. The script reads timestamp and type fields. If these change, the script will return empty results (not crash). The schemaVersion field in each session lets consumers detect version mismatches.

30-day retention: Claude Code may delete sessions older than 30 days. The script can only find what's on disk.

Cross-midnight sessions: The script uses interval overlap logic, not simple date matching. A session starting at 23:00 on day N and ending at 01:00 on day N+1 will match queries for either day.