Task Desk

Task Desk is a local-first Electron control desk for agent-created work. Local agents use the structured taskctl CLI to propose and manage tasks; a human reviews the exact task and prompt before anything is executed through Orca.

Task Desk currently targets macOS and stores its state locally. It does not provide cloud synchronization or a hosted task service.

Highlights

• Task board and list views with task details, provenance, activity history, and execution attempts.
• Human-gated task execution through Orca-managed OMP, Codex, or Claude sessions.
• Immutable execution snapshots so later task edits cannot change an approved run.
• Local SQLite persistence with migrations, transactions, optimistic concurrency, and append-only task events.
• taskctl CLI over a local Unix socket for agent-safe task operations.
• Agent records and task assignment, including configurable default assignees.
• User-authored cron automations for prompt sessions or bounded script-plus-prompt workflows.
• Light, dark, and system appearance modes.

How it works

 taskctl CLI ── local RPC ──> Electron main process ──> SQLite
                                      │
                                      └───────────────> Orca

 React renderer ── typed preload bridge ──> Electron main process

The renderer has no direct filesystem, database, process, or raw IPC access. The Electron main process owns the database and validates requests from both the renderer and the CLI.

Requirements

• macOS for the initial desktop target.
• Node.js 22.13 or newer, which provides the built-in node:sqlite API without an experimental flag.
• npm.
• Orca 1.4.183 or newer for task execution and Orca integration.

The core task and UI flows can be developed and tested without a live Orca session.

Quick start

Install dependencies and launch the desktop app:

npm ci
npm start

npm start builds the main and renderer bundles before opening Electron. For an explicit development launch, use:

npm run dev

To run the background runtime without opening a window:

npm run serve

The CLI starts the headless runtime automatically when no Task Desk runtime is available and Electron is installed locally.

CLI

After building, run the CLI through the npm script:

npm run build
npm run cli -- status --json
npm run cli -- agent list --json

The examples below use taskctl; replace it with npm run cli -- when working directly from this checkout.

Create a task:

taskctl task create \
  --title "Investigate scheduler regression" \
  --workspace /path/to/project \
  --body-file task.md \
  --prompt-file prompt.md \
  --agent omp \
  --assignee commander \
  --isolation worktree \
  --request-run \
  --json

List, inspect, and update tasks:

taskctl task list --status inbox,ready --workspace /path/to/project --json
taskctl task get TSK-42 --json
taskctl task update TSK-42 --assignee alex --title "Updated title" --if-version 3 --json
taskctl task set-status TSK-42 --status ready --if-version 3 --json
taskctl task comment TSK-42 --body "Reproduced locally." --json

Request execution and inspect execution attempts:

taskctl task request-run TSK-42 \
  --agent omp \
  --isolation existing \
  --json

taskctl execution list --task TSK-42 --json
taskctl execution get <execution-id> --json

CLI responses use a JSON envelope:

{"ok":true,"result":{}}

Errors use the same envelope shape with ok: false and a structured error object. Requesting a run does not approve or launch it; a human must review and approve the pending execution in the desktop app.

Human approval and execution

When a task has a pending run, the desktop app shows the exact prompt, workspace, requested agent, isolation mode, setup policy, and Orca behavior that will be used. Approval creates an immutable execution snapshot and requires an explicit confirmation action.

Supported launch profiles are allowlisted (omp, codex, and claude). Task Desk invokes Orca with explicit argument arrays rather than shell interpolation. Uncertain launch results are reconciled before a retry, preventing blind duplicate sessions.

Automations

Automations are explicit, user-authored schedules managed in the desktop app. They support:

• Five-field cron schedules.
• Prompt-only or script-plus-prompt workflows.
• An existing workspace and bounded command timeout.
• Agent selection and optional model configuration.
• Durable run status, stdout, stderr, prompt input, and prompt output logs.

Task content cannot create, edit, enable, or trigger an automation. A script can set TASK_DESK_NO_PROMPT=1 to record its result without launching a follow-up prompt.

Local data and runtime files

On macOS, Task Desk stores its local runtime under:

~/Library/Application Support/Task Desk/

Important files include:

• task-desk.sqlite — SQLite database containing tasks, agents, settings, executions, events, automations, and run logs.
• control.sock — taskctl control socket.
• runtime.json — active runtime descriptor.

Set TASK_DESK_RUNTIME_DIR to use another runtime and database directory, which is useful for isolated development or tests.

Development commands

npm run build       # Build main and renderer bundles
npm run build:main  # Build Electron main, preload, and CLI TypeScript
npm run build:renderer
npm run typecheck   # Typecheck main and renderer projects
npm test            # Run the Vitest suite
npm run test:watch

Project layout

cli/                 taskctl argument parsing and local RPC client
src/main/             Electron main process, domain services, SQLite, RPC, Orca
src/preload/          Narrow typed renderer bridge
src/renderer/         React desktop interface and styles
src/shared/           Shared schemas, types, and method allowlists
tests/                Domain, database, RPC, renderer, and integration coverage
spec.md               Product specification and verification plan

Security boundaries

• Task and prompt content is treated as untrusted text; it does not authorize application actions or execute HTML/JavaScript.
• Human-only approval and launch methods are exposed through the Electron preload surface, not the agent-facing CLI.
• Agent commands are selected from an allowlist; tasks cannot supply executables or arbitrary command lines.
• Orca launches use explicit argument arrays and retain the returned worktree and terminal identifiers.
• Activity records are append-only, and execution snapshots preserve the values reviewed by the human.
• Renderer code runs without Node integration and communicates through a narrow typed bridge.

Project status

Task Desk is an active early-stage implementation. Core task management, local RPC, the desktop task workflow, agent assignment, automations, persistence, and automated tests are present. Full production-build, native desktop, and real-Orca end-to-end smoke verification is still tracked in spec.md.

License

Task Desk is available under the MIT License.