Agent tools

Reference for the surfaces an agent uses to interact with Constellation. The CLI reference covers every subcommand in detail; this page covers when to use which surface and the cross-cutting pieces (auth, env vars, the coordinator subagent) that don't fit on the per-subcommand pages.

pt CLI

A thin Node CLI that wraps the Project Tracker REST API. Designed for shell-based agents (Claude Code, Cursor, Codex, Aider) that don't have an MCP runtime — every operation is a one-shot subprocess call.

npx pt workspace                                # orient: current user, programme, top IN_PROGRESS
npx pt find-project apps/catalog/src/page.tsx   # resolve hint to project UUID
npx pt list-tasks INF --status IN_PROGRESS
npx pt update-task INF INF-31 --status DONE --progress 100 --json

Auth. Reads PT_BASE_URL and PT_AUTH_TOKEN (or PT_AUTH_COOKIE) from the environment. The .env.local autoload pattern from INF-29 makes the same secrets available to Claude Code, Codex CLI, Cursor, and Aider — set them once.

Output. Default is terse Markdown; pass --json for structured output. Use --json in agent loops where you need to parse the response.

Full subcommand list with stable per-command anchors: CLI reference. npx pt --help prints the same list locally.

constellation MCP server

The MCP server (tools/mcp-server/) exposes the same operations as the CLI, named in MCP-style snake_case (list_tasks, get_task, create_task, …). Two transports:

Transport	Use case	Setup
stdio	Claude Desktop, Claude Code, Cursor, Aider, generic stdio MCP hosts	Point the host at tools/mcp-server/ — see MCP server setup
Streamable HTTP	ChatGPT Custom Connectors, any host that speaks Streamable HTTP	Hosted at https://constellation-pt-mcp.vercel.app/api/mcp — Bearer-token auth, per-request rate-limited

Auth model. Same as the CLI — PT_AUTH_TOKEN for stdio, Bearer token in the Authorization header for HTTP.

ChatGPT Custom Connector specifics: Settings → Connectors → Advanced → Developer mode → Add custom MCP. URL is https://constellation-pt-mcp.vercel.app/api/mcp (the hosted MCP service is its own Vercel project, separate from PT_BASE_URL). See the MCP server setup page for the full ChatGPT walkthrough.

pt-coordinator subagent

A read-only Claude subagent dedicated to programme-wide planning. Defined at .claude/agents/pt-coordinator.md.

When to invoke it:

Question	Use the coordinator?
"What should I work on next?"	Yes
"Plan this week's work"	Yes
"What's blocked?"	Yes
"Is any of this duplicating something in flight?"	Yes
"Groom the backlog"	Yes
"Implement the fix for INF-31"	No — it can't write code; use the main agent or a general-purpose subagent
"Pick up INF-31 and ship it"	No — same reason

What it returns. A ranked recommendation with a clear decision point — typically a 1-line suggestion, the reasoning, and the next 1-2 alternatives. The coordinator orients via pt workspace, checks open PRs (gh pr list), reads the development plan, and reasons across all five projects in the dogfood programme.

What it can't do. Its tool allowlist explicitly omits Edit, Write, and NotebookEdit — physically cannot ship code. When it proposes work, you (or a future module-specific developer subagent) do the actual implementation. This separation is intentional: it keeps a clean read-only context window for cross-cutting decisions and prevents scope creep into "while I'm here, let me also fix this".

The full subagent definition (system prompt, tool allowlist, invocation guidance) is in .claude/agents/pt-coordinator.md.

CLI agents — Codex, Cursor, Aider

Other terminal / IDE agents work the same way as Claude Code:

• Auth. Read PT_AUTH_TOKEN from .env.local — the INF-29 setup covers them all.
• MCP. Each runtime has its own config file (.codexrc.toml for Codex, cursor-mcp.json for Cursor, similar for Aider). Each config points at tools/mcp-server/ for stdio, or the hosted HTTP endpoint for cloud agents.
• Pre-push gates. Same 4 gates run regardless of which agent prepared the PR — see overview.

The MCP server setup page has per-runtime config snippets.

Env-var checklist

The core variables every agent surface needs:

Variable	Read by	Value
PT_BASE_URL	pt CLI, MCP server (stdio)	https://constellation.planetb2b.com/projects in production
PT_AUTH_TOKEN	pt CLI, MCP server (stdio)	API key issued from Settings → API Keys in PT (or service-account JWT)
PT_AUTH_COOKIE	pt CLI (alternative to token)	Session cookie value — for local dev against a logged-in browser session

Local-dev secrets live in .env.local. The MCP server, the pt CLI, and Claude Code / Codex / Cursor / Aider all autoload them. Don't commit .env.local.

For the rest of the platform's env vars (DB URLs, Supabase keys, AI provider keys, Vercel multi-zone wiring), see Deployment.

See also

• Overview — ecosystem map + decision tree.
• Workflow — end-to-end worked example.
• CLI reference — every pt subcommand with a stable slug-anchor.
• MCP server setup — per-host config (Claude Desktop, Codex, Cursor, ChatGPT Custom Connector).