Skip to main content
plugin CX Codex

codex-tasklist — Codex plugin: what it does, how to install

codex-tasklist is a plugin for Codex CLI that creates a live task panel, saves state to SQLite, and switches to tmux when native terminal panels are unavailable.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-tasklist@awesome-codex-plugins
Open on GitHub

What codex-tasklist does

The plugin tracks your conversation with Codex CLI and turns normal prompts into a persistent queue. Each session maintains its own task list that updates step statuses during execution and closes once the main process exits. Running version 2.0 requires Python 3.10+, using standard library modules without extra dependencies.

Session state writes to a temporary directory and checkpoints to PLUGIN_DATA/runtime.sqlite3 on lifecycle events. Native split panels are supported out of the box in WezTerm, kitty, iTerm2, and Ghostty on macOS. Other Linux and macOS setups rely on tmux via a dedicated launcher script.

A crash before a checkpoint write will lose uncommitted queue changes. If your system lacks native adapter support and tmux is not installed, the visual split cannot open, though CLI queue commands continue to work.

What it helps with

  • track task execution status in a live terminal split alongside Codex
  • restore active task queues after session restarts via SQLite checkpoints
  • run automated task panels across unsupported terminal emulators using tmux

Example prompts for the agent

  • Set up the codex-tasklist launcher
  • Show current session tasks and their status
  • Resume the previous session with codex-tasklist resume

How to install codex-tasklist

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-tasklist@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-tasklist

How to install codex-tasklist in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins followed by /plugin install codex-tasklist@awesome-codex-plugins. After installing, trust the hooks and restart the client.

What does codex-tasklist do?

It creates an active task list panel next to your Codex session. Tasks update from conversational context and persist to local SQLite storage.

What are the system requirements for codex-tasklist?

You need Python 3.10 or newer. For panels outside WezTerm, kitty, or iTerm2, install tmux on Linux or macOS.

Source text

codex-tasklist · MIT
# Codex Tasklist

A persistent per-session task queue for Codex CLI, with native terminal panels and automatic tmux setup. Version 2.0 requires Python 3.10+ and uses only the Python standard library.

Write requests normally: Codex creates tasks, matches follow-ups, and updates statuses. Each session keeps its own saved queue. The panel opens with a live Codex CLI session and closes when its owner exits. Queue commands remain available if the panel cannot open.

Version 2.0.3 restores panels under the shared Codex app-server daemon (0.155+), where hooks no longer run inside the interactive CLI: the session is bound to its `codex` process and the pane is matched by controlling tty. It also fixes sandbox write failures. Hooks supply a private temporary working directory shared by the CLI and panel, and checkpoint it to `PLUGIN_DATA/runtime.sqlite3` after tools and lifecycle events. Existing queues are imported; the last checkpoint restores tasks after temporary-file cleanup. A machine failure before checkpointing can lose the latest changes. Use the hook's exact `--data-dir`; reinstall, trust the updated hooks and restart Codex after upgrading.

WezTerm, kitty, iTerm2 and supported Ghostty macOS scripting APIs have native adapters. Other Linux/macOS terminals, including VS Code, use tmux. Windows Terminal uses WSL for panels; native PowerShell/cmd keeps queue commands. Real Codex integration has been tested with WezTerm on Linux/Windows, kitty on Linux and Konsole through tmux. Native macOS adapters still need live platform verification.

On native Windows, run **`codex`** or **`codex resume`** directly. The plugin opens WezTerm panels automatically and keeps queue commands available in other terminals. No launcher or shell-policy changes are needed.

On Linux/macOS/WSL, ask Codex to **set up the codex-tasklist launcher**, then run `codex-tasklist` instead of `codex`. Arguments are forwarded, including `codex-tasklist resume`. The launcher uses a native panel when available or configures a private tmux session automatically. No tmux knowledge is required. If tmux is missing, install it once with your package manager; Codex can still run without a panel.

Manual setup: run `python3 PATH/TO/scripts/tasklist.py --data-dir YOUR_PLUGIN_DATA install-launcher` (Linux/macOS/WSL). Add the printed directory to PATH if needed. Re-run setup after upgrades. The launcher does not install dependencies or edit shell profiles. To skip command installation, use `python3 PATH/TO/scripts/tasklist.py start -- resume`.

Native requirements: kitty needs a permitted local Unix remote-control socket and `splits` layout; macOS adapters need Automation permission. Ghostty must expose terminal TTYs in its AppleScript API. A denied or unavailable API falls back through the launcher. iTerm2 AppleScript is deprecated upstream; tmux remains the fallback. An already running Codex cannot be moved into tmux automatically.

See the [installation guide, demo and controls](https://github.com/martinille/codex-tasklist#readme). Review and trust hooks before use. See [SECURITY.md](SECURITY.md) for vulnerability reporting and [LICENSE](LICENSE) for the MIT license.

© Martin Ille · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Notes, tasks and projects →

From the same set391

The whole set →
codex-attachment-manager codex-attachment-manager is a Claude Code plugin that manages image history in Codex tasks. It selects attachments for the next message and searches them by description. CX Codex ★ 1,596repo stars codex-claude-council codex-claude-council asks Claude and ChatGPT the same question, then lets them debate across multiple rounds until both reach agreement. CX Codex ★ 1,596repo stars codex-usage-and-resets codex-usage-and-resets is a Claude Code plugin that reports Codex weekly usage, pace, and reset expirations. It estimates whether the allowance will last until the next reset. CX Codex ★ 1,596repo stars codex-tui-proof codex-tui-proof is a Claude Code plugin for checking terminal UIs in Codex's browser with keyboard input and screenshots. It runs from a TUI validation request. CX Codex ★ 1,596repo stars codex-skin-pack-installer The codex-skin-pack-installer plugin stages and checks public-safe Codex skin packs from GitHub releases. Use it when a custom background, artwork, and a visible restore path matter. CX Codex ★ 1,596repo stars codex-rg-guard codex-rg-guard is a Claude Code plugin that narrows broad repository searches through a budgeted MCP tool. It selects files before returning bounded line matches. CX Codex ★ 1,596repo stars codex-reviewer codex-reviewer runs a secondary audit over AI-authored plans and pull requests. Catches architectural blind spots and unverified code before merge. CX Codex ★ 1,596repo stars codex-quota-title codex-quota-title shows remaining Codex quota and reset time in the Codex Desktop window title on Windows. The original title stays visible. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open