@tinybottleai/pathfinder-cli

Authenticated command-line client and stdio MCP server for AI Pathfinder. Drive your Pathfinder runs from Claude Code, Codex, or any MCP-capable harness.

Install

npm install -g @tinybottleai/pathfinder-cli

Connect your account

pathfinder login

This opens your browser to sign in and authorize. The minted token is stored under ~/.pathfinder/ and can be revoked any time from your Pathfinder account Settings tab.

CLI commands

| Command | What it does | | --- | --- | | pathfinder login | Connect this machine to your Pathfinder account. | | pathfinder logout | Disconnect and delete the stored token. | | pathfinder sessions | List your Pathfinder runs. | | pathfinder show <id> | Show one run's summary and artifact handles. | | pathfinder mcp | Run the stdio MCP server (for an AI harness). |

MCP server

The package ships a stdio MCP server. Register it with your harness so the harness can read your Pathfinder runs in-session.

Claude Code:

claude mcp add pathfinder -- pathfinder mcp

For Codex or another harness, point its MCP config at the pathfinder mcp command.

The server exposes three read tools:

| Tool | What it returns | | --- | --- | | list_sessions | Concise summaries of your readable Pathfinder runs. | | get_session | One run's summary plus its artifact handles. | | get_artifact | One rendered artifact (Markdown) for a run. |

A team-scoped token's list_sessions returns the team's shared runs.

Environment

| Variable | Purpose | | --- | --- | | PATHFINDER_API_URL | Override the Pathfinder API origin (default: production). | | PATHFINDER_CONFIG_DIR | Override the credential directory (default: ~/.pathfinder). |

Notes

• The token is bearer-only and read-scoped. It does not bypass per-route authorization on the server.
• The stdio MCP server writes JSON-RPC to stdout and diagnostics to stderr.