Paseo API Bridge

Expose Paseo features to ChatGPT and other MCP clients. Runs on Linux or macOS. An independent integration for Paseo, not a replacement daemon or an official Paseo/OpenAI product.

The installation default remains read-only. Owners can opt into separate control and administration scopes. Each person brings their own daemon, tunnel and OAuth identity. Open-source code does not share anyone's projects. Project instructions own architecture, orchestration and cross-chat context; this plugin supplies raw operations, schemas and results.

ChatGPT → OpenAI outbound tunnel → OAuth-protected bridge → local Paseo daemon
                                      ↓
                              private SQLite events

Put everything on a headless Linux machine to use ChatGPT from a phone or browser with your Mac turned off. Alternatively run the bridge on your Mac, using a local daemon or a private SSH forward to a remote daemon.

What you can ask

• “List my current Claude and Codex sessions.”

• “What changed in this project since the last update?”

• “Review the changes, explain architectural impact, and suggest the next task.”

The original five evidence tools remain: paseo_status, paseo_agents, paseo_updates, paseo_context, paseo_diff. Updates include provider, project/repository, session/command, outcome, file status, bounded diffs or statistics, reported tests/errors and timestamps where the provider supplies them. The included technical skill explains tool use; it does not assign an architect role or maintain project policy.

Related MCP server: chatgpt-local-mcp-bridge

Raw API tools

paseo_api discovers 174 allowlisted JSON-callable SDK operations and gives each operation's named parameters and schemas. Call paseo_read_request, paseo_control_request or paseo_admin_request with those parameters. paseo_result retrieves saved request results and bounded pages of large output. See API coverage for every mapped operation and exclusion.

Scopes:

• paseo:read: inspection, timelines, providers, workspaces, terminal captures and repository/file reads.

• paseo:control: sessions/tasks/permissions, terminals, file/Git changes, workspaces, scripts and schedules. These can execute real code and alter work.

• paseo:admin: daemon configuration, plugins/skills, hub/pairing access, diagnostics, restart, shutdown and updates. These can expose sensitive configuration or affect daemon security and availability.

To enable additional groups, set PASEO_ACCESS=read,control,admin in private configuration and add matching OAuth permissions to the API/client. Read tokens never authorize a control/admin call. Local stdio honors the configured access groups without OAuth; its host is trusted.

Every mutation requires an idempotencyKey. Replaying a key with identical parameters returns its recorded state without execution; different parameters are rejected. Pending/indeterminate results must be inspected, not blindly reissued with a new key. These records persist across process restarts. An RPC acknowledgement is not agent task completion. Read the session/timeline or terminal afterwards. All arguments/results may contain private information and remain in the owner-only database; no retention is automatic.

Example after inspecting the createAgent schema:

{
  "operation": "createAgent",
  "parameters": {"options": {"provider": "codex", "cwd": "/your/project", "title": "Your task"}},
  "idempotencyKey": "your-unique-create-request-001"
}

Native persistent callback/subscription transports are documented as exclusions. Audio/browser-related JSON operations do not create a native audio/browser UI. The daemon/provider may report unsupported capabilities; the bridge returns the actual outcome. This release maps APIs, not a universal verified guarantee for every operation.

Install

Requires Node.js 22.13+, npm, an existing Paseo daemon (verified against 0.10.3), and unzip for the optional tunnel download helper. The bridge has no model/API inference cost of its own. ChatGPT, OAuth and tunnel providers have their own eligibility and pricing; this package does not provision accounts.

git clone https://github.com/Ramidoz/paseo-architect-bridge.git
cd paseo-architect-bridge
npm ci
npm test
npm run build
npm run tunnel
mkdir -p ~/.config/paseo-architect
cp bridge.env.example ~/.config/paseo-architect/bridge.env
chmod 600 ~/.config/paseo-architect/bridge.env

Edit that private configuration with your own identifiers and runtime key. Never commit it. Follow OAuth and ChatGPT setup before starting. The official tunnel binary is downloaded from OpenAI's GitHub release and checked against a pinned SHA-256 digest; it is not redistributed inside this project's package.

For Paseo on the same machine use ws://127.0.0.1:6767/ws. For a remote daemon, use a private forward (and keep it alive) or a correctly authenticated wss:// endpoint. Plain ws:// outside loopback is rejected by the service CLI.

node cli/index.mjs probe --config ~/.config/paseo-architect/bridge.env
node cli/index.mjs run --config ~/.config/paseo-architect/bridge.env \
  --tunnel-bin ~/.local/bin/tunnel-client

probe reads the daemon without starting a tunnel. run supervises the bridge and tunnel together; if either exits, both stop so the OS can restart them. The bridge listens on loopback 18767; operator health/UI on loopback 18768. Do not publish these ports. Stop an old runtime before starting another for the same tunnel. No Mac/SSH hop is needed when the daemon and bridge share Linux.

Start automatically on Linux

node cli/index.mjs install --config ~/.config/paseo-architect/bridge.env \
  --tunnel-bin ~/.local/bin/tunnel-client --start
systemctl --user status paseo-architect-bridge.service
# Administrator step: start at boot even before you log in
sudo loginctl enable-linger "$USER"

The user service restarts on failure. Your Paseo daemon also needs its own boot service. Read operations and migration.

Start automatically on macOS

node cli/index.mjs install --config ~/.config/paseo-architect/bridge.env \
  --tunnel-bin ~/.local/bin/tunnel-client --start
launchctl print gui/$(id -u)/com.paseo.architect-bridge

This installs a per-user LaunchAgent. It starts after login and restarts on failure; the Mac must remain awake. It does not turn a sleeping/off Mac into a server or automatically manage your SSH forward. See operations for restart, logs and uninstall. Add --dry-run to review a service definition without installing it; omit --start to install without starting now.

Local desktop MCP without a cloud tunnel

Use mcp.json / .mcp.json, or launch node server/dist/bridge.mjs as a stdio MCP server in your trusted desktop host. Set PASEO_URL as needed. Stdio does not require OAuth; never put an unauthenticated web proxy in front of it. Plugin hosts can load plugin.json and skills/paseo-tools/SKILL.md.

Limits and privacy

• Only Paseo-managed sessions and shared repository state are captured. This is not a universal monitor of unrelated CLI processes.

• Shared checkout changes have unknown CLI attribution. Agent edit events give provider evidence but cannot prove exclusive file ownership.

• First connection reads the latest 100 timeline entries per session. Cursors catch up incrementally and gaps are reported; it is not a full historical import. Very old lifecycle revisions can be missed.

• File snapshots cover uncommitted diffs; ignored files and commit-only transitions are not fully captured. Tests are agent-reported, not rerun.

• Polling defaults to 30 seconds. Tools pull updates; no automatic unsolicited chat notifications or scheduled architect agent is included.

• SQLite uses owner-only file permissions and persists across restarts. Data is not automatically pruned. Secret redaction is best effort; review sensitive projects before connecting them to ChatGPT.

• OAuth pins a linked service identity, not a specific ChatGPT account.

The checkout API uses a pinned internal Paseo adapter. Reverify it when upgrading the SDK. See security and contributing.

Packaging

npm pack creates a portable package with source, bundled server, skill, documentation and dependency notices. Runtime credentials, captured events, node_modules and machine-specific service files are excluded by the package allowlist. GitHub source/releases are independent of npm registry publication. The integration code is MIT; dependencies retain their licenses. A GitHub Actions test template is included at docs/ci/verify.yml. To enable it, copy it to .github/workflows/verify.yml using a GitHub credential with workflow permission.