codex-threads

Manage local Codex threads from the command line.

Install

npm install -g codex-threads

This package installs the codext command.

Optional Agent Skill

This repo also maintains an optional agent skill for coding agents that can install SKILL.md bundles from GitHub. The skill is not required to run codext; the npm package ships only the CLI runtime.

Any compatible coding agent can install the same skills/codext-usage path from GitHub. If you are using Codex's built-in GitHub skill installer, pin the skill to the same release tag as the CLI you installed:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo Dikevin/codex-threads \
  --path skills/codext-usage \
  --ref codex-threads-v0.2.0

Replace --ref with the release tag that matches your installed CLI version. Restart or reload your coding agent after installing the skill if it caches available skills.

Quick Start

TUI first:

codext

• Opens the thread manager when stdout is a TTY
• Shows only persisted + not loaded threads
• Keeps Active and Archived in separate tabs
• On roomy terminals, the list shows Repo, Token, and Updated
• Token is the latest compact input/output total from the thread's rollout file, for example 183k/944

Command-line first:

codext list --json
codext list --archived --json
codext show <thread-id> --json
codext title suggest <thread-id> --json
codext title set <thread-id> --title "New title"
codext title rewrite <thread-id...> --json
codext log
codext watch

Local Development

Run from source:

pnpm install
pnpm exec tsx src/cli.ts --help
pnpm exec tsx src/cli.ts list --json

Build the distributable CLI:

pnpm build
node dist/cli.js --help
node dist/cli.js list --json

Link a local global codext command:

pnpm build
npm link
codext --help

Remove the local global link:

npm unlink -g codex-threads
hash -r

Usage

codext
codext list --json
codext list --archived --json
codext show <thread-id> --json
codext title suggest <thread-id> --json
codext title set <thread-id> --title "New title"
codext title rewrite <thread-id...> --json
codext title rewrite --all-matching --range 30d --json
codext archive <thread-id...>
codext archive --all-matching --range 30d --exclude-id <thread-id>
codext unarchive <thread-id...>
codext unarchive --all-matching --range 30d
codext log [--json]
codext watch [--detach|--status|--stop]
codext --account <codexm-account> watch
codext completion zsh > ~/.zsh/completions/_codext
codext --root-dir /path/to/codex-home list --json

Current behavior:

• Bare codext opens a TUI on a TTY
• Non-TTY bare invocation prints help
• The TUI shows only persisted + not loaded threads
• Active and Archived live in separate tabs
• list --archived exposes the archived tab to scripts
• Thread lists are grouped with recent-time bucket separators like <1d, <3d, <1w, <2w, <1m, and older
• Search is tab-local and applied on Enter
• TUI range filtering is session-global and currently supports 1d / 7d / 30d / all-time
• title rewrite uses codex exec --json with compressed thread context, strips plan noise, and records rewrite token usage plus thread token snapshots
• Automatic rewrites skip threads with unchanged content, skip titles that were set manually outside codext, and freeze threads whose title diverged from the last codext-managed value
• watch scans both active and archived manageable threads in the last 30 days, waits for a 30-minute idle window, and can run in the foreground or via --detach
• watch --account <name> creates a temporary codexm overlay so title generation runs against that managed auth snapshot without mutating your base CODEX_HOME
• Archived show / title rewrite fall back to local rollout files when app-server cannot read archived rollouts
• Title write-back uses Codex app-server thread APIs
• Managed-title ledger writes to ~/.codex/codext/managed_titles.jsonl
• Audit history writes to ~/.codex/codext/history.jsonl; codext log renders the same JSONL source in a human-readable view

Shell Completion

Generate a completion script and install it with your shell's standard mechanism:

mkdir -p ~/.zsh/completions
codext completion zsh > ~/.zsh/completions/_codext

mkdir -p ~/.local/share/bash-completion/completions
codext completion bash > ~/.local/share/bash-completion/completions/codext

Current completion covers static commands, subcommands, and flags. It does not dynamically resolve thread IDs.

TUI

Key bindings:

• Tab: switch Active / Archived
• j/k or arrow keys: move
• / or s: open search edit mode
• Enter: apply current search
• Esc: cancel search edit or confirmation/review state
• f: open the range filter picker
• Space: toggle current row selection
• a: select all visible rows in current tab
• Shift+A: clear current-tab selection
• e: archive or restore selected rows
• r: generate title suggestions for selected rows
• q: quit

Review screen:

• Space or x: toggle apply/skip for current suggestion
• a or Enter: apply selected suggestions
• c, q, or Esc: cancel review

List layout:

• Wide split view keeps the thread list on the left and details on the right
• Common wide terminals now keep Repo visible more often instead of hiding it behind the detail pane width split
• When there is enough room, the list shows Repo, Token, and Updated
• Token is shown as input/output with k, m, and b suffixes

Notes

• title set is a manual explicit rename and does not write to the managed-title ledger.
• title rewrite <thread-id...> is the fast manual path and can re-enter codext management for a thread after a manual title detour.
• archive / unarchive use app-server thread APIs; they are not direct SQLite or rollout edits.