Project Memory for Codex

Codex Session Indexer

Turn local Codex history into clean project markdown files so each repository keeps its own readable session history.

This does not modify Codex's built-in Recent Tasks UI. It is a local workaround that generates per-project Markdown indexes from the session store Codex already keeps on disk.

Stephen Joly Python CLI Incremental Sync Optional Watcher
Default install 
curl -fsSL https://raw.githubusercontent.com/stephenjoly/codex-session-indexer/main/install.sh | bash

The installer prefers pipx when it is available and falls back to an isolated venv when it is not. Update later by rerunning the same install command, and check the installed version with codex-sessions version.

GitHub Installer Script Uninstall Script
Rendered preview

Codex Sessions

Generated: 2026-04-01 16:07:03Z
This file is fully generated by codex-sessions generate.
Directory: /Users/stephenjoly/Documents/Coding/market-call-summaries
Session count: 7

Most Recent Sessions

  1. Secure Supabase public table | updated 2026-04-01 16:02:34Z | 8 prompts | 2h 56m 11s
  2. Add Docker deployment files | updated 2026-04-01 11:03:41Z | 27 prompts | 20h 46m 39s
  3. Restart app after Supabase recovery | updated 2026-03-24 13:50:55Z | 1 prompt | 33s

Most Active Sessions

  1. Outline project overview | 80 prompts | 86h 43m 48s
  2. Add Docker deployment files | 27 prompts | 20h 46m 39s
  3. Secure Supabase public table | 8 prompts | 2h 56m 11s
Session Last updated Lifetime Prompts
Secure Supabase public table 2026-04-01 16:02:34Z 2h 56m 11s 8
Add Docker deployment files 2026-04-01 11:03:41Z 20h 46m 39s 27
Report current project status 2026-03-24 01:08:57Z 43m 54s 8
What It Does

Codex already keeps the history. This puts it back where the work happened.

It reads ~/.codex/sessions, groups sessions by exact working directory, and writes codex-sessions.md into the affected projects plus one global recent-session index.

Why It Helps

Three things matter.

  • Readable first

    Recent sessions and active sessions show up before the full table.

  • Cheap to keep current

    Incremental sync means unchanged projects do not get rewritten.

  • Fits the way Codex is used

    Run it manually, keep a foreground watcher open, or install a macOS daemon for background updates.

  • Simple install path

    One command installs the CLI cleanly with pipx when available, without leaving a repo checkout behind.

Install Modes

One default path for most people, one always-on path for heavy daily use.

Manual / Incremental

Run it when you want a refresh

The default path. Install once, then call generate whenever you want fresh indexes.

  • No long-running process required
  • Fast incremental sync by default
  • Best fit for most users
codex-sessions generate --global-root "$HOME/Documents/Coding" --verbose
Watch / Daemon

Choose foreground or background watching

watch runs in the foreground and stays attached to your shell. If you want a background watcher on macOS, rerun the installer with --daemon.

  • watch is for live terminal use
  • --daemon installs a macOS launchd watcher
  • Good fit for heavy Codex workflows
codex-sessions watch --global-root "$HOME/Documents/Coding" --verbose
curl -fsSL https://raw.githubusercontent.com/stephenjoly/codex-session-indexer/main/install.sh | bash -s -- --daemon
Uninstall

Remove the tool without touching the generated project files.

The uninstall script removes the installed CLI, symlink, watcher, and local state. It leaves codex-sessions.md files in place so it does not delete project files unexpectedly. 

curl -fsSL https://raw.githubusercontent.com/stephenjoly/codex-session-indexer/main/uninstall.sh | bash
How It Works

Short path, local state, deterministic output.

  1. Read the session store Parse session files from ~/.codex/sessions and thread names from ~/.codex/session_index.jsonl.
  2. Derive project summaries Calculate titles, timestamps, prompt counts, recent highlights, and active-session rankings from the underlying session events.
  3. Write only where needed Update the exact project codex-sessions.md files affected by changes, plus the global index when relevant.
  4. Persist sync state Keep incremental state in ~/.codex/codex-session-indexer-state.json so the next run can skip unchanged work.
Links

The whole release surface is small on purpose.

Installer Script Uninstall Script GitHub Repository