Agent skill
Migrating from Codex and Claude Code
Find and search historical conversation data from Claude Code and OpenAI Codex CLIs. Use when you need to understand a user's coding patterns, learn about a project from past sessions, or bootstrap agent memory from historical context.
Install this agent skill to your Project
npx add-skill https://github.com/letta-ai/letta-code/tree/main/src/skills/builtin/migrating-from-codex-and-claude-code
SKILL.md
Migrating from Codex and Claude Code
This skill helps you discover, search, and extract useful information from historical Claude Code and OpenAI Codex conversations stored on the user's machine.
When to Use This Skill
- During
/initto bootstrap agent memory with project context - When the user asks about their previous coding sessions
- To understand coding patterns, preferences, or project history
- To find context about a specific project or problem the user worked on before
Scripts
This skill includes ready-to-use scripts for common operations:
| Script | Purpose |
|---|---|
scripts/detect.sh |
Detect available history and show summary |
scripts/list-sessions.sh |
List sessions for a project |
scripts/search.sh |
Search across all history by keyword |
scripts/view-session.sh |
View a session in readable format |
Quick Start
# Detect what history data exists
./scripts/detect.sh
# List sessions for current project
./scripts/list-sessions.sh claude
./scripts/list-sessions.sh codex
# Search for a keyword across all history
./scripts/search.sh "database migration"
./scripts/search.sh "auth" --claude --project /path/to/project
# View a specific session
./scripts/view-session.sh ~/.claude/projects/-path-to-project/session.jsonl
./scripts/view-session.sh session.jsonl --tools --thinking
Data Locations
Claude Code (~/.claude/)
| Path | Contents |
|---|---|
history.jsonl |
Global prompt history (all projects) - always available |
projects/<encoded-path>/ |
Per-project conversation sessions - may not exist for older projects |
projects/<encoded-path>/sessions-index.json |
Quick session metadata lookup |
projects/<encoded-path>/<session-uuid>.jsonl |
Full conversation history |
settings.json |
User preferences (model, plugins) |
Path Encoding: Claude encodes project paths by replacing / with -:
/Users/foo/repos/myproject→-Users-foo-repos-myproject
Important: Session files may not exist for older projects (cleaned up or not persisted). In this case, history.jsonl still contains the user's prompts but not full conversations. The scripts will automatically fall back to searching history.jsonl.
OpenAI Codex (~/.codex/)
| Path | Contents |
|---|---|
history.jsonl |
Global prompt history — uses .ts (seconds) and .text fields (NOT .timestamp/.display) |
sessions/<year>/<month>/<day>/rollout-*.jsonl |
Session files by date |
config.toml |
User config (model, trusted projects) |
Important format difference: Codex uses .ts (seconds) and .text, while Claude uses .timestamp (milliseconds) and .display. Adjust jq queries accordingly.
Quick Searches
Find Sessions for Current Project
# For Claude Code - encode current path
ENCODED=$(pwd | sed 's|/|-|g')
ls ~/.claude/projects/$ENCODED/ 2>/dev/null
# Check sessions index for quick metadata
cat ~/.claude/projects/$ENCODED/sessions-index.json 2>/dev/null | jq '.entries[] | {firstPrompt, messageCount, modified}'
# If session files don't exist, search history.jsonl instead
cat ~/.claude/history.jsonl | jq --arg p "$(pwd)" 'select(.project == $p)'
Search by Project Name (Fallback)
When session files don't exist (older/cleaned up projects), search history.jsonl:
# Search by exact project path
cat ~/.claude/history.jsonl | jq 'select(.project == "/path/to/project")'
# Search by project name (partial match)
cat ~/.claude/history.jsonl | jq 'select(.project | contains("project-name"))'
# List all prompts for a project
cat ~/.claude/history.jsonl | jq -r 'select(.project | contains("myproject")) | "\(.timestamp / 1000 | strftime("%Y-%m-%d %H:%M")) \(.display[0:80])..."'
Search Prompt History
# Claude - search all prompts
cat ~/.claude/history.jsonl | jq 'select(.display | test("keyword"; "i"))'
# Codex - search all prompts (.text field, .ts in seconds)
cat ~/.codex/history.jsonl | jq 'select(.text | test("keyword"; "i"))'
Find User Messages in Sessions
# Claude - extract user messages from a session
cat ~/.claude/projects/<path>/<session>.jsonl | jq 'select(.type == "user") | .message.content'
# Codex - extract user messages from a session
cat ~/.codex/sessions/<path>/rollout-*.jsonl | jq 'select(.type == "event_msg" and .payload.type == "user_message") | .payload.message'
Analyze Tool Usage Patterns
# Claude - what tools does the user's assistant use most?
cat ~/.claude/projects/<path>/<session>.jsonl | jq 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name' | sort | uniq -c | sort -rn
# Codex - tool usage
cat ~/.codex/sessions/<path>/rollout-*.jsonl | jq 'select(.type == "response_item" and .payload.type == "function_call") | .payload.name' | sort | uniq -c | sort -rn
Extracting Context for Memory Blocks
Projects the User Has Worked On
# Claude - list all projects with activity counts
cat ~/.claude/history.jsonl | jq -s 'group_by(.project) | map({project: .[0].project, count: length}) | sort_by(-.count)'
Recent Session Summaries
Claude sessions may contain summary entries:
cat ~/.claude/projects/<path>/<session>.jsonl | jq 'select(.type == "summary") | .summary'
Common Workflows/Commands
Look for patterns in Bash tool calls:
cat ~/.claude/projects/<path>/<session>.jsonl | jq 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use" and .name == "Bash") | .input.command' | head -20
Detailed Format Documentation
For complete format specifications, see:
- references/claude-format.md - Claude Code JSONL structure
- references/codex-format.md - OpenAI Codex JSONL structure
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
letta-ai/letta-code
adding-models
Guide for adding new LLM models to Letta Code. Use when the user wants to add support for a new model, needs to know valid model handles, or wants to update the model configuration. Covers models.json configuration, CI test matrix, and handle validation.
letta-ai/letta-code
searching-messages
Search past messages to recall context. Use when you need to remember previous discussions, find specific topics mentioned before, pull up context from earlier in the conversation history, or find which agent discussed a topic.
letta-ai/letta-code
converting-mcps-to-skills
Connect to MCP (Model Context Protocol) servers and create skills for repeated use. Load when a user wants to use an MCP server, connect to external tools via MCP, or when they mention MCP, model context protocol, or specific MCP servers.
letta-ai/letta-code
working-in-parallel
Guide for working in parallel with other agents. Use when another agent is already working in the same directory, or when you need to work on multiple features simultaneously. Covers git worktrees as the recommended approach.
letta-ai/letta-code
migrating-memory
Migrate memory blocks from an existing agent to the current agent. Use when the user wants to copy or share memory from another agent, or during /init when setting up a new agent that should inherit memory from an existing one.
letta-ai/letta-code
creating-skills
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations.
Didn't find tool you were looking for?