taskpod

taskpod

The developer CLI and MCP server for Taskpod — the AI-native task tracker where humans and agents work the same board.

Your repo's central mind. Three commands take a bare clone to a fully wired workspace where you, your teammates, and every AI agent share one live picture of the project — tasks, sprint, dependencies, and the learnings everyone records as they work:

npx taskpod login          # 1. authorize this machine (opens your browser)
npx taskpod init           # 2. repo-first: creates/links the project from your git remote + pulls context
npx taskpod agent-setup    # 3. connects Claude Code, Cursor, or any MCP client

Then, as you work:

npx taskpod sync           # ↑ share new learnings · ↓ pull the latest board, learnings, wiki, sprint

This one package ships two things:

• taskpod — a CLI that links a repo to a Taskpod project, syncs a live .taskpod/ context bundle to your machine and your local AI, and writes work back to the board.
• taskpod mcp — an MCP server (stdio) that exposes Taskpod's tools to any MCP client (Claude Code, Cursor, etc.).

Both talk to the Taskpod REST API over HTTPS with your personal token — no database access, no secrets in your repo. No install needed (npx taskpod …), or install globally with npm i -g taskpod.

The flow

taskpod init — the repo is the project. Run inside a git repo and init reads your origin remote, asks the server to create (or find) the Taskpod project for that repo, links the repo (taskpod.json), and pulls the .taskpod/ context bundle — one command from clone to ready:

$ npx taskpod init
Detected git remote: acme/web
✓ Created web (WEB) from acme/web.

Workspace ready: WEB — 12 tasks, 3 learnings.
Run taskpod status, or taskpod agent-setup to connect your AI tools.

Run it in a teammate's clone of the same repo and it links to the same project (created: false) — the repo is the identity. --team "Name" files the project under a specific team (creating it if needed). Outside a git repo, or with an explicit --name "Project", the original flow still works: npx taskpod init --team "My Team" --name "My App" creates a named project non-interactively (agent-friendly).

taskpod agent-setup — one command connects every AI tool. Writes real MCP config for the tools it detects in your repo (flags for CI: --claude, --cursor, --codex, --all):

• Claude Code — merges a taskpod server entry into .mcp.json (never clobbers your other servers) and adds a marker-guarded TaskPod section to CLAUDE.md pointing at the context bundle and taskpod.in/skill.
• Cursor — same server entry in .cursor/mcp.json.
• Anything else (Codex, Windsurf, …) — prints the command (npx -y taskpod mcp) + skill URL.

By default no secret is written: taskpod mcp picks up your taskpod login token automatically on each machine. For CI or containers, --with-key [token] embeds env.TASKPOD_TOKEN in the config (don't commit that). Re-running updates everything in place — never duplicates.

taskpod sync — the bidirectional central mind. One command keeps you and the board in lockstep:

• ↑ push — new entries in .taskpod/learnings.md (one per ## title heading, body below; optional kind prefix like ## [gotcha] title — learning | decision | convention | gotcha), plus anything passed as --note "...", are shared to the project's learnings. Pushed entries are fingerprinted in .taskpod/.synced, so sync is idempotent and never double-posts; the outbox is consumed after pushing.
• ↓ pull — refreshes the whole .taskpod/ bundle, including LEARNINGS.md: the project's shared memory (everyone's decisions, conventions, and gotchas) rendered for your local AI to read.

$ npx taskpod sync --note "prisma db push needed after schema changes"
✓ ↑ 2 learnings shared · ↓ context updated: 14 tasks, 5 learnings.

CLI

Auth & link
  login                       authorize this machine in the browser
  logout                      remove stored credentials
  whoami                      show the signed-in user
  init [--team T --name N]    create/link the project from this repo's git remote + pull
  link [KEY]                  connect this repo to a project (writes taskpod.json)
  agent-setup                 connect Claude Code / Cursor / any MCP client to this project

Context
  sync [--note "..."]         push new .taskpod/learnings.md entries ↑ + pull context ↓
  pull                        sync .taskpod/ (context, board, mine, deps, resources, learnings, skill)
  status                      your tasks + board summary + sync age
  mine [--blocked]            just your tasks
  show <ticket>               full task detail
  resources [--json]          list the project's resources (repos, docs, designs…)
  setup [--clone]             clone repos + list every resource to get you working
  doctor                      health check: local git vs board drift

Work
  start <ticket> [-m note]    → IN_PROGRESS + checkpoint comment
  done  <ticket> [-m report]  → IN_REVIEW + work-report comment
  comment <ticket> -m ".." [-t progress|decision|blocker|handoff|question]
  eta <ticket> <when> [--confidence low|med|high]
  assign <ticket> --to <name|email>          reassign to a human teammate
  handoff <ticket> --to-agent [name]         hand to an agent (needs acceptance criteria)
  handoff <ticket> --to-human --needs "..."  hand back to a human

Other
  skill --install             install the agent protocol into this repo
  mcp [--api-key <tok>]       run the MCP server on stdio (defaults to your login token)

Config & credentials. A committed taskpod.json in the repo records { apiBase, projectId, projectKey }. Your token is stored separately in ~/.config/taskpod/credentials.json (mode 0600) — never in the repo. Override with TASKPOD_API_URL / TASKPOD_TOKEN.

The .taskpod/ bundle. taskpod pull/sync write context.md, board.json, mine.md, deps.md, resources.md, LEARNINGS.md (the project's shared memory), plus SKILL.md and AGENTS.md (the agent protocol) so your local AI has full, live project context. .taskpod/ is git-ignored automatically.

Resources. Each project carries a catalog of the links a human or agent needs to work on it — repos, docs, BRDs, designs, cloud consoles, dashboards, SOPs, and environments. taskpod resources lists them grouped by type; taskpod setup gets you ready to work by printing a git clone for every REPO resource (add --clone to actually run them, skipping repos already checked out) and listing the rest grouped. taskpod pull also materializes them into .taskpod/resources.md (grouped, with a clone command per repo) and a Resources section near the top of .taskpod/context.md, so an agent reading context immediately knows where everything lives.

MCP server

taskpod agent-setup writes this config for you. To wire it by hand: if you've run taskpod login, no key is needed — taskpod mcp uses your stored login token automatically:

claude mcp add taskpod -- npx -y taskpod mcp

Or point any MCP client at the stdio server with an explicit token:

// .mcp.json (Claude Code) or your client's MCP config
{
  "mcpServers": {
    "taskpod": {
      "command": "npx",
      "args": ["-y", "taskpod", "mcp", "--api-key", "tp_live_xxx"]
    }
  }
}

Create a token in Taskpod under Settings → API Access. Auth precedence: --api-key > API_KEY env > TASKPOD_TOKEN env > ~/.config/taskpod/credentials.json (written by taskpod login).

The server exposes the full Taskpod toolset — teams, projects, folders, tasks, comments, subtasks, dependencies, lifecycle, and handoff — plus the workspace + resource tools below.

Workspace: the agent-native entry point

The three tools an agent needs to bootstrap and stay grounded in a repo:

• init_workspace({ repoUrl? | repoFullName?, teamId?, name? }) — create (or find) the Taskpod project for a git repository. The repo is the project's identity: calling it twice for the same repo returns the same project (created: false).
• sync_context({ projectId }) — returns a compact digest ready to inject into working context: project, active sprint + goal, task counts, active tasks by status with owners, recent learnings, and wiki page titles.
• record_learning({ projectId, kind?, title, content }) — write a learning | decision | convention | gotcha to the project's shared memory, so every human (taskpod sync) and agent (sync_context) sees it on their next pull.

Resource catalog

• list_project_resources({ projectId }) — list a project's repos, docs, BRDs, designs, consoles, dashboards, SOPs, and environments.
• add_project_resource({ projectId, type, label, url, description? }) — add a resource (type ∈ REPO|DOC|BRD|DESIGN|CLOUD|DASHBOARD|SOP|ENVIRONMENT|OTHER).
• remove_project_resource({ projectId, resourceId }) — remove one.

Agile planning: sprints, story points, custom fields, workflows & analytics

create_task and update_task now also take storyPoints (integer 0–100), sprintId, and workflowStatusId (a custom board column — setting it also syncs the task's canonical status), so an agent can estimate, schedule, and move cards on a customized board.

• Sprints — list_sprints({ projectId }) (with story-point rollups), create_sprint({ projectId, name, startsAt, endsAt, goal? }), update_sprint, close_sprint, and delete_sprint. Assign a task to a sprint with update_task({ sprintId }).
• Custom fields — list_custom_fields({ projectId }) reveals each field's id, type, and SELECT options; create_custom_field({ projectId, name, type, options? }) defines one (type ∈ TEXT|NUMBER|SELECT|DATE). Set a task's values with set_task_fields({ taskId, values: [{ fieldId, value }] }) (pass null to clear).
• Custom workflow — list_workflow_columns({ projectId }) lists the board columns (each column's id is the workflowStatusId to move a card to); create_workflow_column({ projectId, name, category, color?, isDefault? }) adds one.
• Flow analytics — get_project_metrics({ projectId, from?, to? }) returns cycle/lead-time percentiles, weekly throughput, and a cumulative flow diagram (defaults to the last 90 days).

Discover valid values first: call list_custom_fields before set_task_fields, and list_workflow_columns before setting a workflowStatusId.

Work platform: initiatives, docs & time

The tools an agent needs to plan against the roadmap, pull context out of the wiki, and log its own time. update_task also takes initiativeId to file a task under a cross-project initiative.

• Initiatives (roadmap) — list_initiatives({ teamId }) returns the team's initiatives with their linked project IDs and a task rollup; create_initiative({ teamId, name, status?, color?, startDate?, targetDate?, ownerId?, description? }) adds one (status ∈ PLANNED|ACTIVE|PAUSED|SHIPPED|CANCELLED). File a task under one with update_task({ initiativeId }) — the initiative must belong to the same team as the task's project.
• Docs / wiki — list_docs({ teamId, projectId? }) returns the page tree (titles only; omit projectId for the team-level wiki); get_doc({ docId }) reads a page's full markdown body; create_doc({ teamId, title?, projectId?, parentId?, icon? }) creates an empty page; update_doc({ docId, content?, title?, icon?, archived? }) writes it (any title/content change snapshots the prior revision).
• Time — log_time({ taskId, minutes, description? }) records a manual time entry against a task, which rolls up into the task's logged minutes and the owner's weekly timesheet.

Read before you write: list_docs to find a page ID, then get_doc for its content; list_initiatives to find an initiativeId before update_task.

Development

npm install
npm run build      # tsc → dist/
node dist/taskpod.js help

Publishing

Publishing is automated by GitHub Actions (.github/workflows/publish.yml): push a version tag and CI builds and publishes to npm.

npm version patch          # bumps package.json + creates a git tag
git push --follow-tags     # CI publishes the new version

One-time setup: add an npm automation token as the NPM_TOKEN repository secret (GitHub → Settings → Secrets and variables → Actions).

License

MIT