@taskwright/cli

The Taskwright command-line tool. Runs a local daemon that orchestrates Claude Code, Codex CLI, Gemini CLI, and Cursor Agent — running them durably in the background, on a schedule, with policy guardrails and silent failover when one provider rate-limits.

BYO-subscription. Taskwright never pays for inference. Your Claude Max, ChatGPT Plus, Gemini Advanced, and Cursor accounts stay yours, and so do their token budgets. We orchestrate the agent CLIs you already have installed.

Install

npm i -g @taskwright/cli

Requires Node.js ≥ 22. Works on macOS, Linux, and Windows 10+.

Quick start

# 1. Initialize the data directory and config
taskwright init

# 2. Authenticate against the cloud (opens your browser)
taskwright login

# 3. Start the daemon in the foreground
taskwright start

That's it. Once the daemon is running, head to taskwright.dev, define an outcome, and watch your agent run — stdout streams to your dashboard in real time.

Commands

| Command | Description | | ------------------ | ------------------------------------------------------------ | | taskwright init | Seed the data directory (~/.taskwright) and config file | | taskwright login | Device-code OAuth flow — opens browser, mints daemon API key | | taskwright logout| Revoke the daemon API key locally | | taskwright start | Run the daemon in the foreground (PID lock, SIGTERM-safe) | | taskwright stop | Graceful shutdown of a running daemon | | taskwright status| Print PID + lastSeen state |

Run taskwright --help for full flag details, or taskwright <cmd> --help.

How it works

+---------------------+         +----------------------+
|   Web dashboard     |  HTTPS  |   Taskwright cloud   |
|  (taskwright.dev)   |◀───────▶|  (Vercel + Postgres) |
+---------------------+         +----------+-----------+
                                           │ HTTPS / Bearer auth
                                           ▼
                                  +----------------+
                                  |  taskwright    |  <- this CLI
                                  |  (your laptop) |
                                  +-------+--------+
                                          │ child_process.spawn
                       ┌──────────────────┼─────────────────────┐
                       ▼                  ▼                     ▼
                  Claude Code         Codex CLI            Gemini CLI
                  (your sub)         (your sub)           (your sub)

• Daemon (this CLI) runs locally, polls the cloud for assigned jobs every 60 seconds, and spawns the agent CLI of your choice as a child process.
• Cloud is a Next.js app that holds the source of truth: outcomes, jobs, schedules, run history. It assigns jobs to your daemon and receives streamed events back.
• Code never leaves your machine. Only run metadata (timestamps, exit codes, stdout chunks for the dashboard) is synced over the wire.

Data directory

By default, Taskwright stores config, credentials, and run history under:

• macOS / Linux: ~/.taskwright/
• Windows: %USERPROFILE%\.taskwright\

Override with --data-dir <path> on any command, or set TASKWRIGHT_DATA_DIR.

Layout:

~/.taskwright/
├── config.json          # api-url, log level, etc.
├── credentials.json     # daemon API key (chmod 600 on POSIX)
├── daemon.db            # SQLite store (jobs, runs, events)
├── .pid                 # PID lock for the running daemon
└── logs/
    └── daemon-2026-04-26.log

Logging in / out

$ taskwright login
Visit: https://taskwright.dev/cli-auth?code=ABCD-1234
(waiting for approval…)
✔ Logged in as [email protected]

$ taskwright logout
✔ Credentials cleared

Configuration

~/.taskwright/config.json:

{
  "apiUrl": "https://taskwright.dev",
  "logLevel": "info",
  "concurrency": 1
}

Each value can be overridden by a flag (--api-url, --log-level, etc.).

Supported agent CLIs

The daemon spawns whichever of these you have installed and authenticated:

• Claude Code — claude (Anthropic)
• Codex CLI — codex (OpenAI)
• Gemini CLI — gemini (Google)
• Cursor Agent — cursor-agent

If none are installed, taskwright start will warn you and skip job assignment until at least one is available.

Troubleshooting

• Not logged in — run taskwright login.
• PID file already exists — another daemon is running, or a previous process didn't shut down cleanly. taskwright stop will clean up.
• Codex on Windows fails to spawn — see the Windows shell-fix doc.

License

MIT — see LICENSE.