Connect an AI client
Choose the setup that matches what you want:
- Quick browser handoff: run
centaur send, paste the prepared hand-off into the chosen chat, copy the complete reply, and runcentauragain. See Getting Started. - Direct connection: zero-copy after setup. The AI calls Centaur to read context, apply an approved change, and undo.
Centaur provides two client integrations:
- MCP tools let a client read context, prepare a tracked handoff, review a returned patch, apply the approved plan, and undo against one fixed workspace.
- Commands and skills teach a compatible client how to run the Centaur workflow.
| Client Type | MCP | Skill | Notes |
|---|---|---|---|
| Codex desktop/CLI | Yes | Yes | Project-scoped config in trusted projects |
| Claude Code | Yes | Yes | Private local scope for the current project |
| Claude Desktop | Yes | Yes | Use MCP for best integration |
| ChatGPT Web/Desktop | Yes (Tunnel) | Yes | Web requires tunnel, desktop works via skill |
| Gemini Web/CLI | Yes (Tunnel) | Yes | Web requires tunnel, CLI via MCP |
| Cursor | Yes | Yes | Setup MCP natively |
| Windsurf | Yes | Yes | Setup MCP natively |
| Antigravity | Yes | Yes | - |
For existing datasets, the export_data MCP tool takes explicit workspace-relative paths, an optional analysis task, and optional text redact. It creates the same native files and manifest as centaur data and returns their local folder plus the prompt. This still requires attaching files to a remote chat: a local folder path in a tool result does not grant ChatGPT access to its contents. Restart an updated client/server to discover the new tool; no download endpoint is added.
Configure supported clients
Section titled “Configure supported clients”Run this inside the project the client should use:
centaur installRestart each client after setup. Codex and Claude Code bind the entry to the current project, so installing another repository does not repoint this one.
When installation finishes, Centaur states which route still uses copying and links to the extra ChatGPT web setup.
Use centaur doctor to verify the server handshake and that each configured entry points at this workspace. The final GUI discovery check remains inside the restarted client. Use centaur doctor --redact-paths before sharing the result.
To connect one client, install it explicitly:
centaur install --client codexcentaur install --client claude-codeBuilt-in targets
Section titled “Built-in targets”The combined installer configures every supported target. For one integration, use the lower-level installer and its exact ID.
MCP configurations
Section titled “MCP configurations”claude-desktop: updates the platform Claude Desktop configuration.claude-code: writes Claude Code’s private local-scope entry for this project in~/.claude.json.claudeis an alias.antigravity: updates~/.gemini/antigravity/mcp_config.json.antigravity-ide: updates~/.gemini/antigravity-ide/mcp_config.json.cursor: updates~/.cursor/mcp.json.windsurf: updates the Windsurf MCP configuration.gemini-cli: updates~/.gemini/settings.json.vscode: updates this project’s.vscode/mcp.json.codex: updates this project’s.codex/config.tomlwhile preserving unrelated settings and comments. Codex loads it only after the project is trusted.
centaur mcp install --client claude-codecentaur mcp install --client codexCommands and skills
Section titled “Commands and skills”antigravity: Antigravity.claude-code: Claude Code.claudeandclaude-desktopare aliases for the shared Claude skill location.codex: Codex clients that read~/.agents/skillsand the workspace skill.chatgpt: ChatGPT prompt files.agents: clients that read~/.agents/skills.cursor: Cursor.windsurf: Windsurf.
centaur skill install --client claude-codecentaur skill install --client codexFor an unlisted client, provide its MCP configuration file or command destination directly:
centaur mcp install --config path/to/mcp.jsoncentaur skill install --output path/to/centaur.mdProfile a live database
Section titled “Profile a live database”The terminal, More tools menu, and MCP all use the same profiler. Set the connection string in the environment, then run:
centaur db profile --engine postgres --redactcentaur db profile --engine mongo --sample 500 --format json --redactMCP clients call profile_database with the same engine (postgres, supabase, or mongo), optional url_env, optional Mongo sample, and optional redact values.
It returns aggregates, never rows. Tables and collections, columns and types, null rates, distinct counts, and the common values of low-cardinality columns. No record leaves the database, so the profile can go into a chat that the data itself must never enter.
Centaur does not store a connection string and does not connect on its own. It reads the URL from an environment variable at call time and runs the client you already have - psql or mongosh - which is where your credentials already live. If the variable is unset, the call fails and tells you so.
Cost differs by engine:
- Postgres and Supabase scan nothing.
ANALYZEalready stores per-column null fractions, distinct counts, and most-common values inpg_stats, so Centaur reads the catalog. The numbers cover every row, and a table Postgres has never analysed is reported as such rather than guessed at. Thesampleoption is ignored here. - Mongo has no such catalog - the shape only exists in the documents - so it samples
sampledocuments per collection (default 200) and reports how often each key appears. That sample size is the cost dial.
Common values are emitted only for columns with 50 or fewer distinct values. Those are enums and flags; the top values of an email or token column are live user data, and the gate is what keeps them out. The report is scanned for credentials on the way back, and redact: true masks anything found.
ChatGPT on the web
Section titled “ChatGPT on the web”For a direct tool connection instead of the file-and-clipboard workflow, use OpenAI Secure MCP Tunnel with Centaur’s existing stdio server:
centaur mcp serve --workspace /absolute/path/to/projectThe tunnel is outbound-only, so Centaur does not need a public listener. It requires OpenAI tunnel access and ChatGPT developer-mode access; the ordinary browser workflow above does not.
Remote web connectors
Section titled “Remote web connectors”Claude custom connectors, Gemini custom apps, and other remote MCP clients need an HTTPS endpoint. Start Centaur’s authenticated Streamable HTTP transport locally:
# macOS and Linuxexport CENTAUR_MCP_TOKEN="a-random-secret-with-at-least-32-characters"centaur mcp serve --workspace /absolute/path/to/project --http 127.0.0.1:3765# Windows (PowerShell)$env:CENTAUR_MCP_TOKEN = "a-random-secret-with-at-least-32-characters"centaur mcp serve --workspace C:\absolute\path\to\project --http 127.0.0.1:3765Keep your
CENTAUR_MCP_TOKENsecret and never commit it to source control. Treat it like a password to your local filesystem.
Put an OAuth-capable HTTPS tunnel or reverse proxy in front of http://127.0.0.1:3765/mcp. Configure it to forward Authorization: Bearer <CENTAUR_MCP_TOKEN>, then add the public HTTPS /mcp URL to the web client.
Centaur refuses non-loopback HTTP bindings, missing or incorrect bearer tokens, and unexpected browser Origin headers.
If a trusted proxy adds an Origin header, allow the exact value:
centaur mcp serve --workspace <path> --http 127.0.0.1:3765 --allow-origin <exact-origin>Repeat --allow-origin for each trusted value.
The HTTP server intentionally does not implement TLS or OAuth. Those internet-facing controls belong at the tunnel or reverse proxy.
VS Code
Section titled “VS Code”The extension in editors/vscode/ provides these commands:
- Centaur: Start an AI Task
- Centaur: Apply AI Update
- Centaur: Check Project
- Centaur: Undo Last Change
- Centaur: Export Context for AI
The extension requires the centaur executable on PATH. Download https://getcentaur.pages.dev/downloads/centaur-vscode.vsix, then use Extensions: Install from VSIX in VS Code.
After Start an AI Task, choose ChatGPT, Claude, Gemini, Qwen, Kimi, or DeepSeek in the popup. Centaur opens that chat, copies the prompt, and opens the context folder. You still choose the files and press Send in the browser.
What the model can do
Section titled “What the model can do”Development builds include an agent job workflow. delegate takes an objective,
optional paths and budget_tokens, and output (findings, review, patch, or research).
It returns a compact receipt with a durable job_id; the default prepares locally.
Set dispatch: true only for an authorized send. Execution requires Windows and
runs in a separate process so the MCP connection can close while it works.
Research defaults to runner: "desktop", using the configured normal browser
and, by default, a review/send step in the companion’s project window. Opt-in
companion.send_mode: "automatic" skips that confirmation for an authorized
dispatched desktop job. Preparation with dispatch: false remains local. A
small native confirmation is the review-mode fallback when the companion
executable is missing. The
desktop route implements ChatGPT, Claude, Gemini, and Qwen. The zero-file
ChatGPT native round trip is verified. Gemini’s native check stopped before
submission; a separate coordinator browser test succeeded and reported
nativeSent: false. Native verification for Claude, Gemini, and Qwen remains
pending. Other
outputs default to runner: "own_profile", which requires ChatGPT signed in
through centaur browser signin. Supply runner: "desktop" to use the normal
browser for those outputs. Kimi, DeepSeek, and custom websites remain
preparation-only for agent dispatch; local Ollama keeps its existing route.
Public installers may not include these development changes yet.
{"objective":"Review parser.rs for empty-input handling","paths":["parser.rs"],"budget_tokens":8000,"output":"findings","dispatch":true}Retrieve the outcome with get_job({"job_id":"FULL_JOB_ID","wait_ms":30000}).
Continue bounded waits until capture or needs_attention when an automatic
return was requested. Research returns a generated summary, sources, and
limitations; these remain model claims. Inspect status,
next_action, and source freshness. Prepared context is not evidence of sending;
an uncertain send must not be retried automatically. Results are compact by
default; request include_text: true only when needed. Returned patches go through
validation and review, never automatic application. Existing save_task_result
can capture a manually returned answer against the same job ID.
Before exporting, compare the workspace returned by get_settings with the
intended project. MCP does not switch projects when a different chat opens.
Destination, browser, context budget, and research defaults are shared with the
desktop Settings window. update_settings changes only supplied future defaults;
research_options on delegate overrides one task without changing them.
Companion sending and display preferences are shared too. For example,
update_settings with {"companion":{"send_mode":"automatic","show_progress":false}}
opts future authorized desktop dispatches into sending without Enter and hides
their progress. get_settings exposes both settings.companion and
factory_defaults.companion. Each prepared job snapshots these preferences;
changing defaults does not alter an existing job. Automatic mode can still
focus the browser and require sign-in or website verification. It does not
auto-apply patches or retry failed or uncertain sends. A task typed into the
companion still requires context review and Run.
budget_tokens gates the estimated complete outgoing prompt. Automatic dispatch
stops if required context and instructions exceed it; prepare-only mode reports
the estimate. .centaur/jobs/ holds local job records, prompts, and failed raw
captures. Exclude it from version control. A failed raw capture can be retrieved
explicitly with include_text: true, but is not a validated result.
An MCP client can read the configured workspace, prepare a tracked handoff, preview the exact returned diff, apply that workspace-bound plan after approval, and revert a Centaur session. It cannot choose a different workspace through a tool argument.
prepare_handoff stores the destination, expected response type, repository revision, and file fingerprints. It does not open a browser, touch the clipboard, or send code. If Centaur detects possible credentials, preparation stops until the caller requests redaction. A GUI can call get_pending_review to read the newest browser-captured plan for this workspace. Pass the returned handoff_id to preview_patch, show the diff to the user, then pass the reviewed plan_id to apply_patch only after approval. A changed source file or different workspace invalidates the plan.
Clients with global configuration still need a separate named entry for a second project:
centaur mcp install --client cursor --workspace ~/code/api --name centaur-apiRead Safety and recovery before exposing a connector beyond the local machine. See Edge cases for pagination, proxy origins, and multiple workspaces.