playbooks

home / skills / terrylica / cc-skills / session-info

session-info skill

/plugins/statusline-tools/skills/session-info

This skill reveals the current Claude Code session UUID and registry details to aid debugging and session tracing.

npx playbooks add skill terrylica/cc-skills --skill session-info

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.7 KB
---
name: session-info
description: Get current Claude Code session UUID and registry info. TRIGGERS - current session, session uuid, session id, what session, which session.
---

# Session Info Skill

Returns the current Claude Code session UUID and registry information.

## When to Use This Skill

Use this skill when:

- Need to know the current session UUID for debugging
- Want to check the session chain history
- Verify the session registry is working
- Find correlation between sessions and transcripts

## Implementation

Run the session info script:

```bash
bun $HOME/.claude/plugins/marketplaces/cc-skills/plugins/statusline-tools/scripts/get-session-info.ts
```

## Output Format

The script outputs structured session information:

```
Current Session: c1c1c149-1abe-45f3-8572-fd77aa046232
Short ID: c1c1c149
Project: ~/.claude
Registry: ~/.claude/projects/-Users-terryli--claude/.session-chain-cache.json
Chain Length: 3 session(s)
Last Updated: 2026-01-15T21:30:00.000Z
Managed By: [email protected]

Metadata:
  Repo: cc-skills
  Hash: a1b2c3d4e5f6
  Branch: main
  Model: opus-4
  Cost: $0.42

Recent Sessions (last 5):
  1. 8e017a43 (2026-01-15T10:00:00.000Z)
  2. a2b3c4d5 (2026-01-15T14:00:00.000Z)
  3. c1c1c149 (2026-01-15T21:30:00.000Z)
```

## Registry Location

The session registry follows Claude Code's native path encoding:

```
~/.claude/projects/{encoded-path}/.session-chain-cache.json
```

Where `encoded-path` replaces `/` with `-`:

- `/Users/terryli/eon/cc-skills` → `-Users-terryli-eon-cc-skills`

## References

- [Registry Format](./references/registry-format.md) - Schema documentation

---

## Troubleshooting

| Issue                     | Cause                      | Solution                                         |
| ------------------------- | -------------------------- | ------------------------------------------------ |
| Script not found          | Plugin not installed       | Run `claude plugin list` to verify installation  |
| JSONL ID undefined        | No active session          | Start Claude Code session first                  |
| Registry file not found   | First session in project   | Registry created automatically on first session  |
| Chain length is 0         | Fresh project              | Normal for new projects, chain grows over time   |
| Metadata missing          | Older session format       | Recent sessions include metadata automatically   |
| Path encoding looks wrong | Special characters in path | Claude Code uses `-` to replace `/` in paths     |
| Bun not found             | Bun not installed          | Install with `brew install oven-sh/bun/bun`      |
| Permission denied         | Registry file permissions  | Check ~/.claude permissions (should be readable) |

Overview

This skill returns the current Claude Code session UUID and the session registry information for the active project. It helps you inspect session identity, chain history, metadata, and registry location for debugging and audit purposes. Output is structured and suitable for scripts or human review.

How this skill works

The skill reads the local session registry file for the active Claude Code project and extracts the current session UUID, short ID, chain length, last-updated timestamp, manager, and attached metadata. It also lists recent sessions and prints the registry path using Claude Code's encoded-path format. The tool is typically invoked via a small TypeScript script run with Bun.

When to use it

  • You need the current session UUID for debugging or logging correlation
  • Verify session chain length or session history for a project
  • Confirm that the session registry file exists and is being updated
  • Map transcripts or event logs back to a session ID
  • Validate metadata (model, cost, repo, branch) recorded for the last session

Best practices

  • Run the script from the same user account that owns ~/.claude to avoid permission issues
  • Use the short ID for quick human references and the full UUID for machine correlation
  • Check chain length and recent sessions to understand session lineage before blaming transient errors
  • If the registry file is missing, start a new Claude Code session to populate it automatically
  • Treat registry path encoding consistently: replace / with - when locating project registry

Example use cases

  • Debugging an unexpected model response by correlating transcript timestamps with the session UUID
  • Automating telemetry: include session UUID in CI logs to trace behavior across runs
  • Verifying that session metadata (model, repo, branch, cost) is captured after an update to plugins
  • Auditing recent sessions for a project to understand who or what initiated changes
  • Checking registry location and permissions when the client reports registry-read failures

FAQ

How do I run this tool?

Execute the provided TypeScript script with Bun, for example: bun $HOME/.claude/plugins/marketplaces/cc-skills/plugins/statusline-tools/scripts/get-session-info.ts

What if the registry file is missing?

A missing registry is normal for a project's first session; start a Claude Code session and the registry file will be created automatically

I get permission denied reading ~/.claude — what now?

Ensure the current user has read access to ~/.claude and its subfiles. Fix permissions or run the script as the owning user

What is the encoded path format for the registry file?

Registry path uses ~/.claude/projects/{encoded-path}/.session-chain-cache.json where / in the original path is replaced with - (dash)