Skip to content
CocurdexCocurdex Docs

Getting started

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

Requirements

Section titled “Requirements”
Item Notes
macOS Primary supported platform during pre-release (Apple silicon first)
Windows / Linux Coming after macOS stabilizes
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

Section titled “Install”

Public builds

Section titled “Public builds”
  1. When public artifacts are published, download from the Download page.
  2. Install and open Cocurdex.
  3. Complete any first-run prompts (theme, CLI launcher, permissions as offered).

Until public installers are linked, use a local or CI-built package from the monorepo (apps/desktop), or run the desktop app from a development checkout.

CLI on your PATH

Section titled “CLI on your PATH”

After install, open Settings → CLI (or the equivalent first-run step) so the cocurdex launcher is available in the terminal.

Terminal window
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

Section titled “Open a workspace”

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

From the desktop app

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

From the terminal (VS Code-style)

Terminal window
# Open the app
cocurdex


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

List known workspaces:

Terminal window
cocurdex workspace list

Prepare an agent

Section titled “Prepare an agent”

Before the first useful run:

  1. Install the agent CLI you want (for example claude, codex, opencode, or grok), or use the built-in Cocurdex (pi) runtime when you only need chat-style work without native write.
  2. Complete that tool’s own auth (API key, ChatGPT login, etc.). Cocurdex prefers reusing your existing provider setup where possible.
  3. 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):

Terminal window
cocurdex provider list
cocurdex provider models <provider-id>

First session (desktop)

Section titled “First session (desktop)”
  1. Start a new session from the desktop shell.
  2. Choose an agent runtime and model you already authorize.
  3. Keep terminal and editor available — agent work often spans more than the chat stream.
  4. Send a small, concrete task first (for example “list the top-level layout and summarize entry points”).
  5. 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)

Section titled “First session (CLI TUI)”

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

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

Or create a session, then send messages:

Terminal window
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

Section titled “Product data in five minutes”

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

Terminal window
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"

Details: Notes and issues and Workspaces and data.

Optional: product skills

Section titled “Optional: product skills”

Install namespaced product skills so agents can run /cocurdex-* flows (grill → PRD → issue → ship) against the same data plane:

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

See Skills.

Checklist

Section titled “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 live (app-owned storage, not ad-hoc repo files)

Next

Section titled “Next”