TaskFlow

CLI task manager: capture raw thoughts into an inbox, optionally classify with an LLM into structured tasks, then work from the terminal or a local web dashboard. The global command is task.

Requirements

• Node.js 18+
• For task process: an Anthropic-compatible API key (or credentials in Claude Code settings — see below)

Install

git clone https://github.com/borankux/taskflow.git
cd taskflow
npm install
npm run build
npm link          # optional: install `task` on your PATH

The task binary runs dist/index.js. dist/ is not committed; always run npm run build after clone or pull.

Quick start

task setup
task add "ship the thing we discussed"
task process       # needs API credentials
task today
task list

Data lives under ~/.taskflow/ (tasks.json, inbox.jsonl, config.json, …). Never commit that directory — it may contain your tasks and any API-related overrides. Add your own product or codeword hints under project_keywords in config.json after task setup (defaults are generic).

Do not put API keys in the repo; use environment variables or your local Claude Code settings.json as documented below.

Commands (summary)

Command	Purpose
task setup	Initialize ~/.taskflow/
task add "<text>"	Append to inbox
task inbox	Show inbox
task process	LLM classifies inbox → tasks
task today / task list	Views and filters (-d, -s, -a, -g, -t)
task start | done | archive | snooze | edit | reclass	Update tasks
task focus	Rank open work (local heuristic)
task dashboard	Local web UI (127.0.0.1, ports 3939–3949)

Use task <cmd> --help for options.

Agents and --json

For scripts and AI agents, prefer machine-readable output (single line of JSON on stdout, no ANSI, full titles):

task list --json --limit 20
task today --json
task inbox --json
task list --json --profile full --include raw,notes --limit 1
task done 12 --json

• Read commands use an envelope: {"taskflow":1,"command":"…","meta":{…},"data":{…}}.
• Mutations with --json: {"ok":true,…} or {"ok":false,"code":"…","error":"…"} (non-zero exit on failure).

Default task objects are slim (id, title, domain, priority, status, effort, due, parent_id, snoozed_until). Use --profile full or --include for more fields.

See skills/taskflow/SKILL.md for full agent-oriented documentation.

API credentials (task process)

1. Environment: ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY (optional ANTHROPIC_BASE_URL, ANTHROPIC_MODEL).
2. If unset, the CLI loads env from ~/.claude/settings.json (same pattern as Claude Code).

Web dashboard

task dashboard

Open the printed URL. Avoid heavy concurrent edits from both the CLI and the browser against the same tasks.json.

Development

npm run dev    # tsc --watch
npm run build