Start here

What is Taskum

If you use AI coding agents, you've felt these problems:

  • Every session starts from zero. The agent doesn't remember what it built yesterday, what patterns the project uses, or why a decision was made.
  • Every agent starts blind. Cursor doesn't know what Claude Code did. A teammate's agent doesn't know what yours decided.
  • You review code too late. The agent jumps into implementation, makes bad assumptions, and you discover them after the code exists.
  • Project knowledge lives in your head. Architecture decisions, conventions, context — trapped in chat logs and stale notes that no agent reads.

Taskum is shared context and an approval workflow for AI coding agents.

Every agent session starts from the same project docs — architecture, conventions, past decisions — and in gated workflows the server refuses to let execution begin until a human approves the plan. Planning before code isn't a convention the agent follows; it's a gate the server enforces.

Without Taskum

Explain the project again. Hope the agent makes a good plan. Discover bad assumptions after the code is written. Lose the reasoning when the session ends.

With Taskum

The agent reads the project docs. Writes a design. Writes an implementation plan. Executes tasks. Updates the project record for the next session. And on gated work, the agent doesn't choose to wait for your approval between those steps — it cannot proceed without it.

The knowledge accumulates. Each session makes the next one better.

Core concepts

The six things to know

Six nouns, two gates, four workflows. That's the whole model.

Project

The home for one product or codebase. Everything — docs, issues, team membership — lives in a project.

Project docs

The shared context that every agent reads at session start. Four types:

  • Brief — what the project is, who it's for, the tech stack, the repo URL.
  • Architecture — components, data flow, boundaries, how state lives.
  • Conventions — coding style, patterns, verification commands.
  • Roadmap — what's in flight and what's being considered. Not what's done — issues are the record.

Roadmap

Where ideas live before they become work. Add to it from the dashboard, your phone, or by asking your agent. Don't create issues for things you're not ready to do — put them on the roadmap.

Issue

One planned unit of work — a feature, a fix, a refactor. An issue holds its design doc, implementation plan, tasks, comments, and deliverables. It's the complete record of what was done and why. Every issue ends with a work record: a computed execution summary — task durations, timeline, deliverables — derived from the event log, not claimed by the agent.

Task

One executable step from the implementation plan. Tasks have instructions detailed enough for any agent to execute, plus a verification command. The agent works through them one by one.

Workflow

How much process an issue gets — chosen per issue, from double-gated down to none:

  • Full — design and plan, each human-approved. For features and refactors.
  • Quick — the design is obvious; you approve just the plan.
  • Direct — small fix: create the issue, execute, done. No documents, no gates.
  • Auto — design and plan still required, but reviewed by an independent agent instead of a human. No gates; the review trail is the accountability.

Process proportional to risk. A one-line fix shouldn't cost two reviews; a new subsystem shouldn't skip them.

The two review gates

Design review asks: are we solving the right problem in the right way? You review the approach before any code is written.

Plan review asks: are these the right concrete steps? You review the task list before execution begins.

In the full and quick workflows, these are server-side gates, not conventions: task execution is refused until the plan is approved, and no agent credential can approve anything — in any workflow, approval is human-only by construction. Bad ideas get caught at the design gate. Bad execution plans get caught at the plan gate.

Get started

Your first 10 minutes

This is the path from zero to your first completed issue.

  1. Connect your agent. Add Taskum as an MCP server in your agent's config. (Setup instructions by agent)
  2. Ask the agent to set up a project. Tell it "set up a taskum project for this codebase." It creates the project, reads the codebase, and writes the project docs (brief, architecture, conventions, roadmap). You can also create a project in the dashboard if you prefer.
  3. Review the project docs in the dashboard — this is the shared context every future session will start from.
  4. Capture ideas on the roadmap. When you think of something — a feature, a fix, an improvement — add it to the roadmap's Considering section. Don't create issues yet.
  5. Create an issue when you're ready to do the work. Discuss the idea with the agent first. Make sure you both understand the problem and the approach. Then ask it to create the issue.
  6. Let the agent write the design. It produces a design doc in plain English: the context, the problem, the approach, the scope.
  7. Review and approve the design in the dashboard. Give feedback if something's off — the agent updates the design and resubmits.
  8. Let the agent write the plan and tasks. Concrete steps, each with instructions and a verification command.
  9. Review and approve the plan in the dashboard. This is the exact work that will be done.
  10. Watch the agent execute. It works through tasks one by one, posts a summary when done, and updates the project docs if anything changed.

That's the full workflow — the most process an issue can get. Lighter workflows (quick, direct, auto) skip gates you don't need; see core concepts. Either way, the next time you start a session, the agent reads the updated project docs and the completed issue — it picks up where the last session left off.

Prompts

What to tell your agent

You don't need to know tool names. Talk to your agent in plain language — it knows how to use Taskum.

First time setup

Set up a taskum project for this codebase.

Starting a session

List the taskum projects and load the one matching this codebase.

Capturing an idea

Add "support webhook notifications on task completion" to the Considering section of the roadmap.

Starting real work

Let's discuss adding rate limiting to the API. When we agree on the approach, create an issue.

Picking up existing work

Load issue rate-limiting and continue from where it left off.

Asking for a review

Review the completed issue auth-refactor and leave a comment with anything you'd improve.

Updating docs after learning something

The tests need a local Postgres running — update the conventions doc so future agents know.
Installation

Connect your agent

The fast path: OAuth

Most clients connect with no key at all:

  1. Point the client at https://taskum.com/mcp
  2. It discovers the OAuth endpoints automatically
  3. A browser window opens for you to approve the connection
  4. The client receives tokens that auto-refresh for 30 days of use

No key to copy, no config beyond the URL. Confirmed for Claude Code, Claude Desktop, Cursor, Windsurf, Continue.dev, Zed, OpenAI Codex, and VS Code (Copilot).

The fallback: an API key

If your client doesn't do MCP OAuth (or you prefer a key):

  1. Log in to taskum.com
  2. Go to Settings → API Keys
  3. Create a new agent key
  4. Copy the key (shown once — starts with tkapi_) and use it as YOUR_API_KEY below

Every config example below was verified against the client's own documentation on 2026-07-07. Formats churn — if one fails, check the linked vendor docs first.

Claude Code

Add to .mcp.json in your project root (project scope; ~/.claude.json for user scope):

{
  "mcpServers": {
    "taskum": {
      "type": "http",
      "url": "https://taskum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "alwaysLoad": true
    }
  }
}

The type key is required — an entry with a url but no type is treated as a misconfigured stdio server and silently skipped. alwaysLoad: true (v2.1.121+) matters too: Claude Code defers MCP tool loading by default, and without it the session-startup flow won't work on the first message. For OAuth instead of a key, run /mcp after adding the server without the headers block. Env expansion like "Bearer ${TASKUM_TOKEN}" is supported. Vendor docs.

Claude Desktop

No config file for remote servers — claude_desktop_config.json is for local stdio servers only. Instead: Settings → Connectors → Add custom connector, paste https://taskum.com/mcp, and complete the OAuth prompt. Note that custom connectors reach the server from Anthropic's cloud, not your machine (fine for taskum.com), and the Free plan allows one custom connector. Vendor docs.

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global). A bare url marks the server remote — no type key:

{
  "mcpServers": {
    "taskum": {
      "url": "https://taskum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Omit headers to use OAuth — Cursor runs the flow automatically. Secrets can be referenced as ${env:TASKUM_TOKEN}. Vendor docs.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json. Remote servers use serverUrl, not url:

{
  "mcpServers": {
    "taskum": {
      "serverUrl": "https://taskum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OAuth is supported per the current vendor docs (now hosted at docs.devin.ai after the Cognition consolidation). Vendor docs.

Cline (VS Code)

MCP Servers icon → Configure → "Configure MCP Servers" (the extension manages cline_mcp_settings.json; the CLI reads ~/.cline/mcp.json). The type key is streamableHttp — camelCase, unique to Cline; a wrong or missing type silently falls back to a legacy transport:

{
  "mcpServers": {
    "taskum": {
      "type": "streamableHttp",
      "url": "https://taskum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OAuth support is not confirmed in Cline's documentation — use the key. Vendor docs.

Continue.dev

Continue's config is YAML now. Add to ~/.continue/config.yaml:

mcpServers:
  - name: taskum
    type: streamable-http
    url: https://taskum.com/mcp
    requestOptions:
      headers:
        Authorization: "Bearer YOUR_API_KEY"

OAuth is supported since v1.2.1 — omit requestOptions to use it. (The requestOptions.headers form is documented indirectly; it's confirmed working in Continue's own issue tracker.) Vendor docs.

Zed

Add to Zed's settings.json (zed: open settings) under context_servers:

{
  "context_servers": {
    "taskum": {
      "url": "https://taskum.com/mcp"
    }
  }
}

With no headers configured, Zed prompts you through the standard MCP OAuth flow — the config above is the complete setup. To use a key instead, add "headers": { "Authorization": "Bearer YOUR_API_KEY" }. Vendor docs.

OpenAI Codex

Add to ~/.codex/config.toml (TOML, not JSON):

[mcp_servers.taskum]
url = "https://taskum.com/mcp"
bearer_token_env_var = "TASKUM_TOKEN"

bearer_token_env_var names an environment variable holding your key. For OAuth instead, drop that line and run codex mcp login taskum. Vendor docs.

GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your workspace — the root key is servers, not mcpServers:

{
  "servers": {
    "taskum": {
      "type": "http",
      "url": "https://taskum.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:taskum-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "taskum-token",
      "description": "Taskum API key",
      "password": true
    }
  ]
}

The ${input:...} variable prompts once and stores the key securely — VS Code's docs warn against hardcoding tokens. Omit headers for the automatic OAuth flow. Vendor docs.

stdio-only clients

If a client only speaks stdio MCP, the Taskum CLI bridges it: install the taskum CLI, then configure the client to run taskum serve with TASKUM_API_KEY and TASKUM_SERVER=https://taskum.com in its environment. The bridge relays stdio to /mcp unchanged.

On your phone

Taskum on your phone

The dashboard installs as an app and pushes a notification the moment something needs you — a document awaiting your approval, an agent finishing its last task, review findings landing as comments. You review and approve from wherever the buzz finds you.

iPhone / iPad

  1. Open taskum.com in Safari and log in
  2. Share → Add to Home Screen
  3. Open the installed app, go to Settings → Notifications, and tap Enable notifications on this device

iOS delivers web push only to installed apps, and only asks permission from a tap — both steps are required, in that order. Requires iOS 16.4 or later.

Android

  1. Open taskum.com in Chrome, log in, and enable notifications under Settings → Notifications — installing is optional
  2. For the app experience, accept Chrome's install prompt (or menu → Add to Home screen)

Desktop

The same switch works in desktop Chrome and Edge. Every device you enable appears under Settings → Notifications, where you can remove devices and choose which kinds of notifications reach you.

Example

Learn the workflow by example

Here's what a real issue looks like, start to finish.

The idea

You're building an API and realize you need rate limiting on the auth endpoints. It's not urgent, so you tell the agent:

Add "rate limiting on auth endpoints" to the Considering section of the roadmap.

The idea sits on the roadmap. No issue, no planning, no commitment.

Ready to work

A week later, you decide it's time. You start a session and discuss it:

Let's discuss adding rate limiting to the login and register endpoints. What approach would you recommend?

The agent reads the project architecture, looks at the existing auth handlers, and proposes an approach. You go back and forth — maybe you want per-IP limits, maybe you want different thresholds for login vs. registration. Once the approach is clear:

Create an issue for this. Full workflow.

The design

The agent creates the issue and writes a design doc. It covers: what exists today (no rate limiting, endpoints are open), the problem (brute-force risk), the approach (per-IP GCRA quotas via tower middleware), what's in scope, and what's explicitly not (API endpoint limiting, which is a different threat model).

You open the dashboard and read the design. The approach looks right, but you notice the agent didn't consider what happens behind a reverse proxy — the client IP needs to come from a forwarded header. You tell the agent:

The design needs to account for the reverse proxy. Client IP should come from X-Forwarded-For when the peer is localhost.

The agent updates the design. You review again, it looks good, and you approve in the dashboard.

The plan

The agent writes the implementation plan: three tasks. Task 1 adds the rate limiter middleware with per-IP extraction. Task 2 wires it onto the login and register routes with different thresholds. Task 3 adds the 429 response handling with Retry-After headers. Each task has instructions detailed enough for any agent to follow, plus a verification command.

You review the plan and approve.

Execution

The agent works through tasks one by one. Each task: start, implement, verify, complete with a deliverable. You can watch progress in the dashboard as tasks move from "ready" to "done."

Wrap-up

After the last task, the agent posts a summary comment on the issue: what was built, the key decisions (GCRA over token bucket, loopback-trust IP extraction), and what to watch for (register enumeration is only slowed, not fixed). It updates the architecture doc to reflect the new middleware and adds the rate limit config to conventions.

The next session

A month later, a different agent connects to the project. It reads the architecture doc and sees the rate limiting middleware. It reads the roadmap and sees the register enumeration follow-up. It reads the completed issue and understands exactly why the IP extraction works the way it does.

Nobody had to explain anything. The knowledge was already there.

Deeper

Why it works

The gates you turn on, the server enforces

In gated workflows, task execution is refused until the plan is approved, and no agent credential can approve anything. The check runs in the server, not in a prompt the agent might drift from. The gates are yours to choose per issue; once on, they are not the agent's to skip.

Project docs are shared context

Every agent session starts by reading the project docs. The architecture, conventions, and roadmap survive across sessions, across agents, and across team members. Each session makes the docs richer, which makes the next session more productive. It's a flywheel.

Issues are the record

An issue holds the design (why this approach), the plan (how it was executed), the review comments (what was caught), and the deliverables (what was produced). A new agent picking up related work reads the issue and understands not just what was built, but why.

Review catches problems before code

Humans review at two gates: the design and the plan. Bad approaches get caught before code is written, not after. But review isn't just human-to-agent — other agents and team members can review completed issues and leave comments that shape future work.

Cross-issue context builds understanding

Agents read recent issues before starting new work. An agent working on issue #5 has the benefit of everything learned in issues #1 through #4. This turns disconnected sessions into a coherent development process.

Shared knowledge across agents and team members

Different people use different agents — Claude Code, Cursor, Cline, Windsurf. Taskum's project docs replace per-agent config files (CLAUDE.md, AGENTS.md) with a single source of truth that every agent reads and the whole team maintains. The docs stay current because updating them is part of the workflow, not a separate chore.

New team members hit the ground running

When someone new joins, they connect their agent to the project. The agent reads the accumulated project docs and recent issues. No stale wiki, no "ask the person who built it" — the new person's agent starts from the same shared context as everyone else's on day one.

Planning grounds the agent in reality

Without structure, agents hallucinate — changing functions that don't exist, updating files that aren't there. The implementation plan forces the agent to read the actual codebase before writing, so it self-corrects during planning. Hallucinated functions and phantom files get caught in the plan, not in your code review.

Docs get better because agents fail

When an agent hits something undocumented — tests need a local database, a build step has a dependency — it figures it out. Taskum instructs the agent to update the project docs when it completes the work, so the gap gets fixed as part of the workflow. The next agent finds the answer already there.

The roadmap is a living backlog

Ideas go on the roadmap, not into issues. The roadmap is low-commitment — capture thinking, not commitments. When you're ready to do the work, you create an issue. This prevents premature planning and keeps agents focused on work you've actually decided to do.