tasktracker

The local-first task board for you and your AI agents.

Claude and Cursor plan and update tasks over MCP. Agents propose, you approve: every change waits for one tap.

Working with agents stays low-effort: one calm board, changes in plain words, nothing leaving your machine.

_{A real MCP connection (a scripted demo agent) asking for three changes. Nothing moves until they're approved.}

💭 Why I built this

In the agentic AI era, the hard part isn't getting AI to do work. It's keeping up with it. Every new agent is one more thing to watch, one more place where work happens, one more stream of updates to read.

I wanted the opposite: a task board that gets calmer as AI gets more capable. One place where my agents and I share the same list, where I can see what happened at a glance, where nothing changes behind my back, and where the screen stays quiet enough to think. Task Tracker is that board.

🙋 Who it's for

Who it's not for: teams that need shared boards and permissions, sync across devices through a cloud account, or enterprise project management with resource planning. Task Tracker is for individuals who want calm over features, local over cloud, and AI as a helper rather than a replacement.

🧘 Calm, defined

"Calm" isn't a mood here; it's a set of promises:

• Four columns to start, not a workflow designer.
• Everything autosaves. There's no Save button anywhere.
• Deadlines read like a person wrote them: Due in 3h, Overdue by 2d.
• Agents ask first. Their changes wait for your OK, spelled out in plain words, and you approve them in one tap.
• No lock states to manage: an agent's "working on it" marker expires on its own, and stale changes are flagged before you approve them.
• The assistant proposes, you approve, and it can't delete anything.
• Agents show up where you already look: on the board, live, with no extra dashboard to check.
• Each reminder fires once, and a burst arrives as a single summary.
• Errors are plain sentences with a next step, never a stack trace.
• What you don't need is folded away: undated tasks, hidden columns and the archive stay out of sight until you ask.

Quick start

git clone https://github.com/Parv17k/tasktracker.git
cd tasktracker
npm install      # installs dependencies and builds the UI
npm start        # → http://localhost:1717

That's it. No database to install and no config files. SQLite is built into Node 22.13+, so there's nothing native to compile either.

🤖 Work with your AI agents (MCP)

Task Tracker ships with a Model Context Protocol server, so your agent can keep track of its own work, or yours.

Claude Code

claude mcp add tasktracker -- node /absolute/path/to/tasktracker/mcp/index.js

Claude Desktop, Cursor, Windsurf and other MCP clients

{
  "mcpServers": {
    "tasktracker": {
      "command": "node",
      "args": ["/absolute/path/to/tasktracker/mcp/index.js"]
    }
  }
}

Then just ask:

"What's overdue across all my projects?"
"Break task #3 into subtasks, tag it #backend and move it to In Progress."
"Log what you just did on #12 and mark it complete."

✋ Agents ask first

By default, an agent can read everything but can't change your board on its own. Each write becomes a request in the 🤖 Agent requests inbox:

• A gentle toast tells you "Claude Code wants to make 3 changes"; nothing interrupts you more than that.
• Each change is spelled out in plain words, with a checkbox. Untick what you don't want, then Apply, or Dismiss the lot.
• The agent is told what happened (get_request), including the ids of anything it created, so it can carry on.
• Trust an agent? Switch the inbox to Apply right away and its changes land directly, live on the board.

🤝 When two agents touch the same card

Things stay predictable without locks to babysit:

• "Working on it" claims, not locks. An agent can mark a card it's working on; the card shows 🤖 Claude Code is working on this. Other agents still get through, but they're told, and their requests are flagged for you.
• Claims can't get stuck. They expire after 30 minutes unless the agent keeps touching the card, vanish the moment the agent disconnects, clear when the card is done or archived, and you can Release one anytime. You can always edit a claimed card yourself.
• No stale overwrites. Each request remembers the values it would replace. If you (or another agent) changed them since the agent asked, the change is flagged "The title changed since Claude Code asked" and starts unticked.
• Everything else is simple: writes are one SQLite transaction at a time, edits only touch the fields they name, and notes are append-only, so two agents logging progress both keep their lines.

The MCP server works on the same SQLite file as the app, so agents can read your board even when the web server isn't running. When it is, open tabs update live within about half a second.

✨ The built-in assistant

Click ✨ in the top bar. Connect any OpenAI-compatible provider once (one-click presets for OpenAI, OpenRouter, Groq, Ollama and LM Studio), and your board gains an assistant.

_{"What should I focus on today?" A real, unedited answer from a self-hosted open model, grounded in the board behind it.}

_{"Summarize this project", asked from inside a board in the Rosé Pine theme. Also a real answer.}

🔒 What leaves your machine? Only when you ask: a summary of your tasks (and, by voice, your recording) goes to the provider you chose. Your API key is stored locally and never reaches the browser, which only ever sees …last4. Point it at Ollama or LM Studio and even that stays local.

🎯 Features

🗂️ Every project at a glance

• Totals and status breakdown for each project, with a progress ring, overdue and due-this-week counts
• Priority and tags on projects: mark what matters most, and filter the home page by tag (work, personal, Q4…)
• Coming up: everything due in the next 7 days across all projects; click a card to open that task
• Drag projects to reorder them; create, edit, archive or delete them. New projects start with four columns, or copy another project's

🗓️ Timeline: plan across time, drag to reschedule

Switch any board to Timeline. It's a Gantt chart without the clutter:

• A bar from start to deadline, or a ◆ when a task only has a deadline, grouped by column and coloured to match it
• Drag to reschedule: move a bar, drag its ends to change dates, or pull a ◆ out into a bar. Arrow keys work too, and times of day are kept
• Today is always in view; overdue items are red with "Overdue 2d"; finished ones fade
• Weeks or Months zoom, and the board's search, tag and deadline filters apply

On the home page, switch Projects to Timeline to see every project at once: one row each, with a ◆ for every deadline, so busy weeks stand out. Expand a project to see and reschedule its tasks right there.

📋 A board that adapts to you

Send invoice to Acme @fri !high #finance ~2h

_{Every field autosaves. Status, priority, deadline, start date, estimate, timer, tags, subtasks and note live in one calm panel.}

⏱️ Estimates and cost, only where you want them

• Size a task in one tap: XS (30m) · S (1h) · M (4h) · L (1d) · XL (3d), or type an exact amount like 90m or 2.5h.
• See it against reality: the panel shows "3h 10m tracked of ~4h", and the card's chip turns amber when you go over.
• Totals where they help: column headers show ~9h of estimated work, project cards show ~32h left.
• Cost, if you bill by the hour: give a project an hourly rate and currency, and estimates and tracked time turn into ~$320 est., $253 so far. No rate, no money on screen.
• Tasks without an estimate look exactly as before.

📝 Notes in Markdown, with diagrams

• Notes are formatted by default: headings, lists, tables, code, links. Click to write, Esc to finish; it autosaves.
• Checklists you can tick right in the formatted note (- [ ] item).
• Mermaid diagrams: a ```mermaid block becomes a flowchart, sequence or Gantt diagram, themed to match.
• Expand for a roomy side-by-side writer: Markdown on the left, the result on the right.
• Agents' progress logs still read one entry per line, and nothing in a note can run scripts.

🏷️ Tags that stay tidy

• Shared by tasks and projects, with suggestions as you type and a stable colour per tag
• Names ignore case, so Design and design are one tag; unused tags disappear on their own
• Manage tags to rename, recolour or delete one everywhere at once

📲 Install it, and get reminders

Task Tracker is a Progressive Web App: click Install in the top bar (Chrome, Edge, or Safari's Add to Dock) and it gets its own window and Dock/taskbar icon. Turn on reminders from the 🔔 bell:

• Works with the app closed: the local server sends reminders through the browser's push service, signed with keys generated on your machine. No account needed.
• Calm by design: each reminder fires once, done tasks never remind you, and a burst (say, after your laptop wakes) arrives as one summary.
• Click a notification to jump straight to that task.

Reminders while the app is closed need the Task Tracker server running and an internet connection for the browser's push service. Open windows also receive them over the local live-update stream.

🎨 Themes

Twenty-four themes designed for focus. Switch instantly from the brush icon; your choice applies everywhere and is remembered.

Old Money · hunter green & brass	Midnight Ink · deep navy	Terminal · neon green on black
Rosé Pine · soft rose on midnight	Sakura · soft blush	Dracula · purple after dark
Solarized · precise and warm	Gruvbox · retro and earthy	Bubblegum · playful pink
Grayscale · no colour, no glare	Navy & Gold · golden highlights	Neon Orange · glowing amber

Also included: Paper · New York · Nordic Frost · Sage Garden · Espresso Library · Graphite · Grayscale Dark · Crimson · Ivy · Cardinal · Sunset Orange · Harbor Gold

🏗️ How it works

flowchart LR
    subgraph clients[" 👥 Clients "]
        direction TB
        UI["🖥️ <b>React UI</b><br/><small>Board · Timeline · Chat · Voice</small>"]
        AGENT["🤖 <b>AI Agent</b><br/><small>Claude · Cursor · any MCP client</small>"]
    end

    subgraph node["&nbsp;⚙️ Node.js&nbsp;"]
        direction TB
        API["⚡ <b>Fastify API</b><br/><small>server/index.js · REST + SSE</small>"]
        CHAT["✨ <b>Assistant</b><br/><small>chat.js · actions.js · voice</small>"]
        MCP["🔌 <b>MCP Server</b><br/><small>mcp/index.js · 21 tools</small>"]
        CORE["🧠 <b>Shared data layer</b><br/><small>server/db.js · rules &amp; validation</small>"]
        WATCH["👀 <b>Change watcher</b><br/><small>PRAGMA data_version</small>"]
    end

    DB[("🗄️ <b>SQLite · WAL</b><br/><small>~/.tasktracker/tasktracker.db</small>")]
    LLM["🧠 <b>Your LLM</b><br/><small>chat · speech-to-text · voice<br/>OpenAI · Groq · Ollama · LM Studio</small>"]

    UI -->|"HTTP · JSON<br/>optimistic updates"| API
    API -.->|"SSE · live updates"| UI
    AGENT <-->|"stdio · JSON-RPC"| MCP
    API --> CORE
    API --> CHAT
    CHAT --> CORE
    CHAT <-->|"OpenAI-compatible API<br/>streamed"| LLM
    MCP --> CORE
    CORE <-->|"~1 ms queries"| DB
    DB -.->|"writes from<br/>other processes"| WATCH
    WATCH -.->|"broadcast"| API

    classDef client fill:#eef2ff,stroke:#6366f1,stroke-width:2px,color:#1e1b4b
    classDef agent fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#2e1065
    classDef server fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b
    classDef core fill:#fff7ed,stroke:#f97316,stroke-width:2.5px,color:#431407
    classDef watch fill:#f0f9ff,stroke:#0ea5e9,stroke-width:1.5px,stroke-dasharray:4 3,color:#082f49
    classDef db fill:#fefce8,stroke:#ca8a04,stroke-width:2.5px,color:#422006
    classDef llm fill:#fdf2f8,stroke:#db2777,stroke-width:2px,stroke-dasharray:5 3,color:#500724

    class UI client
    class AGENT agent
    class API,MCP,CHAT server
    class CORE core
    class WATCH watch
    class DB db
    class LLM llm

    style clients fill:transparent,stroke:#94a3b8,stroke-width:1px,stroke-dasharray:6 4,color:#64748b
    style node fill:transparent,stroke:#94a3b8,stroke-width:1px,stroke-dasharray:6 4,color:#64748b

• One data layer (server/db.js) holds every business rule, shared by the API, the assistant and the MCP server, so humans and agents always behave the same way.
• Grounded chat without tool calling: the server sends the model a compact, budgeted snapshot of your board, and the model proposes changes as a small structured block that the app validates and shows for approval. It works even with small local models. Your API key never reaches the browser.
• Live sync without polling the API: the server watches SQLite's PRAGMA data_version and pushes changes from other processes to browsers over Server-Sent Events.
• WAL mode lets the web app and an agent write at the same time.
• Optimistic UI with fractional ordering means drag & drop, on the board or the timeline, never waits on the server.

sequenceDiagram
    autonumber
    actor You
    participant UI as 🖥️ Browser
    participant API as ⚡ Fastify API
    participant DB as 🗄️ SQLite
    participant LLM as 🧠 Your LLM

    You->>UI: "What should I focus on today?" (typed or spoken)
    UI->>API: POST /api/chat (conversation + open project)
    API->>DB: active projects, columns, tasks
    API->>API: build a compact snapshot<br/>(local dates, due labels, priorities, tags)
    API->>LLM: system prompt + snapshot + conversation<br/>(your key is added here, server-side)
    LLM-->>API: streamed tokens
    API-->>UI: streamed text
    Note over UI: Answer appears word by word ✨<br/>and can be read aloud 🔊
    opt the answer proposes changes
        UI->>API: preview the proposed changes
        API-->>UI: plain-language list, checked against the board's rules
        UI->>You: approval card: tick what you want
        You->>UI: Apply
        UI->>API: apply the approved changes
        API->>DB: one transaction, all or nothing
        API-)UI: board updates live
    end

sequenceDiagram
    autonumber
    participant AI as 🤖 AI Agent
    participant MCP as 🔌 MCP Server
    participant DB as 🗄️ SQLite
    participant API as ⚡ Fastify API
    participant UI as 🖥️ Browser

    AI->>MCP: complete_task(id: 12, note: "Shipped ✅")
    alt Ask me first (default)
        MCP->>DB: save a request for your approval
        MCP-->>AI: waiting for approval (request 7)
        Note over DB: You tap Apply in the inbox
        DB->>DB: append note + move to Done (one transaction)
    else Apply right away
        MCP->>DB: append note + move to Done (one transaction)
        MCP-->>AI: ✓ Completed task 12 → Done
    end
    loop every 500 ms
        API->>DB: PRAGMA data_version
    end
    DB-->>API: version changed
    API-)UI: SSE event: change
    UI->>API: GET /api/board
    API-->>UI: full board (~1 ms)
    Note over UI: Card glides into Done ✨<br/>no refresh needed

sequenceDiagram
    autonumber
    participant REM as ⏰ Reminder engine
    participant DB as 🗄️ SQLite
    participant PUSH as ☁️ Browser push service
    participant SW as 🔔 Service worker
    actor You

    loop every minute
        REM->>DB: open tasks with deadlines
    end
    REM->>REM: due and not yet sent?
    REM->>DB: log it (each reminder fires once)
    REM->>PUSH: Web Push, signed with local VAPID keys
    PUSH->>SW: deliver, even if the app is closed
    SW->>You: "Due in 30 min · Send proposal"
    You->>SW: click
    SW-->>You: opens that task

The AI provider (and optional voice models) is configured in the app (✨ → settings) and stored in the same database.

🧭 Roadmap

Task Tracker is young and moving fast. Here's where it's heading, and every item is open for contributors. Comment on an issue (or open one) to claim it.

✅ Recently shipped

• ⏱️ Estimates and cost: XS–XL sizes or exact amounts, over-estimate hints, per-project hourly rate
• 📝 Markdown notes with tickable checklists and Mermaid diagrams
• 🤝 Multi-agent safety: "working on it" claims that expire on their own, and warnings for changes made since an agent asked
• ✋ Agents ask first: MCP changes wait in an approval inbox (or apply right away, your choice)
• 🎙️ Voice: talk to the assistant and hear it answer, hands-free
• ✅ Assistant actions with an approval card for every change, and plain-language errors
• 🗓️ Timeline (Gantt) per project and across projects, with drag to reschedule and optional start dates
• 🏷️ Tags on tasks and projects, and project priority
• ✨ AI chat with any OpenAI-compatible provider, grounded in your board
• 🗂️ Multiple projects with a home page, drag-to-reorder projects and columns
• 📲 Installable app with deadline reminders that work while it's closed
• 🎨 Twenty-four themes

🤖 AI and agents

📋 Planning and productivity

🔄 Data and platforms

_{🧪 Exploring: open design question · 📋 Planned: agreed direction · 🙋 Help wanted: ready to pick up}

🛠️ Development

npm run dev     # API on :1717 + Vite with hot reload on :5173
npm test        # data layer, reminders, tags, timeline, chat, actions and voice tests (node:test)
npm run build   # production build of the UI

🤝 Contributing

Contributions of every size are welcome, from fixing a typo to adding a theme or building the planning agent. If this is your first open-source contribution, even better: we'd love to help you land it.

1. Read the Contributing Guide. It takes about 3 minutes.
2. Pick something from the roadmap, look for issues labelled good first issue, or browse the ideas list.
3. Fork, branch, code, and open a pull request.

Not sure where to start? Open an issue and say hi. 👋

Please be kind, be patient, and assume good intent.

⭐ Support

If Task Tracker helps you stay focused, consider starring the repo. It helps others find it.

License

MIT © Parv Khatri