TeamFlow in Cursor

1. Install

npx -y github:macleodlabs-ai/teamflow-plugin skills install --for cursor

That writes:

• .agents/skills/<skill>/SKILL.md — the twelve skills, in the shared skills directory this tool reads
• .cursor/rules/teamflow.mdc — the always-on reporting instruction, generated from the same SKILL.md sources
• .cursor/mcp.json — the TeamFlow MCP server
• .teamflow/hooks/cursor.sh — the hook itself; it calls teamflow hook --for cursor, prints nothing the tool could read as a denial, and exits 0 whatever happens
• .teamflow/hooks/cursor.ps1 — the same hook for a Windows developer; the config names it beside the shell one, so a repository shared between macOS and Windows reports from both
• .cursor/hooks.json — the hook registration: sessionStart, beforeSubmitPrompt, afterFileEdit, postToolUse, postToolUseFailure, afterShellExecution, subagentStart, subagentStop, preCompact, stop and sessionEnd

Add --scope user to install for every project on this machine, or --dry-run to see the file list without writing anything. Re-running it replaces TeamFlow's block and leaves the rest of each file alone.

Then sign this machine in, and check it. The hooks above report nothing at all until there is a credential, and nothing errors while they do not: an install that is never signed in looks exactly like a working one until somebody notices the board is empty.

npx -y github:macleodlabs-ai/teamflow-plugin login
npx -y github:macleodlabs-ai/teamflow-plugin status

login opens a browser once and stores a revocable refresh token; login --device prints a code to type into a browser on another machine instead. status answers with the organisation, the project and the repository this checkout reports to, and identity: not signed in there is the one thing to fix before expecting anything on the board.

2. What TeamFlow can do in Cursor

This list comes from Cursor's own documentation, checked 2026-10-04. We have not run Cursor with TeamFlow yet.

• Yes: Ticket, project and lead notes at session start.
• Yes: Plan goes on when a turn ends.
• Yes: Helper agents and session end on the board.
• Yes: TeamFlow skills.
• Yes: TeamFlow MCP server.
• No: Ticket, project and threads with each prompt. Cursor takes no added text when you send a prompt.
• No: Allow or Deny from TeamFlow. Cursor runs its hooks before every command, not only when it asks you. Waiting there would stop all work.
• No: One-minute check-in on an idle session. Cursor cannot wake an idle session later.

To add these to an earlier install, run npx -y github:macleodlabs-ai/teamflow-plugin hooks install --for cursor again. Every tool side by side.

3. The skills you get

The same twelve the Claude Code plugin carries, generated from the same SKILL.md files. This tool loads them as skills, one directory each, with the name prefixed so they do not collide with anybody else’s in a shared directory.

Each one wraps a github:macleodlabs-ai/teamflow-plugin subcommand, so the skill and the shell command are the same thing. Inside Claude Code they are /teamflow:login, /teamflow:status and so on.

4. Sign in once

Open Settings -> MCP (or Tools & Integrations on newer builds). teamflow appears with a Needs login control; clicking it opens the browser, and Cursor stores the token. The tools macleodlabs_teamflow_capabilities and macleodlabs_teamflow_call turn green when it is done.

Then, in the chat: "run teamflow status".

5. By hand

The installer writes this for you. If you would rather paste it: .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project.

{
  "mcpServers": {
    "teamflow": {
      "url": "https://codercat.io/mcp"
    }
  }
}

A remote server needs url and nothing else. type is for stdio servers, and no credential belongs in this file at all.

The rule has to be .mdc: Cursor ignores plain .md in that directory. The installer writes the frontmatter (alwaysApply: true) for you.

Cursor scans .cursor/skills as well as the shared root, so keep the skills in one place: a repository with both would show Cursor each skill twice.

The generated rule at cursor.mdc is a different thing: it teaches an agent how to call a paid MacleodLabs service and handle HTTP 402. The two sit side by side.

6. Uninstall

npx -y github:macleodlabs-ai/teamflow-plugin skills uninstall --for cursor

That removes exactly what the install above wrote: its own files go, and its own entries come out of the files it shares with your editor's other hooks and servers, which are left as they were. A hook TeamFlow did not write is never touched, and uninstalling something that is not there succeeds quietly. --dry-run prints the list without removing anything.

npx -y github:macleodlabs-ai/teamflow-plugin hooks uninstall --all is the bigger hammer: every tool at once, the git hooks, and this repository's ticket binding.

7. The stages to report

BACKLOG is the thirteenth: the ticket exists and nothing has started. Statuses are running, success, waiting, blocked, failed and idle. This is the same vocabulary the Claude Code plugin derives, so a ticket moved from here sits in the same column as one moved by Claude.

8. Without the agent

Anything that runs in a shell posts the same report with no model involved. A git hook, an npm script, a run configuration, a CI step:

npx -y github:macleodlabs-ai/teamflow-plugin report --issue DAEMON-142 --stage LOCAL_TEST \
  --status success --summary "42 tests, 0 failing"

Same envelope, same transport, same credential. Prefer it wherever the board has to be right whether or not an agent remembered. npx -y github:macleodlabs-ai/teamflow-plugin report --help lists every flag.

9. What this is not

Cursor reports automatically through its own hooks: sessionStart, beforeSubmitPrompt, afterFileEdit, postToolUse, postToolUseFailure, afterShellExecution, subagentStart, subagentStop, preCompact, stop and sessionEnd. Nothing to remember. Cursor has the fullest hook set outside Claude Code. A red test run reports rework, each session starts with its ticket, and a plan goes on to its next step by itself. Cursor documents command, output and duration for afterShellExecution and no exit status, so a shell command is classified only where Cursor does supply one; the definite signal is postToolUse and postToolUseFailure. Checked against the vendor’s own hook documentation on 2026-10-04: MACLEOD-972. Session context goes in sessionStart additional_context ("Additional context to add to the conversation's initial system context"), and a plan's next step in stop followup_message ("Can optionally auto-submit a follow-up user message to keep iterating"). No answers from TeamFlow: beforeShellExecution and beforeMCPExecution are "Called before any shell command or MCP tool is executed", not only when Cursor would ask, and preToolUse does not support "ask". beforeSubmitPrompt reads only continue and user_message, so a prompt gets no context. No idle, notification or question event exists, so there is no check-in wake-up and no shown question. subagentStop carries no subagent id, so an agent is keyed by its task. afterShellExecution has no exit status, so shell commands report through postToolUse and postToolUseFailure.

The hooks see this tool's own calls and nothing else. A test run in another terminal, a merge from the web UI, a deploy from a pipeline: put npx -y github:macleodlabs-ai/teamflow-plugin report in the git hook or the script that already runs on every change, and those land on the board too.

10. What leaves your machine

TeamFlow manages your AI software factory. It is run by MacleodLabs. Your code stays inside your organisation: the local plugin sends derived state only, a ticket key, a stage, a status, a short summary and evidence links. Prompts, diffs, source code, commands and logs are never sent and are rejected before they are charged.

• Every client
• llms.txt
• Capabilities
• The reporting contract, in full