@letta-ai/letta-code 0.14.16 → 0.15.1

package/skills/migrating-from-codex-and-claude-code/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: Migrating from Codex and Claude Code
+description: 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.
+---
+
+# 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 `/init` to 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+cat ~/.claude/projects/<path>/<session>.jsonl | jq 'select(.type == "summary") | .summary'
+```
+
+### Common Workflows/Commands
+
+Look for patterns in Bash tool calls:
+```bash
+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](references/claude-format.md) - Claude Code JSONL structure
+- [references/codex-format.md](references/codex-format.md) - OpenAI Codex JSONL structure

package/skills/migrating-from-codex-and-claude-code/references/claude-format.md

@@ -0,0 +1,212 @@
+# Claude Code Data Format Reference
+
+## Directory Structure
+
+```
+~/.claude/
+├── history.jsonl              # Global prompt history
+├── projects/                  # Per-project data
+│   └── -Users-...-<path>/     # Encoded directory paths
+│       ├── sessions-index.json    # Quick session metadata
+│       ├── <session-uuid>.jsonl   # Full conversation sessions
+│       └── agent-<id>.jsonl       # Agent-specific sessions
+├── settings.json              # User preferences
+├── statsig/                   # Analytics
+└── debug/                     # Debug logs
+```
+
+## Path Encoding
+
+Claude encodes project paths by replacing `/` with `-`:
+```
+/Users/username/repos/myproject → -Users-username-repos-myproject
+```
+
+To encode a path programmatically:
+```bash
+ENCODED=$(pwd | sed 's|/|-|g')
+```
+
+## Global History (`history.jsonl`)
+
+Each line is a JSON object representing a user prompt:
+
+```json
+{
+  "display": "fix this test: npm run test:unit",
+  "pastedContents": {},
+  "timestamp": 1759105062139,
+  "project": "/Users/username/repos/myproject",
+  "sessionId": "0fd6a5d1-c1e4-494f-82d6-9391ccc1797d"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `display` | The user's prompt text |
+| `pastedContents` | Any pasted content (files, images) |
+| `timestamp` | Unix timestamp in milliseconds |
+| `project` | Working directory path |
+| `sessionId` | Links to session file |
+
+## Sessions Index (`sessions-index.json`)
+
+Quick metadata lookup without parsing full session files:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "sessionId": "0fd6a5d1-c1e4-494f-82d6-9391ccc1797d",
+      "fullPath": "/Users/username/.claude/projects/-Users-sarah-repos-myproject/0fd6a5d1-....jsonl",
+      "fileMtime": 1768524387632,
+      "firstPrompt": "fix the failing test in auth.ts",
+      "messageCount": 14,
+      "created": "2026-01-16T00:39:26.583Z",
+      "modified": "2026-01-16T00:46:27.609Z",
+      "gitBranch": "feature/auth-fix",
+      "projectPath": "/Users/username/repos/myproject",
+      "isSidechain": false
+    }
+  ]
+}
+```
+
+## Session Files (`<session-uuid>.jsonl`)
+
+Each line is a JSON object. Message types:
+
+### User Message
+
+```json
+{
+  "type": "user",
+  "uuid": "8705b595-71fb-4a97-be0b-edc2fe934724",
+  "parentUuid": null,
+  "sessionId": "079c7831-6083-4b29-9fe2-534da46f2585",
+  "cwd": "/Users/username/repos/myproject",
+  "gitBranch": "main",
+  "timestamp": "2025-12-23T03:01:20.501Z",
+  "message": {
+    "role": "user",
+    "content": "please help me fix the lint errors"
+  }
+}
+```
+
+### User Message with Tool Results
+
+When responding to tool calls, content is an array:
+
+```json
+{
+  "type": "user",
+  "message": {
+    "role": "user",
+    "content": [
+      {
+        "type": "tool_result",
+        "tool_use_id": "toolu_01FTU3GpL9GpoJXd8WitDSd2",
+        "content": "Exit code 0\nChecked 265 files...",
+        "is_error": false
+      }
+    ]
+  }
+}
+```
+
+### Assistant Message
+
+Content is always an array with multiple block types:
+
+```json
+{
+  "type": "assistant",
+  "uuid": "64064220-5503-44f1-8f3c-d6862b249309",
+  "parentUuid": "8705b595-71fb-4a97-be0b-edc2fe934724",
+  "message": {
+    "role": "assistant",
+    "model": "claude-opus-4-5-20251101",
+    "content": [
+      {
+        "type": "thinking",
+        "thinking": "The user wants me to fix linting errors. Let me first run the lint command.",
+        "signature": "EowCCkY..."
+      },
+      {
+        "type": "text",
+        "text": "I'll run the linter to see what errors exist:"
+      },
+      {
+        "type": "tool_use",
+        "id": "toolu_01FTU3GpL9GpoJXd8WitDSd2",
+        "name": "Bash",
+        "input": {
+          "command": "bun run lint",
+          "description": "Run linter"
+        }
+      }
+    ],
+    "usage": {
+      "input_tokens": 10,
+      "cache_creation_input_tokens": 4691,
+      "cache_read_input_tokens": 14987,
+      "output_tokens": 3
+    }
+  }
+}
+```
+
+### Content Block Types
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `thinking` | `thinking`, `signature` | Chain-of-thought reasoning |
+| `text` | `text` | Final response text |
+| `tool_use` | `id`, `name`, `input` | Tool invocation |
+
+### Summary Entry
+
+Auto-generated conversation summaries:
+
+```json
+{
+  "type": "summary",
+  "summary": "The user asked me to fix linting errors in the auth module...",
+  "leafMessageId": "abc-123",
+  "timestamp": "2025-12-23T03:05:00.000Z"
+}
+```
+
+## Settings (`settings.json`)
+
+```json
+{
+  "apiKey": "sk-ant-...",
+  "customApiKey": "sk-ant-...",
+  "permissions": {
+    "allow": ["Bash(npm run lint)", "Read"],
+    "deny": ["Bash(rm -rf)"]
+  }
+}
+```
+
+## Useful jq Queries
+
+```bash
+# List all unique projects with session counts
+cat ~/.claude/history.jsonl | jq -s 'group_by(.project) | map({project: .[0].project, count: length}) | sort_by(-.count)'
+
+# Extract all user messages from a session
+cat session.jsonl | jq 'select(.type == "user") | .message.content | if type == "string" then . else .[0].text // .[0].content // empty end'
+
+# Get all tool calls in a session
+cat session.jsonl | jq 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | {name, input}'
+
+# Find sessions that modified specific files
+cat session.jsonl | jq 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use" and .name == "Write") | .input.file_path'
+
+# Get token usage statistics
+cat session.jsonl | jq 'select(.type == "assistant") | .message.usage | select(. != null)'
+```

package/skills/migrating-from-codex-and-claude-code/references/codex-format.md

@@ -0,0 +1,229 @@
+# OpenAI Codex Data Format Reference
+
+## Directory Structure
+
+```
+~/.codex/
+├── history.jsonl              # Global prompt history
+├── sessions/                  # Per-session data, organized by date
+│   └── <year>/
+│       └── <month>/
+│           └── <day>/
+│               └── rollout-<timestamp>.jsonl  # Session files
+├── config.toml                # User configuration
+└── instructions.md            # Custom instructions file
+```
+
+## Global History (`history.jsonl`)
+
+Each line is a JSON object representing a user prompt:
+
+```json
+{
+  "text": "fix the failing test in auth.ts",
+  "ts": 1759105062
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `text` | The user's prompt text |
+| `ts` | Unix timestamp in seconds |
+
+Note: Unlike Claude Code, Codex history doesn't include the project path. You need to correlate with session files to determine project context.
+
+## Configuration (`config.toml`)
+
+```toml
+model = "o4-mini"
+
+[history]
+persistence = "across-sessions"
+save_inputs = true
+
+[[project_doc_approval]]
+project_directory = "/Users/username/repos/myproject"
+
+[[full_auto_approval]]
+project_directory = "/Users/username/repos/myproject"
+```
+
+Key fields:
+- `model` - Default model
+- `project_doc_approval` - Projects where docs auto-approval is enabled
+- `full_auto_approval` - Projects with full auto-approval (trusted)
+
+## Session Files (`rollout-<timestamp>.jsonl`)
+
+Each line is a JSON object. Event types:
+
+### Session Metadata
+
+First entry in each session file:
+
+```json
+{
+  "type": "session_meta",
+  "payload": {
+    "model_provider": "openai",
+    "model_name": "o4-mini",
+    "cwd": "/Users/username/repos/myproject",
+    "session_id": "sess_abc123",
+    "git": {
+      "branch": "main",
+      "commit": "abc1234"
+    }
+  },
+  "ts": 1759105062
+}
+```
+
+### User Message
+
+```json
+{
+  "type": "event_msg",
+  "payload": {
+    "type": "user_message",
+    "message": "fix the failing test in auth.ts"
+  },
+  "ts": 1759105063
+}
+```
+
+### Agent Reasoning
+
+```json
+{
+  "type": "event_msg",
+  "payload": {
+    "type": "agent_reasoning",
+    "text": "I need to look at the test file to understand what's failing..."
+  },
+  "ts": 1759105064
+}
+```
+
+### Function Call (Tool Use)
+
+```json
+{
+  "type": "response_item",
+  "payload": {
+    "type": "function_call",
+    "id": "fc_abc123",
+    "call_id": "call_abc123",
+    "name": "shell",
+    "arguments": "{\"command\":[\"cat\",\"src/tests/auth.test.ts\"]}"
+  },
+  "ts": 1759105065
+}
+```
+
+Common function names:
+- `shell` - Execute shell commands
+- `file_edit` - Edit files
+- `file_read` - Read files
+- `create_file` - Create new files
+
+### Function Call Output
+
+```json
+{
+  "type": "response_item",
+  "payload": {
+    "type": "function_call_output",
+    "call_id": "call_abc123",
+    "output": "import { test, expect } from 'bun:test';\n..."
+  },
+  "ts": 1759105066
+}
+```
+
+### Assistant Message
+
+```json
+{
+  "type": "response_item",
+  "payload": {
+    "type": "message",
+    "role": "assistant",
+    "content": [
+      {
+        "type": "output_text",
+        "text": "I found the issue. The test is failing because..."
+      }
+    ]
+  },
+  "ts": 1759105067
+}
+```
+
+### Background Event (Exec Approval)
+
+```json
+{
+  "type": "event_msg",
+  "payload": {
+    "type": "exec_approval_request",
+    "command": ["npm", "run", "test"]
+  },
+  "ts": 1759105068
+}
+```
+
+## Key Differences from Claude Code
+
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| **History format** | Includes project path | No project path |
+| **Session organization** | By project directory | By date |
+| **Path encoding** | Replace `/` with `-` | N/A |
+| **Tool call format** | `tool_use` blocks | `function_call` events |
+| **Thinking** | `thinking` blocks | `agent_reasoning` events |
+| **Timestamps** | Milliseconds | Seconds |
+| **Session index** | `sessions-index.json` | None (scan date dirs) |
+| **Config format** | JSON | TOML |
+
+## Useful jq Queries
+
+```bash
+# List all sessions with their project directories
+find ~/.codex/sessions -name "*.jsonl" -exec sh -c 'echo "$1: $(head -1 "$1" | jq -r ".payload.cwd // \"?\"" 2>/dev/null)"' _ {} \;
+
+# Get all user messages from a session
+cat rollout-*.jsonl | jq -r 'select(.type == "event_msg" and .payload.type == "user_message") | .payload.message'
+
+# Get all tool calls from a session
+cat rollout-*.jsonl | jq 'select(.type == "response_item" and .payload.type == "function_call") | {name: .payload.name, args: .payload.arguments}'
+
+# Find sessions that used shell commands
+cat rollout-*.jsonl | jq -r 'select(.type == "response_item" and .payload.type == "function_call" and .payload.name == "shell") | .payload.arguments | fromjson | .command | join(" ")'
+
+# Get assistant text responses
+cat rollout-*.jsonl | jq -r 'select(.type == "response_item" and .payload.type == "message" and .payload.role == "assistant") | .payload.content[]? | select(.type == "output_text") | .text'
+
+# Search history by keyword
+cat ~/.codex/history.jsonl | jq -r --arg kw "test" 'select(.text | test($kw; "i")) | "\(.ts | strftime("%Y-%m-%d %H:%M"))  \(.text)"'
+
+# Find all trusted projects
+grep -A1 "full_auto_approval" ~/.codex/config.toml 2>/dev/null
+```
+
+## Session File Naming
+
+Session files follow the pattern:
+```
+rollout-<ISO-timestamp>.jsonl
+```
+
+Example: `rollout-2025-12-23T03:01:20.501Z.jsonl`
+
+Sessions are organized by date:
+```
+sessions/
+└── 2025/
+    └── 12/
+        └── 23/
+            └── rollout-2025-12-23T03:01:20.501Z.jsonl
+```