TeamFlow in Claude Desktop

1. Install

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

That writes:

• .teamflow/claude-desktop-instructions.md — the rules document, for you to paste into Project instructions

Then, by hand, because this part is UI:

1. Settings -> Connectors -> Add -> Add custom connector -> https://codercat.io/mcp
2. Create a Project for this codebase and paste the rules document into its Project instructions.

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. The skills you get

The same twelve the Claude Code plugin carries, generated from the same SKILL.md files. This tool has no skill loader, so they arrive as sections of the rules file the installer writes rather than as files nothing would read; ask for one by name and the agent runs its command.

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.

3. Sign in once

An authorization screen appears as soon as the connector is added and hands off to the browser. Afterwards, open the connector to choose which of its three tools Claude may call without asking.

4. Adding it by hand

1. Settings -> Connectors -> Add -> Add custom connector.
2. Paste https://codercat.io/mcp.
3. Add.

On Team or Enterprise the same thing lives under Organization settings -> Connectors, and adding it there gives it to everyone at once.

Claude reaches a remote connector from Anthropic's own infrastructure rather than from your laptop, so the endpoint has to be publicly reachable. codercat.io is.

If you specifically need it in the local config file, bridge it over stdio:

{
  "mcpServers": {
    "teamflow": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://codercat.io/mcp"]
    }
  }
}

That is the community pattern rather than a documented one. The Connectors route is the supported path.

Claude Desktop has no skills directory on disk. Its custom skills are packaged as a ZIP and uploaded under Customize -> Skills, which needs code execution enabled in Settings. The installer does not try to automate that.

Note also that ~/.claude/skills is a real path but it belongs to Claude Code, not Claude Desktop. Writing there does nothing for this client.

Claude Desktop is a chat window, not a coding agent with a checkout. It will report the stage you tell it about, and it cannot observe a test run it did not perform. For a repository where work actually happens, Claude Code reports the same stages automatically and instructs nobody.

5. Uninstall

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

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.

6. 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.

7. 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.

8. What this is not

Claude Desktop has no hooks, so the agent reports because its rules file tells it to; a git hook keeps the board complete when it forgets. The chat side runs no local command and has no hooks; the Code tab is Claude Code and is covered by installing the plugin there. Checked against the vendor’s own hook documentation on 2026-09-18: No local command runs on the chat side, so there is nothing to hook and nothing to verify.

Which usually happens and sometimes does not. For a board that has to be complete, put npx -y github:macleodlabs-ai/teamflow-plugin report in the git hook or the test script that already runs on every change, where no model has to remember it.

9. 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