Skip to content
Get packs

Guide · Agent skill

How to use the Session Log Search agent skill (session-logs)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The session-logs skill teaches an AI agent to search the saved transcripts of its earlier conversations, which are stored as JSONL files on your machine. It is useful when you ask about something said in an older or parent chat that is not in the agent's memory files. After this guide you will know what the skill does, how to install it, how to phrase requests that trigger it, and what to check before using it.

Session Log Searchspinabot/brigade · MIT

Quick start

  1. 1Install jq and ripgrep. Install the two command-line tools the skill needs. The source suggests Homebrew formulas named jq and ripgrep.
  2. 2Unzip the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
  3. 3Confirm your state directory. Check that your session logs sit under $BRIGADE_STATE_DIR/agents/<agentId>/sessions/ or the default ~/.brigade path.
  4. 4Ask a natural question. Refer to an earlier chat that is not in memory files, for example asking what was decided in a previous conversation.
  5. 5Review the results. The agent pulls matching text from the transcript. Check the session file name and date it reports against what you expected.

What the session-logs skill makes the agent do

Agent skills are instruction packs that teach an agent how to handle a specific kind of task. This one covers the saved history of earlier conversations. When you refer to a prior chat or ask what was said before, and the answer is not in memory files, the agent is directed to search the transcript files instead.

The skill's source describes these abilities: finding the right session, pulling out the human-readable messages, searching for keywords, and summarizing message counts, tool usage, and per-session or daily cost.

  • Locate sessions by date and size
  • Extract user or assistant text from a session
  • Search one session or all sessions for a phrase
  • Count messages and tool calls
  • Total cost per session or per day

Install the session-logs skill

Download the skill ZIP from this page. Unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder so it applies only to that project.

If you use the Claude apps instead, open Settings, then Capabilities, then Skills, and upload the ZIP there.

The skill ships as a single file, SKILL.md. The metadata lists two command-line tools it depends on, jq and ripgrep (rg). The source gives Homebrew install labels for both: a formula named jq and a formula named ripgrep.

brew install jq ripgrep

Check where your session logs live

The skill reads logs from the active state directory: $BRIGADE_STATE_DIR/agents/<agentId>/sessions/. If that variable is not set, the default is ~/.brigade/agents/<agentId>/sessions/. The agent ID comes from the agent=<id> value in the system prompt Runtime line.

Inside that folder, sessions.json maps session keys to session IDs, and each <session-id>.jsonl file holds the full transcript for one session.

  • sessions.json: index from session keys to session IDs
  • <session-id>.jsonl: full conversation transcript for one session
  • Deleted sessions carry a .deleted.<timestamp> suffix

Trigger the skill with natural requests

You do not need special syntax. The skill is meant for requests about prior chats, parent conversations, or historical context that is not in memory files. Say what you remember and what you need back.

Be specific about the topic, a rough date, or a platform if you know it. The source mentions chat providers such as Discord and WhatsApp as keys in the index, so naming the channel can help narrow the search.

  • "What did we decide about the database schema in a previous chat?"
  • "Find the session from January 6 where we talked about the release plan."
  • "How much did my agent sessions cost per day this week?"
  • "Which tools were used most in the Discord session?"

Run the common queries yourself

If you want to run the queries directly, the skill includes ready-made commands. Replace <session> or <id> with a real file name, and set AGENT_ID to your agent's ID. This example extracts user messages from one session.

To search assistant replies for a keyword, pipe the text-only output into rg -i. To search every session for a phrase, use rg -l so only matching file names are listed.

  • Session cost total: jq -s with message.usage.cost.total summed
  • Message and token counts: jq -s returns messages, user, assistant, first and last timestamps
  • Tool usage breakdown: counts toolCall names with sort and uniq -c
jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl

Safety notes: scripts and network

The skill runs scripts on your machine, so review SKILL.md before you install it. The listed requirements say it runs scripts and does not use the network. It reads only files already on disk.

Session logs contain full conversation text, and the agent will read all of it when it searches. Do not use the skill casually on chats that contain sensitive material you would not want an agent to read.

  • Runs scripts: yes
  • Uses network: no
  • Reads only session files already stored locally

Tips for better results

Session files are append-only JSONL, with one JSON object per line. Large sessions can reach several megabytes, so sampling with head or tail is faster than reading a whole file. Only the text-type content is human-readable, so filtering on type == "text" keeps output short.

  • Use head and tail to sample large sessions
  • Filter with type=="text" for low-noise output
  • Use the sessions.json index to find the session for a given chat provider

What people use it for

  • Recovering an earlier decision or exact wording from a previous chat
  • Finding which session discussed a specific topic on a given day
  • Tracking daily or per-session agent cost
  • Reviewing which tools an agent used most in a session
  • Checking message counts and first and last timestamps of a conversation

Frequently asked questions

How do I install the session-logs skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

What do I need to run session-logs?

The skill requires jq and ripgrep (rg). The source suggests installing both with Homebrew, using the formulas jq and ripgrep. It also expects Brigade session logs on your disk.

Is session-logs free?

The skill is listed under the MIT licence. The source does not mention pricing, so check the licence text on this page for the terms.

Does session-logs work with other agents besides Brigade?

No. The paths and log structure are specific to the Brigade state directory, so it is not meant for non-Brigade agent setups.

Does the skill send my chats over the internet?

The listed requirements say it does not use the network. It reads session files already stored on your machine, though it does run scripts, so review SKILL.md first.

Why does the skill find no sessions?

Check that session logs exist under $BRIGADE_STATE_DIR/agents/<agentId>/sessions/, or under ~/.brigade/agents/<agentId>/sessions/ if the variable is unset. Also confirm the agent ID matches the agent=<id> value in the Runtime line.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use session-logs if you run the Brigade agent and need to recall, audit, or cost out past conversations that are stored locally. Skip it if you do not keep local session logs, use a different agent setup, or need to share chats safely, since the skill reads the full text of every transcript it searches.

Download the skill