Getting started

Install Cocurdex, open a workspace, configure an agent runtime, and run your first session.

This guide gets you from install to a useful first agent session.

Requirements

Item	Notes
macOS	Apple silicon and Intel
Windows	x64 (unsigned NSIS installer)
Linux	x64 AppImage or `.deb`
Agent runtime	At least one supported agent CLI or provider you already use (see Agents)
Disk / project	A project directory on disk that agents and the editor can use as the workspace root

Install

Public builds

Download the build for your platform from the Download page.
Install and open Cocurdex.
On first launch, the Welcome to cocurdex screen shows what's available on this machine. Open a folder to start with a workspace—agents run inside the folder you choose. The built-in Pi agent needs a provider; other agent CLIs bring their own. The screen also offers Configure a model provider, Skip, and Don't show this again.

CLI on your PATH

After install, open Settings → General → Shell command and click Install so the cocurdex launcher is available in the terminal.

cocurdex --version
cocurdex --help

If the binary cannot find the desktop app, open Cocurdex once from the Dock/Applications, or set COCURDEX_ELECTRON to the app executable. See CLI.

Open a workspace

A workspace is the project context Cocurdex attaches to — typically a directory on disk.

From the desktop app

Open Cocurdex.
Open or create a workspace pointed at your project root.
Confirm the shell shows sessions/chat alongside terminal and editor peers.

From the terminal (VS Code-style)

# Open the app
cocurdex

# Open a folder as the workspace
cocurdex .
cocurdex open /path/to/project

List known workspaces:

cocurdex workspace list

Prepare an agent

Before the first useful run:

Install the agent CLI you want — claude, codex, or opencode — or add an agent such as Cursor, Devin, or Grok Build from Settings → Agent CLIs → Add from ACP Registry. If cursor-agent, devin, or grok is already on your PATH, Cocurdex picks it up automatically. You can also use the built-in Pi (pi) runtime with a provider config when you only need chat-style work without native write.
Complete that tool’s own auth (API key, ChatGPT login, etc.). Cocurdex prefers reusing your existing provider setup where possible.
In the desktop app, create a session and pick agent + provider + model.

Supported agent ids and permission modes are documented on Agents.

Check provider configs from the CLI (daemon must be running — opening the desktop app starts it):

cocurdex provider list
cocurdex provider models <provider-id>

First session (desktop)

Start a new session from the desktop shell.
Choose an agent runtime and model you already authorize. Tick Worktree if the session should work in an isolated checkout.
Keep terminal and editor available — agent work often spans more than the chat stream.
Send a small, concrete task first (for example “list the top-level layout and summarize entry points”).
Watch session status:
- Working / thinking / using tools — agent is busy
- Pending approval / awaiting input — you need to act
- Ready / completed — review the result, then continue or start another session

Prefer narrow permission modes until you trust the task. Elevated or “full access” modes exist for power use; they are intentionally high risk.

First session (CLI TUI)

With the daemon available (desktop open or daemon reachable):

cocurdex session tui \
  --workspace /path/to/project \
  --agent codex \
  --provider <provider-id> \
  --model <model-id>

Or create a session, then send messages:

cocurdex session create \
  --workspace /path/to/project \
  --agent codex \
  --provider <provider-id> \
  --model <model-id>

cocurdex session list
cocurdex session send <session-id> "Summarize the repo structure"
cocurdex session stop <session-id>

Product data in five minutes

Notes, issues, and slide decks are app-owned, not a second Markdown tree in your repo:

cocurdex note create --title "Kickoff notes" --body "Goals for this week"
cocurdex issue create --title "Ship getting-started docs" --status backlog
cocurdex search "getting-started"

Slide decks are the same kind of record. See Slide decks.

Details: Notes and issues and Workspaces and data.

Optional: product skills

Install namespaced product skills so agents can run /cocurdex-* flows (note → issue → ship, and /cocurdex-deck for slide decks) against the same data plane:

cocurdex skills list
cocurdex skills install --scope project
# or
cocurdex skills install --scope global

See Skills.

Troubleshooting

Symptom	Try
An agent shows as unavailable	Install and log in to its CLI, then check Settings → Agent CLIs (it also flags versions that need an update)
An agent says it needs you to sign in	Choose Sign in to … from the composer's model menu, then send again
CLI data commands fail	Open the desktop app so the daemon starts; `cocurdex daemon status`
Notes, issues, or agents stop responding	Settings → General → Restart the daemon
A browser asks to pair	On the computer running Cocurdex, open Settings → Devices, create a pairing code, then open its link or enter the code. See Devices and local web
The phone lists computers but not sessions	Open the Sessions tab. The list is for the computer named in the toolbar. See Devices and local web
Anything else	Help → Export Diagnostics… and attach the file to a GitHub issue, or ask on Discord

Checklist

App opens and a workspace points at the right project root
At least one agent runtime is installed/authenticated
You can create a session and see honest status while it runs
cocurdex --help works from a terminal
You know where notes, issues, and decks live (app-owned storage, not ad-hoc repo files)

Desktop workspace — panes, attention, shortcuts
Devices and local web — browser client, paired devices, and Sessions on the phone app
Agents — runtimes, permissions, plan mode
CLI — full command surface
Teams and orchestration — agent teams and script runs