From 388796253a0380f47cae15a434f1f1e33b034ce1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 7 Jan 2026 04:13:23 +0000
Subject: [PATCH] feat(skills): add session-logs skill for searching
 conversation history

Adds jq-based queries for:
- Listing sessions by date/size
- Searching user/assistant messages
- Extracting costs per session and daily totals
- Tool usage breakdowns
- Cross-session keyword search
---
 skills/session-logs/SKILL.md | 95 ++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 skills/session-logs/SKILL.md

diff --git a/skills/session-logs/SKILL.md b/skills/session-logs/SKILL.md
new file mode 100644
index 000000000..986cc2e7c
--- /dev/null
+++ b/skills/session-logs/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: session-logs
+description: Search and analyze your own conversation history from session log files using jq.
+metadata: {"clawdbot":{"emoji":"📜","requires":{"bins":["jq"]}}}
+---
+
+# session-logs
+
+Search your complete conversation history stored in session JSONL files. Use this when you need to recall something not in your memory files.
+
+## Location
+
+Session logs live at: `~/.clawdbot/agents/main/sessions/`
+
+- **`sessions.json`** - Index mapping session keys to session IDs
+- **`<session-id>.jsonl`** - Full conversation transcript per session
+
+## Structure
+
+Each `.jsonl` file contains messages with:
+- `type`: "session" (metadata) or "message"
+- `timestamp`: ISO timestamp
+- `message.role`: "user", "assistant", or "toolResult"
+- `message.content[]`: Text, thinking, or tool calls
+- `message.usage.cost.total`: Cost per response
+
+## Common Queries
+
+### List all sessions by date and size
+```bash
+for f in ~/.clawdbot/agents/main/sessions/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  size=$(ls -lh "$f" | awk '{print $5}')
+  echo "$date $size $(basename $f)"
+done | sort -r
+```
+
+### Find sessions from a specific day
+```bash
+for f in ~/.clawdbot/agents/main/sessions/*.jsonl; do
+  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
+done
+```
+
+### Extract user messages from a session
+```bash
+jq -r 'select(.message.role == "user") | .message.content[0].text' <session>.jsonl
+```
+
+### Search for keyword in assistant responses
+```bash
+jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | grep -i "keyword"
+```
+
+### Get total cost for a session
+```bash
+jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
+```
+
+### Daily cost summary
+```bash
+for f in ~/.clawdbot/agents/main/sessions/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
+  echo "$date $cost"
+done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r
+```
+
+### Count messages and tokens in a session
+```bash
+jq -s '{
+  messages: length,
+  user: [.[] | select(.message.role == "user")] | length,
+  assistant: [.[] | select(.message.role == "assistant")] | length,
+  first: .[0].timestamp,
+  last: .[-1].timestamp
+}' <session>.jsonl
+```
+
+### Tool usage breakdown
+```bash
+jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.jsonl | sort | uniq -c | sort -rn
+```
+
+### Search across ALL sessions for a phrase
+```bash
+grep -l "phrase" ~/.clawdbot/agents/main/sessions/*.jsonl
+```
+
+## Tips
+
+- Sessions are append-only JSONL (one JSON object per line)
+- Large sessions can be several MB - use `head`/`tail` for sampling
+- The `sessions.json` index maps chat providers (discord, whatsapp, etc.) to session IDs
+- Deleted sessions have `.deleted.<timestamp>` suffix