Providers and settings

Most Cocurdex configuration lives in the desktop app's Settings. This page covers the settings that change how agents and models behave — agent CLIs, providers, MCP, network, git, worktree environments, and devices.

Agent CLIs

Settings → Agent CLIs lists every agent you can pick when starting a session. For each one it shows the detected version and status (Built in, Ready, Not installed, Update required), a copyable install command, a docs link, and — for agents that report it — your plan usage. Add from ACP Registry installs more agents, or registers one with your own command. See Agents.

Run limits on the same page cap how many agent runs execute at once. Delegated runs (teammates and script-run subagents) past a limit wait in the queue; runs you start yourself are never held back.

Providers and models

Settings → Providers manages provider configs: named service endpoints with credentials and a model catalog. These configs feed the built-in Pi runtime and in-session model controls.

A provider config holds:

Templates fill the endpoint for common providers; Import JSON bulk-loads a provider definition. Manage everything in the UI, then verify from the CLI:

cocurdex provider list
cocurdex provider models <provider-id>

Provider configs and models are also scriptable: cocurdex provider add|update|login|key|model|default|import|export — see CLI.

External agent CLIs (claude, codex, opencode, and ACP Registry agents such as cursor-agent or grok) keep their own authentication — Codex account state under ~/.codex, for example. Provider configs do not replace that; they give Pi and the desktop a shared model catalog.

MCP servers

Settings → MCP configures the Model Context Protocol servers available to the built-in Pi agent. Pi connects to them when a session starts, through its built-in MCP support.

• Two editing modes: a form (name, transport, command/URL, arguments, environment) and raw JSON.
• The JSON shape is the standard mcpServers object.
• Transports: local stdio (command + args + env) and remote HTTP (url).
• Server names may contain only letters, digits, _, and -.
• Changes apply when a Pi session starts; running sessions keep their current tools.

Network proxy

Settings → Network controls the app's outbound proxy:

Scope notes:

• Applies to Agent subprocesses (including ACP), app and daemon model/API requests, and Chromium network traffic.
• Does not change the system proxy and does not force the integrated terminal to use these settings.
• Proxy URLs are stored as plain text in app settings and passed to Agent subprocesses — avoid embedding credentials you would not want a spawned CLI to read.
• Restart an active agent session after changing proxy settings so it picks up the new environment.

Test connectivity sends one request through the app's outbound path and reports the egress IP, so you can tell whether the proxy is really in use.

Git

Settings → Git picks the agent and model used to generate commit messages. When the commit message is left blank, the selected model writes a Conventional Commits subject from the staged changes. Choose None to always type messages yourself.

Worktree environments

Two layers:

• Settings → Worktrees: the root directory for managed worktrees (blank = default location) and whether to fetch remotes before creating a worktree. The inventory lists every checkout Cocurdex created, which sessions use it, and offers delete / new-session actions.
• Settings → Workspaces → Worktree settings: per-workspace setup and cleanup scripts plus actions. Setup runs in the background after Cocurdex creates a worktree (for example pnpm install), and the session's first turn waits for it; cleanup runs before an unused checkout is removed. Actions are named commands (for example Dev server → npm run dev) shown in the session's … menu, each running in a new terminal tab. Ask agent has an agent inspect the repository and propose both scripts for your approval.

The same surface is scriptable via cocurdex worktree settings — see CLI.

Devices

Settings → Devices opens the same host in a browser on this computer, or pairs another device with scoped permissions. See Devices and local web.

Settings assistant

The settings screen has an assistant dock: a chat session with the settings agent tools. Ask it to "switch to dark mode", "review my notifications", or "what can you change?" and it reads and edits the setting catalog for you — including project worktree setup and cleanup scripts. Changes that need your confirmation are proposed first.

Any main agent session can use the same tools; the optional /cocurdex-settings skill teaches agents to use them well.

App updates

Settings → About shows the installed version and Check for updates. Choose the Stable or Test update channel; Test builds can be unstable, and switching back to Stable may install an older version.

After an update downloads, an Update available card offers Update and Restart, Later, and View release notes. Automatic updates only work in the packaged app.

Diagnostics

Settings → Diagnostics (or Help → Export Diagnostics…) bundles sanitized app logs and runtime info into a file you can attach to a GitHub issue. Turn on Verbose diagnostics to record more detail while you reproduce a problem; logs stay sanitized either way.

Settings → General also shows the local daemon (socket, protocol version, start time) with Restart — use it if notes, issues, decks, or agents stop responding.

Other settings

Related

• Agents
• Devices and local web
• CLI
• Desktop workspace