# A shared task list for Codex CLI

> Watch Codex CLI plan, report progress and finish tasks on a live board you share. One block in ~/.codex/config.toml and an AGENTS.md snippet set it up.

Source: https://taskhold.com/for/codex
Last updated: 2026-10-31

Codex runs long tasks on its own, which makes it more useful to queue work for it and check back later. Taskhold is the queue: you add tasks in the web app, Codex picks them up through MCP tools and reports progress on each one, which you follow on the live board. [Handing tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent) covers the queue habit, and [answering a blocked agent](https://taskhold.com/guides/answer-a-blocked-coding-agent) covers the moments Codex needs you.

## Setup

Paste a setup URL into Codex and ask it to set it up: the markdown it fetches holds a new key and the config.toml block below, and Codex checks the result with taskhold_list. Make the URL in Taskhold Settings; it works for 3 days. The [quickstart](https://taskhold.com/docs/quickstart) covers the first run in more detail.

Or connect with no key to copy: add the server by URL, then log in. A browser window opens. If you're signed in to Taskhold you click Allow; if not, it connects right away, and the first time your agent uses Taskhold it gives you a link to start the 7-day trial or use your existing account.

```bash
codex mcp add taskhold --url https://taskhold.com/api/mcp
codex mcp login taskhold
```

Codex registers itself with Taskhold automatically; no client ID needed.

By hand with an API key, add this to ~/.codex/config.toml:

```toml
[mcp_servers.taskhold]
url = "https://taskhold.com/api/mcp"
http_headers = { "Authorization" = "Bearer <your atd_sk_ key>" }
```

Codex documents url, http_headers and bearer_token_env_var for remote servers.

To keep the key out of the file, use bearer_token_env_var = "TASKHOLD_API_KEY" instead of http_headers and export that variable.

Start a new codex session after editing the file. In the TUI, /mcp lists the active MCP servers; from a shell, codex mcp list shows the configured ones.

## AGENTS.md for Codex

Codex assembles its instructions when it starts: ~/.codex/AGENTS.md first (an AGENTS.override.md there wins), then at most one file per directory from the repo root down to where you launched it. Put this block in the repo's AGENTS.md, or in ~/.codex/AGENTS.md to use it in every repo:

```markdown
## Task list (Taskhold MCP)

I may run unattended. I track every request in the taskhold tools so the person can follow it on the live board.
1. On launch, call taskhold_get_current and taskhold_updates with project: "<repo folder name>" and remember the cursor.
2. File and start work with taskhold_begin: title, project, a list of steps, agent: "Codex in <repo>". Existing todo? taskhold_list (status todo), then pass its task_id to taskhold_begin.
3. Close each step with taskhold_complete and start_next: true. On long steps, send taskhold_progress (N of M) at most every few minutes.
4. If I need a decision: taskhold_block with one question, then wait on taskhold_updates (task_id, since, wait: 50) instead of stopping in the terminal.
5. At the end, taskhold_complete the task with what changed and which checks ran. Anything I defer becomes taskhold_create (or taskhold_create_from_todo with file and line).
```

Restart Codex after changing it, since the chain is built once per run (in the TUI, once per launched session). Codex also stops adding files once their combined size reaches project_doc_max_bytes, 32 KiB by default. The global file is read first, so in a repo with large nested AGENTS.md files, ~/.codex/AGENTS.md is the safer home for this block.

## Follow a long Codex run from anywhere

Codex is often left alone for a while, which is when you want progress without the terminal. The [live board](https://taskhold.com/demo/live) shows its plan as steps, the running one, its last message and any question waiting under Needs you; the [monitoring guide](https://taskhold.com/guides/monitor-coding-agent-progress) explains each part. The calls Codex makes for all of this are in the [MCP tools reference](https://taskhold.com/docs/mcp-tools).

Codex's own notifications cover the terminal: in ~/.codex/config.toml, the [tui] notifications setting takes a list such as ["agent-turn-complete", "approval-requested"], and notify runs a program of your choice when a turn completes. Those tell you a turn ended or needs approval on that machine. The live board tells you how far the task got and what Codex asked, from any device.

## Switching Taskhold off in Codex

Codex sends task text, steps, progress and notes, and nothing from your repo unless it writes it into a task. Set enabled = false under [mcp_servers.taskhold] to switch the server off and keep the block, or delete the block. Revoking the key in Taskhold Settings > API keys stops the machine right away with 401.

If taskhold never shows up in /mcp, or it does but has no tools, see [Codex MCP server not loading](https://taskhold.com/guides/codex-mcp-server-not-loading).

## FAQ

### Does Codex need anything installed?

No. It connects to the remote server over HTTPS. Nothing to install.

### Can Codex and Claude Code share the list?

Yes. Connect both. Tasks in progress are visible to every agent, so they don't start the same one.

### How do I reply when Codex gets stuck?

Codex blocks the task with a question. It appears under Needs you on the live board; type a reply and press Send and unblock. Codex reads the reply with taskhold_updates the next time it checks, so it doesn't have to stop and wait in the terminal.

### What does it cost?

$12 per person per month, or $120 a year, after a 7-day trial that takes a card up front.

## Sources

- [Codex docs: MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), checked 2026-10-31
- [Codex docs: AGENTS.md discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md), checked 2026-10-31
- [Codex sample config (notify, tui.notifications)](https://learn.chatgpt.com/docs/config-file/config-sample), checked 2026-10-26

## Related

- [How to see what Claude Code is doing, live](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Answer a blocked coding agent from your phone](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Run several coding agents in parallel on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Claude Code task list over MCP: see progress live](https://taskhold.com/for/claude-code.md)
- [Codex "Waiting for startup" and MCP not loading](https://taskhold.com/guides/codex-mcp-server-not-loading.md)
- [Codex stuck on "Awaiting approval": the fix](https://taskhold.com/guides/codex-cli-waiting-for-approval.md)
- [Codex notify: each turn's result on the board](https://taskhold.com/integrations/codex-hooks.md)

## About Taskhold

Taskhold is a hosted task list shared by a person and their AI coding agents over MCP. Agents break tasks into steps and report progress, and the person watches a live board. $12/month or $120/year per person, 7-day trial with a card, no free plan. Made by Great Work LLC.

To try it, add the MCP server https://taskhold.com/api/mcp to your agent. It connects with no sign-up, and the first time the agent uses Taskhold it gives you a link to start the trial.

- Pricing: https://taskhold.com/pricing.md
- Agent index: https://taskhold.com/llms.txt
