session-detail

session-detail

Version 3.0.0. A reusable session archive and recovery skill for Codex, Claude.ai, Claude Code skill invocation, and Cowork. Includes Windows PowerShell and POSIX guidance. Licensed under MIT.

The skill records available session evidence so another session or machine can resume with the right decisions, artifact versions, validation results, and remaining work. It does not recover conversation text that is no longer available. An archive does not authorize future commands or releases.

Output

Each archive contains exactly two top-level tagged sections:

• <session_full>: objectives, accomplished work, decisions, corrections, failures, safe prompts, artifacts, validation, release state, and recovery instructions.
• <context_updates>: persistent facts, corrected facts, acceptance limits, open questions, and carry-forward warnings.

Credentials, tokens, cookies, private keys, private customer/transaction facts, and raw sensitive source quotes are removed. Safe receipt locations and artifact hashes identify evidence that must be restored through a separate approved private transfer. Git publication and private-file transfer are separate.

Use

Invoke the installed skill with any of these requests:

session detail
full session detail
session-detail full
session detail incremental
session-detail inc

In Codex you can also invoke $session-detail. A human can authorize archives at major milestones. The skill does not create timers, services, or recurring automations.

An incremental needs verified current-session identity, a verified covered conversation position, and enough evidence to separate old work from new work. If any requirement is missing, including after compaction, the skill writes a full archive from the evidence that remains. An explicit incremental request cannot make an uncertain boundary valid. A verified sequence can continue even when the mode returns to full.

Install in Codex

Ask Codex to install the skill from this repository:

Use $skill-installer to install session-detail from https://github.com/thebpandey/session-detail.

For a manual Windows install that applies across repositories, use a fresh destination in PowerShell:

$sessionSkillParent = Join-Path $env:USERPROFILE '.agents\skills'
$sessionSkillPath = Join-Path $sessionSkillParent 'session-detail'
if (Test-Path -LiteralPath $sessionSkillPath) {
    throw 'A skill already exists here. Inspect it before updating; do not overwrite local changes.'
}
New-Item -ItemType Directory -Path $sessionSkillParent -Force | Out-Null
git clone https://github.com/thebpandey/session-detail.git $sessionSkillPath

For a manual POSIX install:

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/thebpandey/session-detail.git "$HOME/.agents/skills/session-detail"

Codex also supports repository skills under .agents/skills/session-detail/. Keep SKILL.md and its references/ directory together. Avoid installing multiple same-named copies unless you deliberately manage their versions. Existing installations in a legacy location should be inspected before copying or replacing them.

Codex detects skill changes automatically. If the skill is absent from the selector, restart Codex. See official skill installation and discovery guidance.

If the installation is a clean Git clone, update it with a fast-forward pull:

git -C $sessionSkillPath status --short
git -C $sessionSkillPath pull --ff-only

Inspect local changes before the pull. For a copied installation without Git metadata, ask the installer to update it while preserving local customizations. Do not delete an existing skill folder to make an update pass.

Codex archive storage

Codex writes a local file first. The default is:

<CODEX_HOME>/session-details/<safe-project-name>/<verified-CODEX_THREAD_ID>/

When CODEX_HOME is unset, use the user's .codex directory. An unverified identity gets a separate explicitly unverified location and full mode. The skill reads only the needed identity/home values; it does not dump environment variables or inspect credential stores.

Filenames include an observed timestamp, a safe thread hint, mode, and verified sequence. Files are created exclusively; earlier archives are never overwritten. A repository destination requires explicit human approval and a path that Git already ignores. The skill does not add ignore rules or commit archives automatically.

Recovery on another machine

The archive records what must be restored separately: tracked code, authoritative tracker state, ignored private originals/readers/receipts, runtimes, installed skill version, and account capabilities. It records exact verification and acceptance limits rather than treating a completed lane, a render, or a commit as proof of overall success.

Read the recovery guidance for the complete evidence and platform contract. Read current repository instructions and current tracker state before acting. Recheck hashes and restore private evidence through an approved channel. Do not reuse archived commands, deployment permissions, or candidate values as new authority.

Claude compatibility

The shared SKILL.md describes Claude.ai and Cowork file/chat delivery and Claude Code skill invocation. Install this directory in the skill location supported by your Claude environment.

The separately packaged legacy Claude Code slash command remains unchanged for existing users. It uses its older _sessions/ and checkpoint workflow. It does not implement the 3.0 skill's identity, storage, or recovery rules. Use the shared skill when you need this release's workflow; the slash command is not a Codex installer or command.

See CHANGELOG.md for release history. This repository contains reusable instructions only; it contains no session archives or project-specific recovery data.