TaskDock

Human-first personal tasks with attachable Codex and OpenCode sessions.

TaskDock is a local-first Todo workbench built around one opinion: the task belongs to the person, not to an Agent session.

Agent-native task systems often make the Agent or conversation the unit of work. That becomes awkward when context grows, a task needs several independent attempts, or the human continues the work from another client. TaskDock reverses that relationship:

• A person creates and owns the Todo.
• A Todo can attach multiple independent Agent sessions.
• Sessions describe execution state; they do not decide whether the Todo is complete.
• The person remains the final authority over task status and completion.

The model

Human-owned Todo
├── Codex session · implementation · running
├── Codex session · review · result waiting
└── OpenCode session · research · idle/resumable

The Todo is durable. Sessions are attachable work contexts: they can be started elsewhere, resumed independently, replaced, reviewed, or archived without taking ownership of the task lifecycle.

TaskDock intentionally excludes Codex Subagents and OpenCode child sessions from its dashboard. The user interacts with the root Session; implementation branches remain internal details of that root context.

Features

• List and Kanban views backed by a user-defined human Todo workflow
• Rename, reorder, add, and remove Todo columns; choose defaults for ordinary, Session-created, and completed Todos
• Archive, restore, and explicitly confirmed permanent deletion
• Automatic local discovery of root Codex and OpenCode sessions
• One Todo to many Sessions, with roles such as implementation, research, review, testing, and debugging
• Agent Dashboard for running, result-waiting, idle, unbound, and archived Sessions
• Origin-aware opening: active CLI Sessions return to the terminal, inactive CLI Sessions open with resume, and Desktop-origin Sessions keep their deep link
• Send a next-turn instruction to an idle Codex or OpenCode Session from TaskDock; commands for the same Session are serialized
• Lifecycle-backed states: running, completed with a result waiting, and completed with no result waiting
• A local MCP server so Codex can collect, organize, update, and summarize Todos directly
• Optional Codex lifecycle Hooks for near-real-time state
• Optional private Feishu bot for mobile Todo and Session access
• Feishu completion notifications with a short final-answer preview, paginated result reading, on-demand resume commands, and Todo binding

Product boundaries

Task state and Agent state are deliberately separate:

Todo state	Agent Session state
User-defined; defaults to Inbox / Todo / Doing / Done	Running / Result waiting / Idle / Archived
Chosen by the person	Observed from the local Agent runtime
A Session ending never completes it	Can be resumed independently

Running takes precedence over read state. A Todo with several Sessions may have one Session running while another already has a result waiting.

TaskDock does not inject a second command into an Agent that is already running. Open the live CLI Session instead, or send the next turn after it becomes idle. Codex messages use codex exec resume; OpenCode messages use opencode run --session. Returned output is collapsed by default in the desktop UI.

The default Todo workflow intentionally has no “Review” or “Acceptance” column. An Agent finishing work is represented by the attached Session's result-waiting signal; it never moves the human-owned Todo. If a person genuinely uses review as part of their own process, they can add and name that column themselves.

Architecture

Codex Hooks + local state ─┐
                          ├─ Session scanner ─┐
OpenCode local database ──┘                   │
                                              ├─ local SQLite ─ Desktop UI
Codex MCP ────────────────────────────────────┤
                                              └─ Feishu private-bot bridge

The desktop app, MCP server, lifecycle Hooks, and Feishu bridge share the same local TaskDock database. There is no required cloud data layer.

Requirements

• macOS (the current packaged desktop target is Apple silicon)
• Node.js 22 or newer
• npm
• Codex and/or OpenCode installed locally
• Optional: lark-cli plus a private Feishu app

Development

npm ci
npm run typecheck
npm test
npm run dev

Build the macOS app:

npm run package:mac
open release/mac-arm64/TaskDock.app

Local data is stored at ~/.taskdock/taskdock.sqlite by default. Set TASKDOCK_DB_PATH to override it.

Codex lifecycle Hooks

npm run install:hooks

The installer merges TaskDock's SessionStart, UserPromptSubmit, Stop, and SessionEnd handlers with existing Codex Hooks instead of replacing them. After the first install or a Hook change, start Codex CLI and use /hooks inside the Codex interactive UI to inspect and trust the handlers.

Codex MCP

Build and register the local MCP server:

npm run build:mcp
codex mcp add taskdock -- node /absolute/path/to/TaskDock/dist-mcp/mcp/index.js

New Codex Sessions can then use tools such as taskdock_dashboard, taskdock_get_workflow, taskdock_list_todos, taskdock_create_todo, taskdock_update_todo, and taskdock_list_sessions. Workflow changes are also available through taskdock_update_workflow, but should only be made when the user explicitly asks.

The MCP interface follows the same ownership rule as the UI: Codex may recommend that work is ready, but it does not mark a Todo done unless the person explicitly asks.

Feishu private bot

The Feishu bridge is an optional mobile interface. It accepts only private messages from the configured owner open ID and ignores other users, group chats, and bot messages.

npm run feishu:configure -- \
  --owner-open-id ou_xxx \
  --lark-cli-path /absolute/path/to/lark-cli \
  --lark-profile taskdock
npm run feishu:doctor
npm run feishu:test-card
npm run feishu:install

Required Feishu configuration:

• Event: im.message.receive_v1
• Callback: card.action.trigger
• Bot scopes: im:message.p2p_msg:readonly, im:message:readonly, im:message:send_as_bot

Private-chat commands:

• 任务 — Todo overview
• 结果 or Sessions — Agent Session activity
• 任务 <keyword> — find and operate a Todo
• 新增 <title> — create an Inbox Todo

Completion notifications show at most a short preview. Full final answers are read on demand and paginated; resume commands are revealed only when requested. Obvious API keys, access tokens, and local usernames are redacted before result text is sent to Feishu. Receiving or opening a card does not silently change Codex Desktop's read state.

Feishu credentials, owner IDs, local databases, generated QR codes, logs, and packaged builds must remain outside version control.

Current limitations

• The packaged app is currently macOS arm64 only.
• Local Codex/OpenCode database schemas are integration boundaries and may need adaptation when upstream clients change.
• The macOS development build is ad-hoc signed rather than notarized for distribution.
• Feishu mobile access requires the Mac-side bridge to be running.
• No cloud synchronization is included.
• TaskDock can detect which live Codex process owns a Session and activate its terminal app. Exact navigation to a particular Herdr-managed pane requires a future first-class Herdr integration; TaskDock does not forge Herdr caller context.