Coding session transcripts

Session transcripts let SuperPenguin explain an expensive coding session, for example one that kept retrying a failing tool call and paid again for the same context each time. They are off by default. An organization owner turns them on for the whole organization; there is no per-person setting.

A small hook uploads each session's transcript as it goes and when it ends. SuperPenguin keeps each transcript for 90 days. An owner can delete every stored transcript at any time.

Turn it on

An organization owner opens Settings → AI coding → Coding session transcripts and turns on Capture session transcripts.

Turning it off stops new uploads straight away. Stored transcripts stay until they expire, or until an owner presses Delete stored transcripts, which requires capture to be off first.

Laptops

Run the coding telemetry installer with --with-transcripts:

curl -fsSL https://app.superpenguin.ai/install | sh -s -- --with-transcripts

It checks that your organization has turned transcripts on, installs the upload hook, and registers it for Claude Code and, if installed, Codex. Codex asks you to trust a new hook once: open Codex and review it with /hooks.

A Claude Code transcript uploads when a session ends (when you exit, run /clear, or switch sessions) and, while it is open, in the background after Claude finishes a turn, at most once every 10 minutes per session. A long-running session therefore shows up without being closed, missing at most its last 10 minutes until it ends. Codex sessions upload when they end.

The same hooks run in the Claude Code desktop app and the VS Code and JetBrains extensions, which read ~/.claude/settings.json like the terminal. The desktop app's cloud sessions do not; set those up as described under Cloud environments.

Check the setup any time:

curl -fsSL https://app.superpenguin.ai/install | sh -s -- --status

Under Session transcripts you should see hook: installed, key: set, a SessionEnd hook set line for each tool, and Claude Code: Stop hook set. Remove everything with --uninstall.

Cloud environments (Claude Code on the web)

Cloud sessions work differently from laptops in three ways, so they need their own setup:

• Cloud sessions run hooks only from the repository's .claude/settings.json and from your organization's server-managed settings. They do not read ~/.claude/settings.json.
• Claude Code does not pass OTEL_* variables to hooks, so the hook cannot reuse the telemetry key.
• A cloud session often stops without a clean exit. The hook therefore also uploads after Claude finishes a turn, at most every five minutes, and once more if the session ends cleanly. The last few minutes of a session can be missing.

Set it up once per environment and repository:

1. Environment variables. In SuperPenguin, open Settings → AI coding → Claude Code cloud environment and create a key for the environment. When your organization has transcripts on, the variables shown include SUPERPENGUIN_API_KEY, and SUPERPENGUIN_USER_EMAIL when your email can be used. Paste all of them into the environment's Environment variables in Claude Code.

2. Network access. Allow app.superpenguin.ai in the environment's network access. Choose Custom and add it to the allowed domains, keeping the defaults.

3. Setup script. Add this line to the environment's setup script. It installs the hook, and || true keeps a network problem from stopping the session:

   curl -fsSL https://app.superpenguin.ai/install | sh -s -- --cloud --with-transcripts || true

4. Hooks. Merge this block into the repository's .claude/settings.json and commit it. To cover every repository, add it to your organization's server-managed settings instead. A cloud session that opens several repositories at once does not load repository hooks, so it needs server-managed settings. The hooks do nothing on laptops, so committing them is safe for everyone on the team.

   {
     "hooks": {
       "SessionEnd": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "bash \"$HOME/.superpenguin/hooks/coding-transcript-hook.sh\" --tool claude_code --only-remote 2>/dev/null || true",
               "timeout": 30
             }
           ]
         }
       ],
       "Stop": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "bash \"$HOME/.superpenguin/hooks/coding-transcript-hook.sh\" --tool claude_code --only-remote --min-interval 300 2>/dev/null || true",
               "async": true
             }
           ]
         }
       ]
     }
   }

Verify a cloud environment

Start a new cloud session on the repository and send one prompt. Then ask Claude to run this, which uploads the current transcript and prints the result:

f=$(ls -t ~/.claude/projects/*/*.jsonl | head -1); printf '{"session_id":"%s","transcript_path":"%s"}' "$(basename "$f" .jsonl)" "$f" | CLAUDE_CODE_REMOTE=true SUPERPENGUIN_HOOK_DEBUG=1 bash ~/.superpenguin/hooks/coding-transcript-hook.sh --tool claude_code

Expect stored … bytes. These are the other results:

Codex cloud (pending verification)

The same pattern should work for Codex cloud environments, but it has not been verified yet:

1. Run the setup script line.
2. Add a SessionEnd hook to $CODEX_HOME/hooks.json that runs bash "$HOME/.superpenguin/hooks/coding-transcript-hook.sh" --tool codex --background, with a timeout of 3 seconds.
3. Set SUPERPENGUIN_API_KEY in the environment.

Use it only for testing until this section says it is supported.

Limits

• Transcripts larger than 4 MiB after compression (roughly 30 to 45 MB of raw transcript) are skipped. SuperPenguin records that a session was skipped and its size, never its content.
• Uploads use the organization's SDK key and are refused unless the organization has turned transcripts on.
• Transcripts are kept for 90 days, then deleted automatically.