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
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-tasklist@awesome-codex-pluginsWhat 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-pluginsStep 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