TaskWake

Background task execution, completion detection, and session wake-up for local AI harnesses.

TaskWake runs background commands for local AI harnesses, detects their completion, and wakes the harness session so results are delivered back without a second manual prompt. Tasks run in detached process groups; results are delivered through OpenCode promptAsync, Codex/Claude resume, or an explicit result file.

It is a Unix-first local bridge layer: Linux and macOS are supported; native Windows support is not yet available. bgexec executes sh -c with the current user's privileges — TaskWake is not a sandbox.

Features

• bgexec: run commands in the background with timeout and log/file/port sentinels
• wait_task, task_list, task_status, task_cancel, task_log: query, cancel, and read logs; task_status reports three-dimensional diagnostics (execution / binding / delivery)
• Durable task state (v2 three-dimensional schema with backups and quarantine), restart recovery, log quotas, and process-group termination
• In-process wake-up for OpenCode; Codex and Claude Code wake via helper + MCP + resume
• Exact project/session routing; fails closed and writes a .result file when the target session cannot be confirmed

Supported harnesses

Harness	Wake mechanism	Status
OpenCode	In-process promptAsync adapter	Supported
Codex	command hooks + MCP server + codex exec resume	Supported (requires /hooks trust review)
Claude Code	command hooks + MCP server + resume	Supported (requires manual install verification)

Install

Requirements: Bun 1.2+.

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build

After building, install a B-class integration using the absolute path of this checkout (replace the example paths below):

bun /absolute/path/taskwave/packages/helper/dist/cli.js install \
  --harness codex \
  --project /absolute/path/to/project \
  --mcp-path /absolute/path/taskwave/packages/mcp-server/dist/index.js

bun /absolute/path/taskwave/packages/helper/dist/cli.js doctor --json

doctor --json emits machine-readable diagnostics (helper/lockfile, state schema version, wake channel, per-harness install and hook trust status). Hook trust can only be reported as manual-check statically; verify it manually with /hooks.

Codex hooks

User-level Codex command hooks are not trusted automatically. After installing, run /hooks in Codex, review, and trust TaskWake's PostToolUse and Stop hooks; re-review whenever the hook definitions change. The installer also sets the TaskWake MCP server's default tool approval mode to prompt, because bgexec can execute arbitrary shell commands.

Claude Code

Claude Code installation modifies the project's .claude/settings.json, .mcp.json, and CLAUDE.md:

bun /absolute/path/taskwave/packages/helper/dist/cli.js install \
  --harness claude-code \
  --project /absolute/path/to/project \
  --mcp-path /absolute/path/taskwave/packages/mcp-server/dist/index.js

The installer refuses to overwrite corrupted JSON or an existing unmanaged [mcp_servers.taskwake] entry; resolve such conflicts manually first.

Usage

Once installed, the harness exposes these MCP tools:

Tool	Description
bgexec	Run a shell command in the background; optional timeout and sentinels
wait_task	Block until a task reaches a terminal state
task_list	List recent tasks with truncated output tails
task_status	Three-dimensional diagnostics (execution/binding/delivery)
task_cancel	Cancel a running task (TERM/KILL escalation by process group)
task_log	Read the task's log tail

For local inspection and management, the helper CLI provides taskwake list/status/log/cancel, and taskwake doctor --json reports installation health.

Security

TaskWake runs commands with the privileges of the calling user and is not a sandbox. Working directories are restricted to the project directory unless allowExternalCwd: true is set explicitly. Tasks that lack an exact session binding fail closed instead of guessing a session.

See the Security Model section of the contributing guide for the full security model and reporting guidelines.

Documentation

Document	Description
docs/CHANGELOG.md	Release history
docs/CONTRIBUTING.md	Contributing guide, code of conduct, and security model

Development

CI runs typecheck, build, and tests on Linux and macOS. Tests that touch Unix sockets, detached child processes, or process-group signals require the corresponding system capabilities.

bun run typecheck
bun run test      # builds first, then runs all workspace tests
sh scripts/package-smoke.sh   # pack + install + MCP end-to-end smoke

Contributing

Contributions are welcome. Please read CONTRIBUTING.md — it covers the fork-and-PR workflow, the local gates, and the repository's commit message convention (English, imperative mood, prefixed with the area or milestone changed).

License

MIT — see LICENSE.