Wire Pathmode Into Your Coding Agent

The repository agent drafts a feature from a ticket or brief. The product manager reviews that proposal in Pathmode, corrects its interpretation, and authorizes the revision to build. MCP carries the request, corrections, and review state between those two people’s working environments.

This guide covers the connection and the agent calls behind that workflow. For the product manager’s walkthrough, start with Your First Intent in Pathmode.

Two ways in: keyless and connected

• Keyless. With no API key configured the server runs in local mode: it reads and writes an intent.md in your repo, runs the deterministic preflight, and makes no network requests itself. No Pathmode account is needed. Your coding agent may still send context to its own model provider.
• Connected. A workspace connection adds tools for evidence with its trust tier, the constitution, the dependency graph, PM change requests, human authorization of the exact revision, and a merge that grades the real diff.

You can start locally and later adopt the file into a workspace. Connected mode also exposes workspace data; the repository-bound intent remains the implementation authority. The developer reference lists the current tools and which require a key.

In Claude Code, the plugin installs the server and the skill pack together:

/plugin marketplace add pathmodeio/claude-plugin
/plugin install pathmode@pathmode

No key needed. When you do want a workspace, enter the key when the plugin prompts for configuration; it goes into your OS keychain, not into a config file. Ran npx @pathmode/mcp-server setup before? Remove that older pathmode entry from .mcp.json, since the plugin registers its own.

For supported clients such as Cursor, Windsurf, Claude Desktop, or Claude Code without the plugin, the legacy setup command configures detected clients and credentials:

npx @pathmode/mcp-server@latest setup pm_live_...

This command does not upload or adopt an existing intent.md. For that, use the adoption steps below. Keep credentials out of version control.

For a client that uses JSON MCP configuration, this is a connected entry; drop env for keyless. Codex uses TOML configuration instead; see the Codex setup page.

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"],
      "env": { "PATHMODE_API_KEY": "pm_live_..." }
    }
  }
}

Use --local to force local mode when a key is configured.

Adopt an existing repository intent

Open repository setup, choose the workspace and Product, and copy the one-time command it provides:

npx @pathmode/mcp-server@latest adopt pm_adopt_...

Run the actual command from the project root containing the saved intent.md. The code is short-lived; obtain a fresh command if it expires. Adoption uploads the spec, adds its canonical cloud identity to the frontmatter, and binds that repository to the chosen workspace. The intent body remains the repository’s decision.

The non-secret binding is stored in .pathmode/config.json; the API key is stored separately in ~/.pathmode/workspaces/<workspace-id>@<origin>.json, one file per workspace and API origin. Follow the client connection instructions and restart the editor when required. Ask the agent to read the repository intent and verify that it resolves to the intended workspace before proceeding.

The tools below are grouped by job, not an exhaustive inventory. Consult /developers for current availability and argument schemas.

Two of these carry the workflow. check_intent_readiness is the agent's first move: it resolves the intent.md bound to the repository the client is working in, refuses to guess when it cannot identify the repository, and grades six gates with no model call. get_agent_prompt takes mode: draft (critique the spec) or mode: execute (implement it) and returns the 8-part IntentSpec with the constitution merged and the evidence grouped by trust tier. Before any instruction, it prints what decides whether the agent may proceed: the authorization state of this revision, open product choices, open PM change requests, the agent's own unaccepted proposals, and the latest advisory pre-merge review for each open pull request. While a product choice is open, execute mode returns the spec for review only and tells the agent not to implement.

For agents that read files instead of calling MCP, intent_export emits CLAUDE.md, AGENTS.md (OpenAI Codex and modern Cursor read it natively), .cursorrules, an outcome rubric, or OpenSpec from the repo's intent.md, with no key. export_context does the same for whole-workspace context in connected mode.

The plugin ships nine skills, a /preflight command, and a session hook. Skills auto-trigger from what you say; there is nothing to memorize. In rough lifecycle order:

The session hook adds one line to Claude's context when a repo has an intent.md: title, status, and how far the spec has drifted from the work. It reads the file and your git log locally and sends nothing anywhere.

The skills are the Claude Code layer. The server is the same for every MCP client. Not on the plugin? npx @pathmode/mcp-server install-skills copies the pack into .claude/skills/; if you later install the plugin, delete those copies, since the plugin's supersede them.

1. Preflight first. Before changing product code, the agent calls check_intent_readiness with no arguments. It resolves the repository's intent.md, or reports that there is none.
2. No intent.md yet: propose, save locally, stop. The agent reads the request and the relevant code, then drafts an intent for that request. Any consequential behavior the request leaves undecided becomes an open product choice: the question, a recommendation, the reason, the alternative, its cost, and what would reopen it. The claims that depend on a choice stay out of the required outcomes until someone answers it. The agent saves with intent_save and localDraft: true, reruns preflight, explains the open choices, and stops before writing code. A question asked in the terminal does not preserve the choice; the saved draft does.
3. Adopt the draft for team review. A workspace member opens repository setup and runs the adopt pm_adopt_... command from the project root, as in Step 1. Adoption carries the draft and its open choices into the workspace and establishes which repository owns the intent. An API key alone does not. If adoption is not available, keep the local draft and stop; do not create an unbound intent in the workspace instead.
4. Attach the original wording. Call attach_original_request with intentId, a recognizable title, the exact text, and an optional sourceUrl. Do not summarize or rewrite the text. It is stored as unreviewed context, not as backing for a claim. The reviewer can also use Attach the request in Pathmode. Then share the review link and stop.
5. Have the product manager review the interpretation. They compare the original request with the proposed behaviors, answer the product choices, and submit corrections. Choosing a recommendation prepares a correction; it does not authorize implementation.
6. Apply each answer and correction deliberately. Refresh the body with get_intent, read the request with get_intent_change_request, edit the spec, and call intent_save with both its exact changeRequestId and baseRepoBodyRevision. These arguments must travel together, and the apply should carry only that change: no new choices, no unrelated edits. If the body has changed or a save is refused, inspect the current request and reported reason instead of guessing a new base. Reject an unworkable correction with a concrete reason using reject_intent_change_request. A choice the product manager left undecided still blocks readiness after it is applied.
7. Return the revision for authorization. The product manager inspects the applied change and the whole proposal, then authorizes that revision. Pathmode refuses authorization while any product choice is open. Before building, call get_intent and check that authorization is authorized and authorizedRepoBodyRevision equals repoBodyRevision. Stop on open product choices, open corrections, or pending, rejected, or stale authorization. API keys cannot grant implementation authorization.
8. Implement and verify. For a passing preflight, use get_agent_prompt in execute mode and fetch the applicable constitution. Run the checks in the spec. If implementation contradicts a product assumption, record an implementation finding and propose a correction for human review; do not silently implement different behavior.
9. Link the pull request. With the GitHub integration configured, use a supported reference such as branch intent/<id> or pathmode:<id> in the PR body. verify_implementation can inspect the PR diff via prUrl. The merge workflow owns the shipped transition for linked PR work. Diff review is an additional signal alongside executed checks and observed outcomes.

For the illustrated FN-412 Cancel plan correction from immediate access loss to the end of the paid period, follow the proposal-review use case.

Three judgments that do not substitute for each other

The implement-intent skill enforces the distinction, and it is worth knowing before you rely on it:

• Preflight asks whether the spec is concrete enough to build and verify. Deterministic, repeatable, gate-able in CI.
• Accepted risk records a human decision to proceed while a named gap remains. Save that decision and rerun preflight, keeping the failing verdict visible. In connected mode, the implementation skill uses get_agent_prompt in draft mode for explicitly accepted blockers, then still requires authorization of the resulting revision.
• Authorization confirms that a person permits this exact agent-originated revision to be implemented. It does not make a failing gate pass, and a passing gate does not grant it.

Any body edit is a new revision, including the decision that records accepted blockers, and authorization is asked for again. That is the feature: the person who authorized knows precisely what they authorized.

Keep the handoff current

A copied prompt is a snapshot. Before continuing implementation, ask the agent to read the current repository intent and connected review state. New corrections and changed product decisions need attention even when an earlier revision was authorized.

For the fields in the spec, read The Anatomy of an Agent-Ready Spec. For returning contradictions from implementation, see When the Build Contradicts the Spec.

Common questions

Do I need a Pathmode account? No. Keyless local mode is the default: intent.md, the preflight, and the exports work with nothing configured. A workspace key adds evidence, the constitution, PM change requests, human authorization, and a merge that grades the diff.

Which agents does this work with? Any MCP client: Claude Code, Cursor, Windsurf, Claude Desktop. Agents that read instruction files, OpenAI Codex and modern Cursor, get an AGENTS.md from intent_export. The skill pack is Claude Code's layer.

Does it change how my agent writes code? No. It changes what the agent knows before it writes, and when it stops.

Who decides the agent may build? In connected mode, a signed-in person, by authorizing the exact revision. A passing preflight is not that decision, and neither is accepting blockers. In keyless mode the decision is yours, in the conversation.

Who moves the intent to shipped? The merge, when the branch or PR body names the intent. An agent that marks it shipped by hand replaces a diff-backed verdict with an unverified one.

Is verify-intent a tool or a skill? A skill. It designs the five-dimension verification loop and writes it into the spec. Grading a finished implementation is a separate step: the verify_implementation tool.

Start keyless: install the plugin, run /preflight on an intent.md, and hand the passing spec to your agent. Connect a workspace when the team needs evidence, the constitution, and authorization in the agent's context.