grailautomation/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.

• /home/user/my-project becomes -home-user-my-project

Find the Project Directory

To find sessions for a specific project path:

# Encode project path (replace / with -)
PROJECT_PATH="/home/user/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

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:

{
  "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

cat session.jsonl | jq -r '
  select(.type == "user") |
  .timestamp + " | " + (
    if .message.content | type == "string"
    then .message.content[0:300]
    else (.message.content[0].text // "N/A")[0:300]
    end
  )
' | grep -v "N/A" | grep -v "command-name" | grep -v "local-command"

Count Message Types in a Session

cat session.jsonl | jq -r '.type' | sort | uniq -c

Get Session Start Time

head -5 session.jsonl | jq -r 'select(.type == "user") | .timestamp' | head -1

Find Sessions by Content

Search across all sessions in a project for a keyword:

SESSION_DIR="$HOME/.claude/projects/-home-user-my-project"
for f in "$SESSION_DIR"/*.jsonl; do
  if grep -q "keyword" "$f" 2>/dev/null; then
    echo "=== $f ==="
    cat "$f" | jq -r 'select(.type == "user" and (.message.content | tostring | test("keyword"; "i"))) | .timestamp + " | " + (.message.content | tostring)[0:200]' 2>/dev/null
  fi
done

List Recent Sessions with First User Message

SESSION_DIR="$HOME/.claude/projects/-home-user-my-project"
for f in $(ls -t "$SESSION_DIR"/*.jsonl 2>/dev/null | grep -v "agent-" | head -5); do
  echo ""
  echo "=== $(basename $f) ==="
  cat "$f" | jq -r '
    select(.type == "user") |
    .timestamp + " | " + (
      if .message.content | type == "string"
      then .message.content[0:150]
      else (.message.content[0].text // "N/A")[0:150]
      end
    )
  ' 2>/dev/null | grep -v "N/A" | grep -v "command-name" | head -3
done

---

Filtering Tips

Exclude Agent Sessions

Agent/subagent sessions have filenames starting with agent-:

ls -lt "$SESSION_DIR"/*.jsonl | grep -v "agent-"

Filter by Date

Sessions include ISO timestamps. Filter with jq:

cat session.jsonl | jq -r '
  select(.type == "user" and .timestamp > "2026-01-10") |
  .timestamp + " | " + (.message.content | tostring)[0:100]
'

Exclude System Messages

Filter out command invocations and system noise:

grep -v "command-name" | grep -v "local-command" | grep -v "N/A"

---

Example Workflow

When a user asks "what did I ask you in our last few sessions?":

1. Identify the project path (current working directory or ask user)

2. Encode and locate sessions:

   ENCODED=$(echo "$PWD" | sed 's|^/|-|; s|/|-|g')
   SESSION_DIR="$HOME/.claude/projects/$ENCODED"
   

3. List recent non-agent sessions:

   ls -lt "$SESSION_DIR"/*.jsonl | grep -v "agent-" | head -5
   

4. Extract user messages from each:

   cat "$SESSION_DIR/<session-id>.jsonl" | jq -r '
     select(.type == "user") |
     .timestamp + " | " + (
       if .message.content | type == "string"
       then .message.content[0:300]
       else (.message.content[0].text // "N/A")[0:300]
       end
     )
   ' | grep -v "N/A" | grep -v "command-name" | head -5
   

5. Present results in a clean, organized format grouped by session with timestamps.

---

Troubleshooting

No sessions found: Verify the project path encoding matches exactly. Check ls ~/.claude/projects/ for the correct directory name.

jq parse errors: Some lines may have malformed JSON. Add 2>/dev/null to suppress errors.

Empty content: Some user messages (like tool approvals) have array content without text. Filter with grep -v "N/A".