CocurdexWorkspaces and data
How Cocurdex stores workspaces, notes, issues, slide decks, and search data on your machine — and what stays private.
Workspace
A workspace is the project context Cocurdex attaches to — typically a directory on disk where agents, the terminal, and the editor operate.
| Property | Meaning |
|---|---|
id | Stable workspace id |
name | Display name (often the folder basename) |
rootPaths | Absolute paths on disk; the first entry is the primary root |
A workspace can include several source folders. Use Edit workspace to Add folder, Make primary, or Remove folder; dropping a folder onto the window opens it as a workspace.
Open from the desktop UI or:
cocurdex .
cocurdex open /path/to/project
cocurdex workspace listSessions and many product views are oriented around the active workspace. Notes, issues, and decks may optionally associate with a workspace id; they are not “files inside the project tree” by default. The Decks list shows every deck in one list.
The local web client on this computer — and any paired device you allow — talks to the same daemon and the same workspaces.
App-owned data
Notes, issues, slide decks, views, tags, links, and search indexes live in app-owned storage (cocurdex.sqlite), not as a dual-write Markdown tree.
Important rules:
- The desktop daemon is the only process that opens the local database.
- The CLI is the supported external read/write boundary for automation and agents.
- Markdown import/export is explicit — not a second live database.
- Private table schemas and file paths are not a public API.
- Upgrades migrate the database forward and keep your data. Before a migration, Cocurdex writes a
cocurdex.sqlite.pre-migration-<timestamp>snapshot next to it and keeps the newest three. - A database written by a newer app version is refused, never downgraded. Only a file that is not a Cocurdex database is replaced, and it is first moved aside as a
.bak-<timestamp>file.
What lives where
| Data | Authority |
|---|---|
| Notes, issues, slide decks, views, tags, links, FTS indexes | Daemon + cocurdex.sqlite |
| Agent roles, team tasks, worktree settings, session records | Daemon + cocurdex.sqlite |
| Installed ACP Registry agents | Recorded in app settings; downloaded binaries live in the app's data directory |
| Managed git worktrees | Created by the daemon under the configured worktree root |
| Project source files | Your workspace directory on disk |
| Agent provider auth (e.g. Codex) | That tool’s own config (for example under ~/.codex) |
| Product skill files (optional) | Project or global skills directories after install |
Data directory
| Platform | Default location |
|---|---|
| macOS | ~/Library/Application Support/Cocurdex |
| Windows | %APPDATA%\Cocurdex |
| Linux | $XDG_CONFIG_HOME/Cocurdex (default ~/.config/Cocurdex) |
This location stays the same across releases, so updates keep reading your existing data.
Why this exists
Path-as-identity file trees make stable IDs, transactions, full-text search, and backlinks harder. SQLite gives those properties without asking every tool to parse the repo. Agents keep interoperability through cocurdex note|issue|deck|search … instead of inventing parallel .scratch trees.
Daemon
The daemon:
- Owns the DB connection
- Serves desktop and CLI over documented RPC contracts
- Runs sessions, teams, script runs, and worktree setup
cocurdex daemon statusIf CLI data commands fail, open the desktop app (or ensure the daemon process is reachable), then retry.
Cloud and team later
A future team console and cloud API will expose organization-scoped projections for selected entities (likely issues and published docs first). That does not replace local write authority for on-device work:
| Surface | Role |
|---|---|
| Desktop + daemon | Local write authority |
| CLI | Local automation boundary |
Future app. console | Team visibility / light collaboration |
Future api. | Identity, orgs, sync contracts |
End-user behavior for sync will appear here as features ship.
Safety checklist
- Do not open or migrate
cocurdex.sqlitein scripts - Do not scrape private schema as an integration surface
- Prefer CLI
--jsonand returned UUIDs - Treat product notes, issues, and decks as private until you explicitly publish