TaskForge

A personal, calendar-based task manager delivered as an installable PWA with a token-authed REST API, so you can add and check tasks from the interface and programmatically from external tools (an agent CLI, an MCP server, scripts).

Everything runs as one Node process backed by a single SQLite file. No external database, no build step.

Features

• Inbox for undated tasks, plus Month, Week and Day calendar views.
• Create / edit / complete / delete tasks with time, category (with colour), deadline, notes and a subtasks checklist.
• Drag and drop tasks between days and out of the inbox (with reordering).
• Automatic rollover: a daily job moves unfinished tasks to today.
• Recurring tasks: daily / weekdays / weekly / monthly.
• Categories with colours and an always-visible legend plus filtering.
• Protected time (availability) blocks, such as work, childcare or holidays.
• Auto-scheduling: an endpoint that spreads your inbox across the calendar respecting deadlines and protected time. A deterministic heuristic is the default; an optional Claude-backed mode (enabled by ANTHROPIC_API_KEY) proposes the plan instead, with strict validation of its output and a fallback to the heuristic if the response is unusable.
• Gamification: an evolving "Grove" companion, streaks, milestones and a reward collection you can fill with images or videos from your own tools.
• Installable PWA: works on desktop and phone, with offline app-shell caching and optimistic writes that sync when you are back online.

Quick start (local)

npm install
npm start

Open http://localhost:4000. On first run an API token is printed to the console. Paste it into the unlock screen (it is stored in your browser); the same token authenticates external tools. Set a fixed token instead with the TASKFORGE_TOKEN env var.

Run the tests:

npm test

Run with Docker

docker compose up --build -d
docker compose logs -f taskforge     # grab the printed token on first run

The SQLite database persists in the taskforge-data volume. To pin a token and timezone, create a .env next to docker-compose.yml:

TASKFORGE_TOKEN=choose-a-long-random-string
TZ=Europe/Madrid
# ANTHROPIC_API_KEY=sk-ant-...   # optional, enables Claude auto-schedule

Configuration

Variable	Default	Purpose
PORT	4000	HTTP port
DATA_DIR	./data	Where taskforge.db lives
TZ	OS zone	Timezone used for "today", rollover, recurrence
TASKFORGE_TOKEN	(unset)	Initial API token; if empty, one is generated and printed
ANTHROPIC_API_KEY	(unset)	Enables mode:"claude" in the auto-scheduler

The API (for external tools)

Every route under /api (except /api/health) requires Authorization: Bearer <token>. Full reference: docs/API.md, the machine-readable public/openapi.json, and a rendered page at /docs while the server runs.

export TF=http://localhost:4000
export TOKEN=your-token
tf() { curl -s -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' "$@"; }

tf -X POST $TF/api/tasks -d '{"title":"Buy a desk lamp","category":"home"}'   # add
tf $TF/api/today                                                              # today
tf -X POST $TF/api/tasks/<id>/complete                                        # complete

Two ready-made clients live in this repo:

• integrations/taskforge-agent/: a dependency-free bash CLI intended for AI agents, with confirmation gates on destructive commands.
• mcp/: a standalone Model Context Protocol server that exposes the API as MCP tools for clients such as Claude Desktop and Claude Code.

There is also a thin Electron desktop shell in desktop/.

Deploying

Any host that runs a Node process or a Docker container works. Mount a volume at /data so the database survives restarts, and set TASKFORGE_TOKEN / TZ.

Project layout

src/
  server.js            # entry: boots DB, cron rollover, listens
  config.js            # env config
  db/                  # schema.sql, seed, repositories
  logic/               # pure, tested: recurrence, rollover, gamification, scheduler
  server/              # express app, auth, routes/
  services/            # completion + calendar services
public/                # the PWA (no build step): index.html, js/, vendor/, sw.js
integrations/          # agent CLI
mcp/                   # MCP server
desktop/               # Electron shell
docs/                  # API.md
test/                  # node:test unit + API integration tests

Licence

MIT. See LICENSE.