Skip to content
Back to skills

Session Trace

ASecurity

Publish an agent session as a readable trace page in Grain, with the story, key moments, every request and step on a timeline, subagents, and the pull requests it opened. Use when asked for a trace or "how did this run go", or when a task already has a Grain page (for example from prepare-pr or handoff).

  • 9 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added September 23, 2026
ai-agentsgonode

Works with

  • claude code

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned September 23, 2026

npx -y skills add greenfield-inc/agent-farm --skill session-trace --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Session Trace?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Session Trace
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/greenfield-inc-session-trace/badge)](https://www.skillsdirectory.com/skills/greenfield-inc-session-trace)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: session-trace
description: Publish an agent session as a readable trace page in Grain, with the story, key moments, every request and step on a timeline, subagents, and the pull requests it opened. Use when asked for a trace or "how did this run go", or when a task already has a Grain page (for example from prepare-pr or handoff).
---

# Session trace

Turn a session into a page someone who wasn't there can read in five minutes: what was asked, what happened, where it went right or wrong, and what came out of it. A raw log is the evidence, not the page.

Read [references/page-guide.md](references/page-guide.md) first. It says what the page must answer, what to capture beyond the trace, and how to lay it out. [scripts/build-trace.mjs](scripts/build-trace.mjs) is a working starting point for Claude Code and Codex logs. Adapt it, or build the same page shape another way, when a harness or task needs something else.

## When to run

- When the user asks for a trace, a run review, or a page they can share about a session.
- Without being asked, only when the task already has a Grain page (a PR companion from `prepare-pr`, or a `handoff` page), or the session opened a pull request. Then attach the trace to that page. Don't run it after every session.

## Steps

1. **Find the session log.**
   - Claude Code: `~/.claude/projects/<project>/$CLAUDE_CODE_SESSION_ID.jsonl`, with subagents under `<session id>/subagents/`.
   - Codex: the newest `~/.codex/sessions/**/rollout-*.jsonl` whose first line (`session_meta`) has this working directory and no `parent_thread_id`. Its subagents are the rollouts whose `parent_thread_id` is its `id`.
   - The script finds both on its own; pass `--session FILE` to choose.
   - Other harnesses: see "Other harnesses" in the page guide.
2. **Read the session for the story.** Run `node scripts/build-trace.mjs --out <tmp> --outline` to list every request with its anchor (`t0`, `t1`, …). Use what you remember of the session plus that outline to write `story.json`: a plain summary and 4–8 key moments, as described in the guide.
3. **Build the page.** Run `node scripts/build-trace.mjs --out <dir> --story story.json --title "<task>: session trace" --back index.html`. This writes `trace.html` and `trace.otlp.json` (OpenTelemetry spans). Open the page and check the story, the moments, and that the PRs you know about are listed. Add missing PRs, releases, or artifacts by hand or by extending the script.
4. **Review before publishing.** The page shows every user message in full, including anything pasted (meeting notes, logs, customer text). Only emails and tokens are redacted automatically. Remove or trim anything the page's readers shouldn't see, and ask when unsure.
5. **Publish with the `grain` skill.**
   - Add the page to the task's existing Grain workspace and link it from that workspace's main page, near the top.
   - With no existing page, create one in `Development Artifacts/<org>/<repo>`, named for the task.
   - Keep it private. Never create or widen a share. If the workspace already has a public share, tell the user the trace will be visible through it before you push.
6. **Report** the link, and anything you left out or couldn't capture.

Files in this skill

  • SKILL.md3.2 KB
  • references/page-guide.md5 KB
  • scripts/build-trace.mjs25.3 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.