Threadbox for Codex

A local, cross-platform manager for Codex tasks on desktops, terminals, and remote servers.

简体中文

Threadbox brings Codex task history from every working directory into one searchable list. The Electron app, headless CLI, and VS Code extension share the same official Codex App Server integration. The desktop app also provides separately confirmed adapters for moving selected task directories to Trash and repairing Codex desktop's derived Recents catalog.

Threadbox for Codex is an independent community project. It is not affiliated with or endorsed by OpenAI.

Features

• List active and archived tasks across all working directories.
• Search titles, previews, paths, sources, and task IDs.
• Group desktop chats by Project, VS Code and CLI chats by working directory, and projectless desktop chats as independent tasks.
• Organize VS Code and remote-host tasks inside the Codex sidebar, including drag-and-drop and multi-select actions.
• Switch between grouped and flat views, and filter by project/workspace, archive state, source, directory, or recent activity.
• Archive, unarchive, and permanently delete one or many tasks.
• Optionally move selected working directories to the system Trash while keeping other project files.
• Group spawned sub-agent tasks under collapsible parent rows and avoid duplicate cascade deletion requests.
• Protect running tasks and require an explicit irreversible-deletion acknowledgement.
• Warn when other Codex processes may make cross-process running status incomplete.
• Detect and repair Codex desktop Recents entries whose underlying tasks have already been deleted.
• Open the original working directory or copy a task ID.
• English and Simplified Chinese interface with system light/dark themes.

Everything runs locally. Threadbox has no telemetry, does not call a model, and does not upload or retain conversation content.

Choose a frontend

Capability	Desktop	CLI	VS Code / Remote
List, search, group, archive, pin, and delete task records	Yes	Yes	Yes
Manage the host used by Remote SSH, Dev Containers, or Codespaces	No	Yes	Yes
Create host-local task projects	No	No	Yes
Open a task working directory	Yes	No	Yes
Move selected working directories to system Trash	Yes	No	No
Repair Codex desktop's derived Recents catalog	Yes	No	No

The CLI and VS Code extension always preserve working directories. Unsupported actions are absent from their interfaces rather than exposed as hidden flags.

Requirements

• Codex CLI 0.149.0 or newer available on PATH.
• Desktop: Windows 10/11, macOS, or a modern Linux desktop.
• CLI: Node.js 22.13.0 or newer.
• Extension: VS Code 1.96.0 or newer. Remote sessions require Codex on the remote extension host.

Platform validation

Platform	Current validation
Windows 10/11 x64	Automated tests, packaged-app smoke tests, and manual use
macOS x64/arm64	Automated tests and unsigned package builds in GitHub Actions; physical-device testing is still needed
Linux x64	Automated tests and unsigned package builds in GitHub Actions; physical-device testing is still needed

Install or update Codex CLI:

npm install -g @openai/codex@latest

You can also select a custom Codex executable in Threadbox settings or set CODEX_BINARY.

Desktop install

Download the package for your platform from GitHub Releases.

• Windows: run the NSIS installer or unpack the ZIP build. Unsigned builds may trigger SmartScreen; inspect the publisher and release checksum before choosing More info > Run anyway.
• macOS: open the DMG or ZIP build. Unsigned builds may require right-clicking the app and choosing Open, or approving it in System Settings > Privacy & Security.
• Linux: install the DEB package or mark the AppImage executable and launch it.

Every release includes SHA256SUMS.txt.

CLI install

Run without installing:

npx codex-threadbox

Or install globally:

npm install -g codex-threadbox
threadbox

Running threadbox in a TTY opens the interactive manager. Scriptable commands are status, list, archive, unarchive, pin, unpin, and delete. list hides spawned internal tasks by default; pass --include-spawned to include them. Mutations accept only explicit task IDs. Use delete --dry-run ID... to inspect root tasks, spawned descendants, and protected items without making changes. Non-interactive deletion requires --yes; use --json for the stable schemaVersion: 1 output contract.

VS Code install

Install Threadbox for Codex from the VS Code Marketplace, Open VSX, or the release VSIX. Open the official Codex sidebar and expand Threadbox to search tasks and organize them with multi-select, drag-and-drop, or Move to Project; the move picker can create a project without leaving the workflow. Set threadbox.sidebarLocation to standalone for the original Activity Bar container. Threadbox also falls back there when a compatible Codex sidebar is unavailable. Run Threadbox: Open Manager for the full table and advanced filters.

The extension declares extensionKind: ["workspace"]. In Remote SSH, Dev Containers, and Codespaces, Codex CLI, CODEX_HOME, task data, and the App Server process all remain on the remote host. Configure threadbox.codexBinary, threadbox.codexHome, or threadbox.language as machine-scoped settings when needed. An untrusted workspace cannot start Codex or modify task metadata.

Threadbox project names and root-task assignments are stored in that extension host's VS Code global storage. They do not modify Codex databases or official project assignments and do not automatically sync between remote hosts.

Safety model

Permanent deletion calls App Server thread/delete, which also deletes spawned descendants. Threadbox refreshes the inventory immediately before deletion, removes active or pinned tasks from the request, collapses selected descendants under selected parents, and executes root deletions sequentially so one failure does not stop the rest.

Project files are kept by default. The deletion dialog lists the exact task cwd values shown in the table, not project/workspace group names. Only checked directories are moved to the operating system Trash, and only after the corresponding task deletion succeeds. Threadbox keeps filesystem roots, the user home and Codex data directories, system locations, its own application paths, and directories still referenced by remaining Codex tasks. Trash failures never trigger permanent filesystem deletion.

The CLI and VS Code extension do not contain the Trash or Recents adapters. Their permanent-delete operation removes Codex task records and spawned descendants through App Server while preserving every working directory.

Codex 0.149.0 does not yet expose pin metadata in its stable App Server schema. Threadbox keeps pin controls capability-gated and enables them only when the installed stable CLI advertises the required API. It never works around a missing task API by modifying Codex task state files.

Runtime status belongs to an App Server process, so a separate Threadbox process cannot guarantee that it sees work running inside another Codex desktop or IDE process. Threadbox displays a warning whenever other Codex processes are detected.

Codex desktop also keeps a separate derived local_thread_catalog for its Recents sidebar. Cross-process App Server deletion can leave orphaned rows in that catalog even though the task and rollout are gone. Threadbox compares the catalog with a freshly paged App Server inventory and offers a separate confirmation before removing only orphaned local-host rows. Before changing the catalog it creates a timestamped SQLite online backup under ~/.codex/backups_threadbox/desktop-recents and verifies the backup with PRAGMA integrity_check. It does not alter cloud-host rows, task state databases, rollout files, or working directories during this repair.

Development

Prerequisites: Node.js 22+ (Node.js 24 is used in CI) and npm.

npm install
npm run dev

Validation commands:

npm run lint
npm run typecheck
npm test
npm run test:cli
npm run test:vscode
npm run test:integration
npm run test:e2e
npm run package

Integration tests create isolated temporary CODEX_HOME directories. Unit, CLI, VS Code, and Electron tests use fake App Servers where mutations are exercised. Tests never mutate real Codex tasks.

Regenerate protocol types from the pinned Codex development dependency:

npm run protocol:generate

See Architecture and Contributing for project details.

Scope

Threadbox intentionally excludes full transcript viewing/export, task-database repair, automatic CLI upgrades, and a bundled Codex CLI. Recents repair is limited to the disposable desktop sidebar catalog described above.

License

MIT