chat-history
Extract and organize Claude Code session history into project .chats directory. Use when users want to document their Claude sessions, export conversation inputs, or maintain a log of instructions given to Claude.
How do I install this agent skill?
npx skills add https://github.com/tyrchen/claude-skills --skill chat-historyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill extracts and organizes Claude Code session history from the user's home directory. It accesses sensitive chat logs but keeps the data within the local environment for documentation purposes.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
Chat History Extractor
Extract user inputs from Claude Code session history (~/.claude/projects/) and organize them into a project's .chats directory with daily markdown files.
When to Use This Skill
Use this skill when the user wants to:
- Extract session history from Claude Code sessions
- Document conversations for future reference
- Create instruction logs organized by date
- Export user inputs from
.jsonlsession files - Maintain a changelog of Claude interactions
How It Works
Claude Code stores session data in ~/.claude/projects/{project-path-encoded}/ as .jsonl files. Each file contains messages with:
type: "user"- User messagesuserType: "external"- External user (not system/agent)message.content- The actual message content
This skill extracts meaningful user instructions (filtering out system commands, tool results, and session continuations) and organizes them by date into .chats/{YYYYMMDD}.md files.
Instructions
Step 1: Identify the Project Session Directory
The session directory is derived from the current working directory path:
- Replace
/with-in the path - Prefix with
- - Location:
~/.claude/projects/{encoded-path}/
# Example: /Users/tchen/projects/tubi/titc
# Becomes: -Users-tchen-projects-tubi-titc
# Full path: ~/.claude/projects/-Users-tchen-projects-tubi-titc/
Step 2: Find Session Files by Date
List session files and filter by modification date:
# List all main session files (excluding agent-* files) for a specific date
ls -la ~/.claude/projects/{project-dir}/*.jsonl | grep "Dec 25" | grep -v agent-
Step 3: Extract User Inputs
Extract user messages from jsonl files using jq:
cat {session-file}.jsonl | jq -r '
select(.type == "user" and .userType == "external" and (.isMeta | not)) |
.message.content |
if type == "string" then . else empty end
' | grep -v "^Caveat:" \
| grep -v "^<command" \
| grep -v "^<local-command" \
| grep -v "^This session is being continued" \
| grep -v "^<user-prompt-submit-hook>" \
| grep -v "^Analysis:" \
| grep -v "^$"
Step 4: Create/Update .chats Files
Create markdown files in .chats/ directory with format:
# Instructions
## {task title}
{user instruction}
## {another task title}
{another user instruction}
Step 5: Commit Changes
After creating/updating chat files, commit with:
git add .chats/*.md
git commit -m "docs(chats): add session history for {date range}"
File Format
Each .chats/{YYYYMMDD}.md file should:
- Start with
# Instructionsheader - Use
##for each major task/instruction - Include the actual user input text
- Group related instructions under the same heading
- Preserve code blocks and formatting
Example Output
.chats/20251225.md:
# Instructions
## implement feature X
based on @specs/feature-x.md implement all phases entirely
commit the code and test
## fix bug Y
investigate why component Z is not working
use sub agents to analyze the issue in parallel
Filtering Rules
Include:
- Direct user instructions and requests
- Questions about the codebase
- Task specifications and requirements
Exclude:
- System commands (
<command-name>,<local-command-stdout>) - Session continuation messages
- Tool results and agent responses
- Hook notifications (
<user-prompt-submit-hook>) - Empty lines and caveat messages
Workflow Summary
- Get current working directory
- Compute encoded project path
- Find session directory:
~/.claude/projects/{encoded-path}/ - List sessions grouped by date
- For each date with sessions:
- Extract user inputs from all sessions
- Create
.chats/{YYYYMMDD}.md - Organize inputs with descriptive headers
- Create
.chats/directory if it doesn't exist - Optionally commit the changes
Helper Script
You can use this bash snippet to quickly find the project session directory:
# Get encoded project path
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^|/|' | sed 's|^/|-|')
SESSION_DIR="$HOME/.claude/projects/$PROJECT_PATH"
# Check if exists
if [ -d "$SESSION_DIR" ]; then
echo "Session directory: $SESSION_DIR"
echo "Sessions by date:"
ls -la "$SESSION_DIR"/*.jsonl 2>/dev/null | grep -v agent- | awk '{print $6, $7}' | sort -u
else
echo "No session directory found for this project"
fi
Notes
- Session files named
agent-*.jsonlare sub-agent sessions and typically don't contain direct user input - Main session files have UUID-style names (e.g.,
01e78099-de0e-4424-845c-518638c8241e.jsonl) - The
.message.contentfield can be either a string (user text) or an array (tool results) - Always verify the extracted content makes sense before committing
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tyrchen/claude-skills/chat-history">View chat-history on skillZs</a>