jq-for-clawd

# JQ for Claude - Session History Queries

Use this skill when users ask about past conversations, previous sessions, or conversation history.

---

## Session File Location

Claude Code stores session history as JSONL files at:

```
~/.claude/projects/<encoded-project-path>/<session-id>.jsonl
```

**Path encoding**: Project paths use dashes instead of slashes.
- `/Users/dave/Documents/my-project` becomes `-Users-dave-Documents-my-project`

### Find the Project Directory

To find sessions for a specific project path:

```bash
# Encode project path (replace / with -)
PROJECT_PATH="/Users/dave/Documents/my-project"
ENCODED=$(echo "$PROJECT_PATH" | sed 's|^/|-|; s|/|-|g')
SESSION_DIR="$HOME/.claude/projects/$ENCODED"

# List sessions sorted by modification time
ls -lt "$SESSION_DIR"/*.jsonl 2>/dev/null | head -10
```

### List All Project Directories

```bash
ls -lt ~/.claude/projects/ | head -20
```

---

## JSONL File Structure

Each session file contains one JSON object per line:

| Line Type | Key Fields | Description |
|-----------|------------|-------------|
| `summary` | `type`, `summary`, `leafUuid` | Session metadata (first line) |
| `user` | `type`, `timestamp`, `message` | User messages |
| `assistant` | `type`, `timestamp`, `message` | Claude responses |
| `system` | `type`, `message` | System prompts |
| `file-history-snapshot` | `type`, `snapshot` | File state snapshots |

### Message Content Structure

User and assistant messages have this structure:

```json
{
  "type": "user",
  "timestamp": "2026-01-10T22:32:07.522Z",
  "message": {
    "role": "user",
    "content": "your message text here"
  },
  "sessionId": "uuid",
  "uuid": "message-uuid"
}
```

**Note**: `message.content` can be either:
- A string: `"content": "hello"`
- An array: `"content": [{"type": "text", "text": "hello"}]`

---

## Common jq Patterns

### Extract User Messages with Timestamps

```bash
cat session.jsonl | jq -r '
  select(.type == "user") |
  .timestamp + " | " + (
    if .