Archive Session

IMPORTANT: Always invoke scripts with relative paths from the project root, never absolute paths. Permission rules use relative patterns -- absolute paths will not match and will trigger a prompt.

Archive Session

Archives the current Claude Code session transcript and any subagent logs, generating browsable HTML and Markdown files.

When to Use

• End of work session for audit trail
• Debugging session or subagent execution
• Before context gets too large

Arguments

• No arguments: archives to default location docs/process/claudeCodeSessions/exported-on-/
• --output=: archives to custom location
• Session ref (optional): last, last-1, last-2, or UUID

What It Does

1. Detects current session (most recently modified transcript)
2. Archives main session transcript (session.jsonl)
3. Archives subagent transcripts if present (subagents/)
4. Generates HTML and Markdown files via claude-code-log dependency, or uvx
5. Opens HTML in browser

Cross-Platform Support

Works on both macOS and Windows (Git Bash / MSYS2). The script handles the different path formats each OS uses for Claude Code's transcript storage.

Claude Code stores transcripts in ~/.claude/projects//, where ` is the project path with path separators and : replaced by -`.

macOS:

Project path:    /Users/dev/code/my-project
Transcript dir:  ~/.claude/projects/-Users-dev-code-my-project/

Windows (Git Bash / MSYS2):

Native path:     D:\code\my-project
Git Bash pwd:    /d/code/my-project
Transcript dir:  ~/.claude/projects/D--code-my-project/

On Windows, the script detects the MSYS /d/... path format and converts it back to the Windows-native D:/... form before computing the hash. This uses pure string operations (no cygpath dependency).

All bash features used are compatible with macOS's default bash 3.2.

Output Location

Default: docs/process/claudeCodeSessions/exported-on-/

Override: Set either CLAUDE_ARCHIVE_DIR env var or use --output= argument.

Location override: Useful in scenarios where you want to archive to a different location to fit other frameworks and processes.

For example, when using the Get Shit Done CC framework, a better location might be in .planning/sessions/, where that framework generates all of its other plans and records.

Default exported folder structure

docs/process/claudeCodeSessions/exported-on-2026-01-14_15-51-05/
├── session-info.txt      # Metadata
├── session.jsonl         # Main transcript
├── session.html          # Main session HTML
├── session.md            # Main session Markdown
└── subagents/            # If subagents exist
    ├── agent-a2bad1a.jsonl
    ├── agent-a2bad1a.html    # HTML per subagent
    ├── agent-a2bad1a.md      # Markdown per subagent
    ├── agent-b3cde2b.jsonl
    ├── agent-b3cde2b.html
    ├── agent-b3cde2b.md
    └── cache/                # Created by claude-code-log

Usage

Via Claude Code Skill:

# Archive current session (auto-detected, to default location)
/archive-session

# Archive specific session by UUID
/archive-session 602fca42-0159-466c-bdb7-00745e1939f1

# Archive using relative references
/archive-session last      # most recent session (same as no arg)
/archive-session last-1    # second most recent
/archive-session last-2    # third most recent

# Archive to custom location
/archive-session --output=./my-archives
/archive-session last-1 --output=./my-archives
/archive-session 602fca42-0159-466c-bdb7-00745e1939f1 --output=./my-archives

Direct Bash Execution:

# Archive current session
bash .claude/skills/archive-session/scripts/archive.sh

# Archive with relative reference
bash .claude/skills/archive-session/scripts/archive.sh last
bash .claude/skills/archive-session/scripts/archive.sh last-1

# Archive specific UUID
bash .claude/skills/archive-session/scripts/archive.sh 602fca42-0159-466c-bdb7-00745e1939f1

# Archive to custom location via env var
CLAUDE_ARCHIVE_DIR=~/some/other/path bash .claude/skills/archive-session/scripts/archive.sh

# Archive to custom location via arg
bash .claude/skills/archive-session/scripts/archive.sh --output=./my-archives
bash .claude/skills/archive-session/scripts/archive.sh last-1 --output=./my-archives

TUI for Richer Experience

For interactive session management, claude-code-log provides a TUI:

claude-code-log --tui
# or
uvx claude-code-log@latest --tui

Features: session list with timestamps/token counts, keyboard nav (h HTML, m Markdown, v view), cross-project traversal, c to resume sessions.

Dependencies

claude-code-log generates browsable HTML reports from transcript files. Primarily a TUI with CLI capabilities for batch export.

You can install it as a project dependency or run it on-demand:

Project dependency (recommended if using frequently):

uv add claude-code-log

Adds to pyproject.toml and installs via uv package manager.

On-demand execution (no install):

uvx claude-code-log@latest

uvx is uv's tool runner that fetches and runs packages without permanent installation.

The script checks for claude-code-log first, falls back to uvx. If neither available, transcripts are still archived but HTML generation is skipped.

Note: You can also use pip install claude-code-log, but we default to uv for convenience and speed.

Script Location

.claude/skills/archive-session/scripts/archive.sh

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lifeinchords
• Source: lifeinchords/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.