Agent Integrations

Caplets works with Codex, Claude, OpenCode, Pi, and other MCP clients. Code Mode is the default surface for configured capabilities.

Local setup is daemon-first: caplets setup initializes user Caplets config, installs or starts the local Caplets daemon, verifies daemon health, and then configures the selected agent as a thin caplets attach <local-daemon-url> or native client. This solves the environment passthrough problem in clients that do not launch MCP servers with the same shell environment as your terminal; backend execution happens in the Caplets daemon.

Codex

Run setup:

caplets setup codex

Equivalent daemon-backed local MCP config:

[mcp_servers.caplets]
command = "caplets"
args = ["attach", "<local-daemon-url>"]

Claude

Run setup:

caplets setup claude-code

Manual setup should still point Claude at the daemon-backed attach client:

claude mcp add --transport stdio --scope user caplets -- caplets attach http://127.0.0.1:5387/

OpenCode

OpenCode can use Caplets through MCP or the native OpenCode integration. Native mode exposes caplets__code_mode for Code Mode, plus progressive or direct tools only when configured.

caplets setup opencode

Local setup installs the native plugin and writes non-secret daemon defaults. Explicit OpenCode plugin config still wins over those defaults.

Native integrations use the shared anonymous telemetry controls and do not send telemetry on a native-first run until a visible CLI telemetry notice has already been recorded.

Remote native usage:

caplets remote login https://caplets.example.com
CAPLETS_MODE=remote CAPLETS_REMOTE_URL=https://caplets.example.com opencode

Pi

Pi can use Caplets through MCP or the native Pi integration. Native mode uses the same local, daemon, and generic remote selection rules as OpenCode.

caplets setup pi

Local setup installs the Pi extension and writes non-secret daemon defaults. Explicit Pi settings still win over those defaults.

Native integrations use the shared anonymous telemetry controls and do not send telemetry on a native-first run until a visible CLI telemetry notice has already been recorded.

Native runtime selection

OpenCode and Pi accept shared runtime selectors through integration settings or environment:

Mode	Selection
auto	Use a configured generic remote, otherwise a setup-written daemon when present, then local.
local	Run Caplets in the agent process with user and project config.
daemon	Use the loopback runtime selected by the origin-only CAPLETS_DAEMON_URL.
remote	Use the saved generic Remote Profile selected by the origin-only CAPLETS_REMOTE_URL.

Generic Current Host and loopback daemon sessions that provide a project root can open Project Binding when the host advertises support. Required project Caplets remain hidden until a managed binding is ready.

Remote native usage:

caplets remote login https://caplets.example.com
CAPLETS_MODE=remote CAPLETS_REMOTE_URL=https://caplets.example.com pi

Other MCP clients

Use the add-mcp client catalog through Caplets setup:

caplets setup mcp-client --client <client-id>

If you write config manually, keep the agent as a thin daemon client:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach", "<local-daemon-url>"]
    }
  }
}

For remote-backed MCP, use caplets attach <current-host-origin> after caplets remote login <current-host-origin>. The value must contain only scheme, host, and optional port; non-root paths, queries, fragments, and embedded credentials are rejected. Agent configs should not contain Caplets remote tokens, passwords, or provider environment variables.

As an advanced alternative, caplets serve can run a foreground HTTP or stdio runtime. If you want one local HTTP runtime to own environment, Vault, Remote Login, dashboard access, reloads, and logs while composing an upstream Current Host, run:

caplets serve --transport http --upstream-url https://caplets.example.com

Then configure the MCP client with caplets attach <local-runtime-url>. If you also need host administration, open the same runtime’s /dashboard path in a browser and complete an Operator approval there.

Use the CLI reference for the complete command-family map and Privacy and network activity for the independent native telemetry, update-check, and catalog-indexing controls.