agentleFS
MereithhhMereithhh/very-happy/.agents/skills/sessions/SKILL.md

sessions

Skill8 starsChanged 10 days agoMITView on GitHub

Search and ask questions about coding agent session history across Claude Code, Codex, and Cursor. Use when asking what was worked on, what was tried before, how a problem was investigated across sessions, what happened recently, or any question about past agent sessions. Also use when the user references prior sessions, previous attempts, or past investigations — even without saying 'sessions' explicitly.

  • Deletes or force-pushes

26 other projects use a version of this; 1 new project in the last 4 weeks, against 0 the 4 before.

Adopted by

Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 1 new projectWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 1 in all, so this is a hint, not a trend.

Most recently taken up by

Used with

Projects with it also use tool-rename-deprecation, add-policy and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • gitpod-ioSkill

    tool-rename-deprecation

    Ensure renamed built-in tool references preserve backward compatibility. Use when renaming a toolReferenceName, tool set referenceName, or any tool identifier. Run on ANY change to tool registration code. Covers legacyToolReferenceFullNames for tools and legacyFullNames for tool sets.

    Also in 5 projects that use this

  • OpenCortexIDESkill

    add-policy

    Use when adding, modifying, or reviewing VS Code configuration policies. Covers the full policy lifecycle from registration to export to platform-specific artifacts. Run on ANY change that adds a `policy:` field to a configuration property.

    Also in 4 projects that use this

  • gitpod-ioSkill

    agent-sessions-layout

    Agent Sessions workbench layout — covers the fixed layout structure, grid configuration, part visibility, editor modal, titlebar, sidebar footer, and implementation requirements. Use when implementing features or fixing issues in the Agent Sessions workbench layout.

    Also in 3 projects that use this

  • TheKREATORSSkill

    refactor-clean

    No description

    Also in 3 projects that use this

  • ryu111Skill

    browser

    agent-browser CLI 瀏覽器自動化指南。E2E 測試、UI 調試、設計驗證。適用於需要實際操作瀏覽器的場景。

    Also in 3 projects that use this

  • Hugging FaceSkill

    update-docs

    Update documentation across the repo after API changes. Finds stale references in docs, examples, docstrings, and fixes them.

    Also in 3 projects that use this

  • +2 more from gitpod-io

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 6 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search session history across Claude Code, Codex, and Cursor and synthesize findings about what was worked on, tried, decided, or learned …

    line 8
  2. Very specific:

    If the line above resolved to a plain branch name (like feat/my-branch), use it for branch filtering and pass it to the synthesis subagent.

    line 21
  3. Distinctive:

    If the line above resolved to a plain repo folder name, use it for session discovery.

    line 25
  4. Distinctive:

    Fail fast on access errors: If session discovery fails on permissions, report the issue immediately.

    line 40
  5. Very specific:

    Run the discovery + metadata pipeline (preserving the null-delimited xargs hardening that lets extract-metadata.py run in batch mode):

    line 61
  6. Very specific:

    If the inventory's _meta line shows files_processed: 0, return "no relevant prior sessions" and stop.

    line 69
  7. Very specific:

    If parse_errors > 0, note that some sessions could not be parsed and proceed with what was returned.

    line 71
  8. Very specific:

    Branch filter (Claude Code only): Keep sessions where branch == dispatch_branch exactly, or where the branch name contains a keyword from …

    line 79
  9. Very specific:

    If files_matched > 0, treat those sessions as candidates.

    line 85
  10. Very specific:

    Drop sessions outside the scan window: Use last_ts when available, fall back to ts.

    line 87
  11. Distinctive:

    Create a per-run throwaway scratch directory:

    line 99
  12. Distinctive:

    Use selectively — only when understanding what went wrong adds value.

    line 131
  13. Very specific:

    When the caller (e.g., ce-compound) supplies a schema in the skill argument, pass it through verbatim.

    line 156
  14. Very specific:

    When the caller (typically a user typing /ce-sessions, or another skill invoking ce-sessions via the platform's skill-invocation primitive) …

    line 198
  15. Distinctive:

    If the discovery pipeline fails (e.g., unreadable home directory, permission failure), surface the error to the caller.

    line 212
  16. Very specific:

    If extraction --output write fails (disk full, permission), surface a clear error and do not dispatch the synthesizer with partial paths.

    line 214
  17. Very specific:

    If _meta reports parse_errors > 0 from any script, note partial extraction in the dispatch prompt and proceed.

    line 216

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/sessions (installed from EveryInc/compound-engineering-plugin ce-sessions)

Search session history across Claude Code, Codex, and Cursor and synthesize findings about what was worked on, tried, decided, or learned in prior sessions.

Usage

/ce-sessions [question or topic]
/ce-sessions

Pre-resolved context

Git branch (pre-resolved): !git rev-parse --abbrev-ref HEAD 2>/dev/null || true

If the line above resolved to a plain branch name (like feat/my-branch), use it for branch filtering and pass it to the synthesis subagent. If it still contains a backtick command string or is empty, derive the branch at runtime instead.

Repo name (pre-resolved): !basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || true

If the line above resolved to a plain repo folder name, use it for session discovery. Otherwise derive at runtime.

Note: 2026

The current year is 2026. Use this when interpreting session timestamps.

Guardrails

These rules apply at all times during orchestration and synthesis.

  • Never read entire session files into context. Session files can be 1-7MB. Always use the extraction scripts to filter first, then reason over the filtered output.
  • Never extract or reproduce tool call inputs/outputs verbatim. Summarize what was attempted and what happened.
  • Never include thinking or reasoning block content. Claude Code thinking blocks are internal reasoning; Codex reasoning blocks are encrypted. Neither is actionable.
  • Never analyze the current session. Its conversation history is already available to the caller.
  • Surface technical content, not personal content. Sessions contain everything — credentials, frustration, half-formed opinions. Use judgment about what belongs in a technical summary and what doesn't.
  • Fail fast on access errors. If session discovery fails on permissions, report the issue immediately. Do not retry the same operation with different tools or approaches — repeated retries waste tokens without changing the outcome.

Execution

If no question argument is provided, ask what the user wants to know about their session history. Use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini, ask_user in Pi (requires the pi-ask-user extension). Fall back to asking in plain text only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Step 1 — Determine scan window

Infer a time range from the user's question. Start narrow; widen only if a narrow scan finds nothing relevant.

SignalInitial scan window
"today", "this morning"1 day
"recently", "last few days", "this week", or no time signal7 days
"last few weeks", "this month"30 days
"last few months", broad feature history90 days

Claude Code retains session history for ~30 days by default. Wider windows may find nothing on Claude Code unless the user has extended retention.

Step 2 — Discover sessions and extract metadata

Run the discovery + metadata pipeline (preserving the null-delimited xargs hardening that lets extract-metadata.py run in batch mode):

bash scripts/discover-sessions.sh <repo> <days> | tr '\n' '\0' | xargs -0 python3 scripts/extract-metadata.py --cwd-filter <repo>

Each output line is a JSON object describing a session (platform, file, size, ts, session, plus platform-specific fields). The final _meta line carries files_processed and parse_errors.

If the inventory's _meta line shows files_processed: 0, return "no relevant prior sessions" and stop.

If parse_errors > 0, note that some sessions could not be parsed and proceed with what was returned.

To narrow the platform set, add --platform claude, --platform codex, or --platform cursor to the discover-sessions.sh invocation. Default to all three.

Step 3 — Filter and rank

Apply these filters in order to pick the sessions worth deep-diving:

  1. Branch filter (Claude Code only). Keep sessions where branch == dispatch_branch exactly, or where the branch name contains a keyword from the question's topic (e.g., a question about "auth middleware" matches branches feat/auth-fix, chore/auth-refactor). Codex sessions don't carry gitBranch — skip this filter for them.
  2. If the branch filter returned zero sessions, or you're processing Codex sessions:
    • Derive 2-4 keywords from the question's topic. For "a recent crash in the auth middleware where session-validation rejects valid tokens", derive auth,middleware,session,token (or similar).
    • Re-invoke the discovery pipeline with --keyword K1,K2,... appended to the extract-metadata.py invocation. The script returns sessions with non-zero match_count plus per-keyword counts.
    • If files_matched: 0, return "no relevant prior sessions" and stop. Do not extract anything.
    • If files_matched > 0, treat those sessions as candidates. Rank by match_count, break ties by per-keyword counts.
  3. Drop sessions outside the scan window. Use last_ts when available, fall back to ts. Discard sessions where both fall before the window start.
  4. Exclude the current session — its conversation history is already available to the caller.
  5. Apply the deep-dive cap. Take at most 5 sessions total across all platforms. Narrow by branch-match → match_count → file size > 30KB → recency.
  6. Proceed only if at least one session remains after filtering. Otherwise return "no relevant prior sessions" and stop.

Note: gitBranch is captured at the first user message only. A session that began on main and did substantive work on a feature branch via mid-session git checkout records branch: "main". Branch-match returning nothing is not conclusive evidence — that's why the keyword-filter fallback in step 2 is required.

Step 4 — Set up scratch space

Create a per-run throwaway scratch directory:

SCRATCH=$(mktemp -d -t ce-sessions-XXXXXX)

Capture the absolute path; thread it into Step 5 and Step 6. The OS handles cleanup on session end; an explicit rm -rf "$SCRATCH" at the end of Step 7 is harmless and makes intent explicit.

Step 5 — Extract per-session content (file-mediated)

For each selected session, run the skeleton extractor with --output so content writes directly to the scratch file — extraction bytes never round-trip through the orchestrator's tool results:

python3 scripts/extract-skeleton.py --output "$SCRATCH/<session-id>.skeleton.txt" < <session-file>

Stdout receives only a one-line JSON status ({"_meta": true, "wrote": "...", "bytes": N, ...}). Capture bytes and parse_errors from each status line.

Conditional tail-extract — if a skeleton terminates mid-investigation (last visible turn is a tool call with no resolution, or the assistant is mid-debugging without a conclusion), re-extract with a tail shape:

python3 scripts/extract-skeleton.py --output "$SCRATCH/<session-id>.skeleton.tail.txt" < <session-file>

(The skeleton script does not accept a tail:N cap directly; if a tail-only view is needed, post-process the scratch file in shell with tail -n 50 after extraction. Use this only when the head output suggests the session was truncated mid-investigation.)

Conditional errors-mode — for sessions where investigation dead-ends are likely valuable:

python3 scripts/extract-errors.py --output "$SCRATCH/<session-id>.errors.txt" < <session-file>

Use selectively — only when understanding what went wrong adds value. Cursor agent transcripts don't log tool results, so errors-mode produces nothing for Cursor sessions.

Step 6 — Dispatch synthesis subagent

Dispatch the ce-session-historian subagent via the platform's subagent primitive (Agent in Claude Code, spawn_agent in Codex, subagent in Pi via the pi-subagents extension). Omit the mode parameter so the user's configured permission settings apply. Run on the mid-tier model (e.g., model: "sonnet" in Claude Code) — the synthesizer doesn't need frontier reasoning.

The dispatch prompt is the agent's input contract. Pass these fields:

  • problem_topic — one sentence naming the concrete question. Lift from the user's argument or, if missing, from the answer to the no-arg prompt.
  • scratch_dir — absolute path to $SCRATCH.
  • sessions — an array of objects, one per extracted session, each with:
    • path — absolute path to the skeleton file (and optionally errors_path for the errors file when extracted)
    • platform — claude, codex, or cursor
    • branch — git branch when present (Claude Code only)
    • cwd — working directory when present (Codex only)
    • ts and last_ts — session timestamps
    • match_count and keyword_matches — when keyword filtering was used
  • output_schema — the structure the agent's response should follow. Default schema:
    Structure your response with these sections (omit any with no findings):
    - What was tried before
    - What didn't work
    - Key decisions
    - Related context
    When the caller (e.g., ce-compound) supplies a schema in the skill argument, pass it through verbatim.

Example dispatch shape:

Synthesize findings from these prior sessions:

Problem topic: <one-line topic>

Sessions to read (paths in $SCRATCH):
1. /tmp/ce-sessions-XXXX/abc123.skeleton.txt
   platform=claude branch=feat/auth-fix ts=2026-05-01
2. /tmp/ce-sessions-XXXX/def456.skeleton.txt  errors=/tmp/ce-sessions-XXXX/def456.errors.txt
   platform=codex cwd=/Users/.../my-project ts=2026-05-03
...

Output schema:
- What was tried before
- What didn't work
- Key decisions
- Related context

Filter rule: only surface findings directly relevant to this specific problem.
Ignore unrelated work from the same sessions or branches.

The agent reads each path via the platform's native file-read tool and returns prose findings. Bulk extraction content lives only in the agent's subagent context — the orchestrator's working state stays at file paths plus small inventory metadata.

Step 7 — Return findings

Return the synthesizer's output text to the caller verbatim. If discovery or keyword filtering returned zero sessions (Step 2 or Step 3), return the literal string no relevant prior sessions instead.

Optionally clean up scratch:

rm -rf "$SCRATCH"

The OS handles cleanup eventually regardless; the explicit cleanup is for readers who expect it.

Output

When the caller (typically a user typing /ce-sessions, or another skill invoking ce-sessions via the platform's skill-invocation primitive) does not specify an output format, include a brief header noting what was searched:

**Sessions searched**: [count] ([N] Claude Code, [N] Codex, [N] Cursor) | [date range]

Then the synthesizer's prose findings. When the caller supplies a schema, honor it verbatim and omit the default header.

Time budget

Stop as soon as a complete answer is available. A confident "no relevant prior sessions" within seconds is a complete answer; do not extend the search to fill time. The structural caps in Step 3 (max 5 sessions deep-dived) and Step 5 (conditional tail/errors extraction) bound runtime by construction.

Error handling

If the discovery pipeline fails (e.g., unreadable home directory, permission failure), surface the error to the caller. Do not substitute git log, file listings, or other sources — this skill's contract is session metadata and synthesis.

If extraction --output write fails (disk full, permission), surface a clear error and do not dispatch the synthesizer with partial paths.

If _meta reports parse_errors > 0 from any script, note partial extraction in the dispatch prompt and proceed; the synthesizer flags partial in findings.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.