CodexBridge CLI

A CLI tool that converts GPT-5.2-Codex session logs (JSONL) into structured Markdown files with YAML frontmatter, enabling natural language search powered by GPT-5.2.

Why CodexBridge?

Codex CLI stores session history as raw JSONL files buried in ~/.codex/sessions/. These files are large, unreadable, and impossible to search. CodexBridge solves this by:

• Parsing JSONL session logs into clean, human-readable Markdown
• Enriching sessions with AI-generated summaries, tags, and handoff context via GPT-5.2
• Searching across all your sessions using natural language queries
• Bridging sessions between Codex CLI and Claude Code with structured handoff context

Install

# npm
npm install -g codexbridge

# npx (no install, run directly)
npx codexbridge --help

# bun
bun add -g codexbridge

# bunx (no install, run directly)
bunx codexbridge --help

Or build from source:

git clone https://github.com/anthropics/codexbridge.git
cd codexbridge
npm install && npm run build
npm link

Setup

CodexBridge needs an OpenAI API key for AI-powered enrichment and search features.

# Option 1: Store in codexbridge config
codexbridge config set openai_api_key sk-proj-...

# Option 2: Use environment variable
export OPENAI_API_KEY=sk-proj-...

You can use all commands except index (with enrichment) and search without an API key.

Commands

codexbridge index - Index Codex Sessions

Parses Codex JSONL session files and converts them into structured Markdown with YAML frontmatter. By default, sessions are enriched with GPT-5.2 to generate summaries, tags, completed/todo tasks, and handoff context.

codexbridge index                     # Index 5 most recent sessions
codexbridge index -n 10               # Index 10 most recent sessions
codexbridge index -f ./session.jsonl  # Index a specific JSONL file
codexbridge index -d ./my-sessions    # Index from a custom directory
codexbridge index --no-enrich         # Skip AI enrichment (faster, no API key needed)
codexbridge index --skip-existing     # Skip sessions that are already indexed

What gets extracted from JSONL:

• Session ID, model, reasoning effort level
• Project name and working directory
• Token usage (input/output) and estimated cost
• All modified files (from apply_patch and edit_file calls)
• Bash commands with exit codes
• MCP tool calls
• AI reasoning notes
• Timestamps and duration

What GPT-5.2 adds during enrichment:

• Korean summary (1-2 sentences)
• English tags (up to 5, e.g. #authentication, #refactoring)
• Completed tasks list
• Remaining tasks list
• Handoff context for another developer to continue the work

codexbridge search - Natural Language Search

Search across all indexed sessions using natural language queries. Powered by GPT-5.2 semantic understanding.

codexbridge search "JWT token refactoring"
codexbridge search "dylib loading issues"
codexbridge search "yesterday's auth work"
codexbridge search "npm test failures"
codexbridge search -n 3 "database migration"    # Limit to 3 results

The search engine considers:

• Project name, tags, summary, and file names
• Time-related queries ("yesterday", "last week")
• Synonym matching ("auth" <-> "authentication", "login" <-> "sign in")
• Korean and English queries

Each result shows a relevance score and an explanation of why it matched.

codexbridge show - View Session Details

Display detailed information about a specific session.

codexbridge show abc12345             # Show full session details
codexbridge show abc12345 --json      # Output as JSON (for piping)
codexbridge show abc12345 --handoff   # Show only handoff context

The display includes:

• Model and reasoning effort
• Project name and duration
• Token usage and cost
• Tags
• Summary
• Completed and remaining tasks
• Modified files
• Tool usage breakdown (Bash, Edit, Patch, MCP)

You can use partial IDs - codexbridge will match the first session containing that string.

codexbridge list - List Sessions

List all indexed sessions with summaries and tags.

codexbridge list                      # List 10 most recent sessions
codexbridge ls                        # Alias for list
codexbridge ls -n 20                  # List 20 sessions
codexbridge ls --tag authentication   # Filter by tag
codexbridge ls --tag git              # Show only git-related sessions

codexbridge resume - Resume or Handoff

Get the command to resume a Codex session, or generate a structured handoff context for Claude Code.

codexbridge resume abc12345           # Output: codex --resume <full-id>
codexbridge resume abc12345 --claude  # Generate Claude Code handoff prompt
codexbridge resume abc12345 --copy    # Copy to clipboard (macOS)

The --claude flag generates a structured handoff that includes:

• Previous session context and summary
• Files involved
• Completed tasks
• Remaining tasks

This lets you seamlessly continue work started in Codex CLI using Claude Code (or vice versa).

codexbridge config - Configuration

Manage codexbridge settings stored in ~/.codexbridge/config.yaml.

codexbridge config set openai_api_key sk-proj-...   # Set API key
codexbridge config get openai_api_key               # Get a value
codexbridge config get                              # Show all config

Storage Structure

~/.codexbridge/
├── config.yaml          # Settings (API key, etc.)
├── sessions/
│   ├── 2026-02-20-abc12345.md    # Session as Markdown
│   ├── 2026-02-20-def67890.md
│   └── ...
└── index.json           # Search index cache

Session Markdown Format

Each session is stored as a Markdown file with YAML frontmatter:

---
id: 019c7a15-e5a4-7ae1-9199-e3468f7e3e27
source: codex
model: gpt-5.3-codex
reasoning_effort: xhigh
created_at: 2026-02-20T08:06:32.305Z
ended_at: 2026-02-20T08:16:44.079Z
duration: 10m
project: my-project
cwd: /Users/dev/projects/my-project
tokens:
  input: 128470
  output: 2105
  cost_usd: 0.2738
files_modified:
  - src/auth.ts
  - src/middleware.ts
tools:
  bash: 8
  edit: 0
  patch: 2
  mcp: 0
tags:
  - git
  - staging
  - workflow
summary: "Session summary generated by GPT-5.2"
---

# Session: abc12345

## Summary
...

## Tasks
### Completed
- ...

### Todo
- ...

## Tool Activity
...

## AI Reasoning Notes
...

## Handoff Context
...

Example Output

$ codexbridge index -n 3

Indexing 3 session(s)...

✔ 8f7e3e27 -> 저장소 상태를 확인하고 data/investment.csv를 스테이징
✔ 9162f1df -> 의존성 관련 변경 여부를 확인하고 커밋을 준비
✔ 4c1cea4b -> bun.lock과 package.json을 스테이징하고 diff 확인

Done: 3 session(s) indexed
  Sessions stored in ~/.codexbridge/sessions/


$ codexbridge list

Sessions (3)
------------------------------------------------------------

4c1cea4b | 2/20/2026 | 8m [tonydeal]
  의존성 관련 변경 사항을 커밋하기 위해 bun.lock과 package.json을 스테이징
  #git #dependencies #package-management

9162f1df | 2/20/2026 | 8m [tony]
  의존성 관련 변경 여부를 확인하고 커밋을 준비
  #git #workflow #dependencies

8f7e3e27 | 2/20/2026 | 10m [tonydeal]
  저장소 상태를 확인하고 data/investment.csv를 스테이징
  #git #staging #data


$ codexbridge search "의존성 관련 작업"

Search: "의존성 관련 작업"
--------------------------------------------------

019c79fe | 2/20/2026 [tonydeal] 97%
  의존성 관련 변경 사항을 커밋하기 위해 bun.lock과 package.json을 스테이징
  -> bun.lock과 package.json 스테이징 등 의존성 변경 사항과 가장 일치

019c79ff | 2/20/2026 [tony] 90%
  의존성 관련 변경 여부를 확인하고 커밋을 준비
  -> 의존성 변경 여부 점검 및 커밋 준비로 관련 작업과 잘 매칭

Use: codexbridge show <id> to view details

Tech Stack

• Runtime: Node.js (>=18)
• Language: TypeScript
• CLI Framework: Commander.js
• Terminal UI: chalk + ora
• YAML Parsing: yaml
• AI: OpenAI GPT-5.2 API (enrichment + semantic search)

How It Works

1. Parsing: Reads Codex JSONL session files and extracts structured data - session metadata, tool calls (exec_command, apply_patch, MCP), token usage, reasoning notes, and timestamps.

2. Enrichment: Sends the parsed session context to GPT-5.2, which generates a Korean summary, English tags, task lists, and handoff context.

3. Storage: Saves each session as a Markdown file with YAML frontmatter in ~/.codexbridge/sessions/ and updates a JSON index for fast lookups.

4. Search: Sends the user's natural language query along with session metadata to GPT-5.2, which performs semantic matching and returns ranked results with explanations.

Codex JSONL Format

CodexBridge parses the following entry types from Codex CLI session logs:

| Entry Type | Payload Type | Data Extracted | |-----------|-------------|---------------| | session_meta | - | Session ID, CWD | | turn_context | - | Model name, reasoning effort | | event_msg | token_count | Input/output tokens | | event_msg | agent_reasoning | AI reasoning notes | | event_msg | user_message | User prompts | | response_item | function_call | exec_command (bash), edit_file, write_file | | response_item | custom_tool_call | apply_patch (file modifications), MCP tools |

Roadmap

v0.2 - Multi-Source Support

• [ ] Claude Code session parsing (.jsonl from ~/.claude/)
• [ ] GitHub Copilot session support
• [ ] Auto-indexing with file watcher (codexbridge watch)
• [ ] Configurable AI model (swap between GPT-5.2, GPT-5.3, etc.)

v0.3 - Web Dashboard

• [ ] Local web UI for browsing sessions (codexbridge dashboard)
• [ ] Timeline view - visualize sessions on a calendar
• [ ] Session diff view - compare what changed between sessions
• [ ] Token usage analytics and cost tracking over time
• [ ] Tag-based filtering and faceted search in the browser
• [ ] Export sessions as PDF or HTML reports

v0.4 - Team Collaboration

• [ ] codexbridge push - push session data to a shared remote (GitHub repo, S3, or custom server)
• [ ] codexbridge pull - pull teammate's sessions into your local index
• [ ] GitHub-based sharing - store sessions as .md files in a shared repo

  codexbridge remote add origin [email protected]:team/sessions.git
  codexbridge push                    # Push new sessions to shared repo
  codexbridge pull                    # Pull teammate sessions
  codexbridge search "auth refactor"  # Search across team sessions

• [ ] Team activity feed - see what your teammates worked on
• [ ] Session comments and annotations
• [ ] Role-based access control for sensitive sessions

v1.0 - Production Ready

• [ ] Hosted dashboard (SaaS) with team management
• [ ] SSO and organization support
• [ ] Webhook integrations (Slack, Discord, Linear)
• [ ] API for programmatic access to session data
• [ ] Session analytics - most edited files, tool usage patterns, cost trends
• [ ] AI-powered session recommendations ("You worked on auth last week, here's the context")

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

# Development setup
git clone https://github.com/anthropics/codexbridge.git
cd codexbridge
npm install
npm run dev          # Watch mode - auto-rebuild on changes

License

MIT