CodexToDoTree

Recursive task trees for Codex. Live progress in a browser, not a wall of chat updates.

中文文档 · Complete workflow rules · Workflow coverage · Security

A local-first MCP server, a live dashboard, and a reusable agent workflow. Plan major phases, break them into nested steps, adapt the plan as work evolves, and keep each conversation's progress separate.

What You Get

• Recursive trees: up to 32 levels and 1,000 stages per work item, with expand/collapse, keyboard navigation, search, current execution path and smooth progress updates.

• Multiple conversations and work items, isolated by exact conversation ID. In-progress items stay first; completed work collapses by default.

• Honest acceptance gates: completed children do not silently complete their parent. Parents need their own verification evidence.

• One local service for many browser tabs. Live SSE updates, atomic persistence, reconnection and automatic idle shutdown.

• Optional, read-only native Codex project/archive sync. No message scraping, telemetry, API key or external CDN.

• Existing mcp-tasks Markdown/JSON can be watched without maintaining two independent plans.

This is an independent community project, not an official OpenAI product. The dashboard currently uses Chinese UI labels; task content can use any language. MCP works in compatible local clients. A Codex sidebar needs that client's browser-opening tool; the MCP cannot inject native UI.

Related MCP server: Sequential MCP Server

Quick Start

Prerequisites: Node.js 22.13+ (24 LTS recommended) and a local Codex/MCP client. No administrator access required. Git is optional if you download the repository ZIP instead.

git clone https://github.com/weipeng-droid/CodexToDoTree.git
cd CodexToDoTree
npm ci
npm run setup -- --apply --codex-metadata
npm run doctor

1. setup --apply installs both the MCP configuration and the complete global AGENTS.md workflow in your Codex home (CODEX_HOME, otherwise the default Codex profile). It preserves unrelated text/settings, creates local backups, and ensures sufficient instruction capacity. npm run setup without --apply is preview-only; preview is not installation.

2. --codex-metadata explicitly opts into read-only native project/archive sync, matching the full local workflow. Omit it if you do not want native metadata reads; task-label grouping still works, but native archive synchronization does not. The option stays enabled on subsequent upgrades; use setup --apply --no-codex-metadata to deliberately disable it without editing a protected block.

3. Require a passing doctor, then restart/reload the MCP client and begin a new Codex run. Run codex mcp list and look for codex_todo_tree. Doctor proves installation consistency, not model obedience or UI capability.

4. Start a new conversation and ask:

Use CodexToDoTree for this task. Read the real CODEX_THREAD_ID, create 4-8 main phases with nested substeps, open this conversation's task dashboard, and keep it updated until verification is complete.

The agent calls console_plan, console_open and console_update. If Codex exposes its browser panel tool, the workflow opens the page on the right. Otherwise open the returned URL in your normal browser. A fresh URL alone shows an empty conversation until a plan is registered.

The installed workflow delegates substantial implementation, assigns each parent only its direct children, requires independent review, and hands acceptance upward. A parent never self-accepts its delegated node. Implementation/review/acceptance are serial because the current model permits one executing leaf per board. See the complete protocol and Chinese handoff handbook. MCP initialization also supplies the same rule source, but does not silently install global files.

To inspect instructions without installing, use npm run setup -- --instructions. For a custom profile use node bin/cli.mjs setup --apply --codex-home /absolute/profile --codex-metadata, then node bin/cli.mjs doctor --codex-home /absolute/profile. These same commands work from an installed package with the codex-todo-tree binary. This repository provides source installation; it is not a claim the package has been published to the npm registry.

Codex's standard MCP configuration is documented in the official MCP guide. This project does not require an OpenAI API key.

Enable Native Project and Archive Sync

npm run setup -- --apply --codex-metadata
npm run doctor

The installer updates its existing managed configuration instead of adding a duplicate server. It sets CODEX_TODO_TREE_CODEX_METADATA="1". The service reads only registered conversations' ID, archive flag, title and project mapping from local Codex metadata every 3 seconds. Archived chats disappear; unarchiving restores the same tasks. Nothing is written to Codex's database. Read failures retain the last valid view and show a warning. Doctor reports this option's configuration, not proof that a particular native database version is supported.

This is an opt-in, version-dependent adapter, not an official stable API. Without it, task-supplied project labels provide grouping and native archives are not synchronized. Changing the option requires stopping this tool's existing service and reopening it; changing only the MCP process environment cannot reconfigure an already running shared service.

CLI Without MCP

From this repository, use a real thread ID from your host. The following PowerShell example runs inside Codex:

node bin/cli.mjs url --thread "$env:CODEX_THREAD_ID"
node bin/cli.mjs plan --board release --thread-title "Release" --title "Ship a release" --project "Example App" --steps "Inspect|Implement|Test|Deliver"
node bin/cli.mjs update --board release --step step-1 --status in_progress
node bin/cli.mjs update --board release --step step-1 --status done --evidence "Actual command and result, exit code 0"
node bin/cli.mjs add --board release --step api --parent step-2 --title "Implement the API"
node bin/cli.mjs list

In Bash, use --thread "$CODEX_THREAD_ID". Outside Codex, pass your own explicit integration's --thread consistently; do not reuse another chat's ID. Evidence in examples is a placeholder, not a real test claim. Use plan --file nested-plan.json for nested JSON stages. See the command reference.

How Progress Works

Project
  Conversation (exact thread ID)
    Work item (stable board ID)
      Main phase
        Subphase
          Executing leaf

Only one leaf per work item is explicitly in progress. Ancestors roll up automatically. Children done + parent not yet accepted = awaiting verification. Editing accepted children invalidates ancestor acceptance. Skipping needs a reason and preserves history. A new goal gets a new work item; debugging the same goal stays in its existing tree.

Work-item order: in progress, blocked, awaiting verification, todo, done, skipped. Within each group the latest update comes first. Progress measures accepted main phases, not estimated time remaining.

Privacy and Lifetime

Data stays in a per-user application-data directory, outside your clone/npm install. Windows uses the local application-data folder, macOS Application Support, and Linux XDG data home (or its standard fallback). CODEX_TODO_TREE_STATE overrides this for a deliberate whole-installation choice; do not set it separately per conversation. The older TASK_CONSOLE_STATE remains an alias.

The service binds only to 127.0.0.1, preferably port 47831, falling back if occupied. CLI/MCP writes require a local client key; the webpage is read-only. This is not a multi-user authorization boundary: another local program/user with access to the state directory can read it. Do not store secrets in task content.

An open live dashboard keeps the service alive. After the last page disconnects and no task read/write occurs for 60 seconds, the listener, timers, metadata worker and lock are released. Saved tasks remain. The next CLI/MCP call restarts the service. Do not stop it just because one conversation finishes.

No automatic startup hook runs merely because you click a historical chat. Auto-open is an agent action governed by the installed workflow rules. Cloud/remote executor localhost may not be reachable from your browser; use a same-machine local setup. Do not expose this unauthenticated read interface publicly.

Development

npm ci
npm run check
npm test
npm run demo

demo uses synthetic data in an isolated ignored work/ directory, never your real tasks. Stop it with Ctrl+C, or close all viewers and let it idle out. Tests exercise real stdio MCP, CLI, HTTP/SSE, tree acceptance, persistence, archive restoration and shutdown. CI covers Windows, macOS and Linux with Node 22/24; a configured CI matrix is not a claim all remote runs already passed.

The frontend is plain HTML/CSS/JavaScript, with no build step. Asset snapshots use one startup fingerprint; after code changes, run node bin/cli.mjs stop, reopen with url, and refresh once. Other open pages reconnect.

Uninstall

Remove only the section between # CodexToDoTree BEGIN/END in config.toml, and between <!-- CodexToDoTree BEGIN/END --> in global AGENTS.md. Leave unrelated settings/rules and instruction capacity intact. Reload the client. Use node bin/cli.mjs stop only when other conversations no longer need the service. Removing source does not delete saved history; delete that separately only after backing it up.

Upgrade and Recovery

• Update source, run npm ci, npm run setup -- --apply and npm run doctor, then reload. The installer replaces its one managed block, preserves a larger existing capacity and retained metadata opt-in, and does not duplicate rules. Stop/reopen the old shared broker once after changing code; do not stop it at ordinary task completion.

• Upgrading a manually configured 0.1 installation: first back up the profile. Remove only its old codex_todo_tree server/env section and the workflow text you manually added, preserving other content, then apply setup. An enabled legacy task_console must be deliberately migrated/disabled first. The installer refuses unmanaged conflicts rather than silently overwriting them or adding a second service.

• Nonempty AGENTS.override.md, invalid TOML, edited managed rules/settings, symlinks, malformed markers or an active setup lock cause explicit failure. Both managed blocks have integrity hashes; custom fields/env inside the managed MCP block are not silently discarded. Preserve them and deliberately migrate before setup. Resolve the specific conflict; do not delete all settings/state. Projects can also override guidance and must be inspected separately.

• Explicit [agents] enabled=false or a zero subagent limit makes doctor fail the complete-workflow check without changing that preference. Static checks report browser/subagent host capability as unverified; unavailable tools require honest degradation, not invented review/open results.

• Backups named AGENTS.md.codex-todo-tree-*.bak and config.toml.codex-todo-tree-*.bak stay in the user's profile. They may contain secrets: never upload them. Compare current edits before manually restoring a backup. Unrelated preferences added after backup must be preserved.

• Setup validates both proposed files before writing, uses a profile lock and snapshot checks, and attempts safe rollback on ordinary write failure. The lock coordinates this installer, not every editor; this is not an operating-system CAS or a power-loss-atomic two-file transaction. An interrupted process can leave its lock/partial managed installation. Confirm it stopped, inspect backups/current files, then recover and rerun doctor; never blindly remove another process's lock.

No MCP can guarantee identical behavior for every client, model, remote executor or policy. Missing subagent/browser capabilities must be reported, not fabricated. Hierarchical ownership is a workflow contract, not actor ACL enforcement; evidence strings do not prove commands ran. Persistent rules, runtime guidance, actual tests and independent review are complementary gates.

License

MIT. See LICENSE. Lucide icons are ISC-licensed and the MCP SDK is MIT-licensed; their packages retain their own notices. See THIRD_PARTY_NOTICES.md.