TeamFlow in Gemini CLI

1. Install

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

That writes:

• .agents/skills/<skill>/SKILL.md — the twelve skills, in the shared skills directory this tool reads
• GEMINI.md — a marked TeamFlow block; your own instructions are kept
• ~/.gemini/settings.json — the TeamFlow MCP server under httpUrl
• .teamflow/hooks/gemini.sh — the hook itself; it calls teamflow hook --for gemini, prints nothing the tool could read as a denial, and exits 0 whatever happens
• .gemini/settings.json — the hook registration: AfterTool and AfterAgent

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

3. Sign in once

/mcp auth teamflow

The browser opens on a loopback callback and the token is cached in ~/.gemini/mcp-oauth-tokens.json, refreshed automatically. /mcp on its own lists which servers still need authenticating.

4. By hand

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

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

Writing url here asks for an SSE connection this endpoint does not serve, and the failure looks like an unreachable server rather than a wrong key.

Leave any oauth block out: for a server that supports OAuth discovery, Gemini CLI finds the endpoints itself after the first 401.

Gemini CLI reads both .gemini/skills and the shared .agents/skills root, and ranks the shared one higher within the same tier. The installer writes the shared one, so a repository carries a single copy that six other tools also read.

GEMINI.md is hierarchical: ~/.gemini/GEMINI.md for every project, then the workspace file and its parents. If the team would rather keep one file for every tool, point context.fileName at AGENTS.md in settings and install for codex instead.

5. Uninstall

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

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

Gemini CLI reports automatically through its own hooks: AfterTool and AfterAgent. Nothing to remember. AfterTool fires on every finished tool call, which is everything TeamFlow needs; the hook stays silent because Gemini parses a hook’s stdout as JSON. Checked against the vendor’s own hook documentation on 2026-09-18: AfterTool carries tool_name, tool_input and tool_response over Claude Code's base fields, and stdout is still parsed as JSON, which is why the hook answers {}.

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.

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