Desktop

codai desktop lets the assistant work on your computer: run commands, read and edit files in folders you approve, drive a browser in a separate profile and — on Windows — click around in other apps. It ships with a small code workbench (Monaco editors, terminals, file explorer, Git view) so you review every change before it lands. Apache-2.0, source at github.com/codai-ro/codai-desktop.

InstallCopy Anchor Link

Get the newest build from codai.ro/download or the latest GitHub release. Every release is tagged desktop-v<version>; the version you run is shown in Settings → Device & gateway → Updates.

Linux dependenciesCopy Anchor Link

The .deb and .rpm packages declare what they need, so apt and dnf install it for you. The AppImage carries most libraries itself, but it still uses the system WebKitGTK, the tray library and your graphics driver. Install these first if the app does not start, shows a blank window or has no tray icon:

# Debian / Ubuntu
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1 gnome-keyring libsecret-1-0 xdg-utils

# Fedora
sudo dnf install webkit2gtk4.1 gtk3 libayatana-appindicator-gtk3 gnome-keyring libsecret xdg-utils

# Arch
sudo pacman -S webkit2gtk-4.1 gtk3 libayatana-appindicator gnome-keyring libsecret xdg-utils

• KDE users can keep KWallet instead of GNOME Keyring: any Secret Service provider works. Without one, the app stores secrets in a file only your user can read and says so in Settings.
• Blank or white window on an NVIDIA driver. The app already turns off WebKit's DMA-BUF renderer when it finds the NVIDIA driver. To force it on another setup, start the app with WEBKIT_DISABLE_DMABUF_RENDERER=1; set it to 0 to turn the renderer back on.
• There is no AUR package yet. On Arch, use the AppImage with the packages above.

First runCopy Anchor Link

SkinsCopy Anchor Link

The skin is the shell the main window renders. Switching never stops anything — terminals, agents, editors and browser tabs keep running underneath.

Open a folder with no code and codai offers to switch to Assistant; open a code project and it offers Developer. Settings → Skins → Use for this workspace only pins a skin to one folder.

ChatCopy Anchor Link

Sending, steering and queueingCopy Anchor Link

• Enter sends; Shift+Enter adds a new line.
• While a turn is running, Enter with text steers the current turn: the message is added as "waiting for the current step" and the agent reads it at its next step.
• Ctrl+Enter while a turn is running queues the message as its own turn ("after this turn"); you can remove it before it starts.
• With an empty box during a turn the send button becomes a red Stop.

Plan firstCopy Anchor Link

The Plan pill in the composer has three settings: off (act right away), auto (default — plan first on non-trivial requests: long, agentic, or with files) and always. Whatever the setting, you can force or skip a plan for a single message (Plan first: this message / Plan first: skip this message).

Questions from the agentCopy Anchor Link

When a decision is needed, the agent shows a card — "N decision(s) before continuing" — with a recommended option per question. Click Continue with the recommendations, pick other options, or type your own answer.

Cost and contextCopy Anchor Link

• Each finished turn shows its tokens and cost (… tok · $…, ~ when estimated); hover it for prompt, cached, completion and request counts. The composer shows the running total for the chat and an estimate for the next request.
• (v0.7+) A ring next to the composer shows how full the model's context window is (Context: used / window tokens (pct%)), including the point at which the conversation is compacted.

Reviewing changesCopy Anchor Link

(v0.7+) Proposed file changes open in Review changes, one hunk at a time:

Accept all, Reject all and Apply (N accepted) work on the whole set; right-click a hunk for Accept This Hunk / Reject This Hunk. You can also leave a comment on a hunk — comments are sent back to the agent with your decision so it can revise.

Undo a turnCopy Anchor Link

Before the agent writes a file, the previous content is saved as a checkpoint. From a message's Message actions menu:

• Restore checkpoint — reverts files changed after that message and drops the messages below it (disabled while a turn runs).
• Fork from here — starts a new chat from that message.

You can also just ask the agent to undo; it can roll back its recent change sets and delete files it created.

History, snapshots and revertCopy Anchor Link

Open History from the Assistant sidebar (next to Chat, Sessions and Memory). It lists every change the assistant made to the open folder, newest first, grouped by day; open an entry to see its diff.

• Snapshots. After each agent turn that changes files, codai records a snapshot: a commit tagged [codai snapshot] on the current branch (only the changed files; Git hooks skipped) plus a hidden checkpoint ref. This is controlled by Settings → Workbench → Keep a history of changes automatically (on by default); with it on, a folder without Git gets a repository and a .gitignore the first time you open it.
• Revert. Puts the entry's files back the way they were before that snapshot; your other changes stay as they are and your branch is not moved. The revert gets its own entry, with Revert again to undo it. The first snapshot of a project cannot be reverted — there is nothing before it.
• Restored later. A revert never deletes files. Files it would remove (ones the reverted turn created) are moved to %LOCALAPPDATA%\codai\restored-later\ and listed under Restored later (N). Use Bring back to return one (if a file already exists there you can restore it alongside as name (restored …).ext), Delete permanently for one, or Empty for all. This safety net exists only in the desktop app.

Old hidden checkpoint refs are pruned (the newest 200 and anything younger than 30 days are kept); the commits themselves stay.

Save to cloudCopy Anchor Link

The Save to cloud card sits at the top of History and in the Source Control view.

Fold assistant steps into one commit at Save to cloud (Settings → Workbench, on by default) squashes each run of consecutive, not-yet-pushed codai snapshot commits into one before pushing. Your own commits and anything already pushed are never rewritten, and there is no force-push.

Triggers and InboxCopy Anchor Link

Command palette → Open event triggers or Open inbox opens one tab with Triggers and Inbox. You need to be signed in to codai.

• New trigger — pick a source: GitHub, Sentry, Google Cloud alerts, Any webhook (signed JSON) or Contact / feedback form. You get a Webhook URL and a Signing secret (shown once). GitHub and Sentry have one-click setup buttons.
• What happens on an event — mode (Notify only, Assisted, Autopilot, Smart by severity; Autopilot never deploys), what the agent may do (Read only, Edit files, Open a PR), a severity floor, sessions per hour, quiet hours, budgets per event and per day, filters and an agent prompt with {{event.*}} placeholders.
• Test fire, Enable/Disable, Rotate secret; Recent events shows what each event led to.
• Inbox collects notifications from triggers and cloud tasks, unread first, with Mark read, Mark all read and Open link.

Local ingressCopy Anchor Link

To receive webhooks from tools on your own machine or LAN without a public URL, turn on Local ingress in a trigger (off by default): Listen for local webhooks, Listen on This computer only (127.0.0.1) or Local network (LAN) (then Allowed networks (CIDR) is required), Port (default 8788), Apply. Set the trigger's Accept events from to Local ingress only or Both.

Senders post to http://127.0.0.1:8788/hooks/<trigger id>, signed exactly as for the public URL; the app forwards the raw body to the gateway with your key. Bodies are limited to 1 MiB, 60 requests per minute, and Content-Length is required. Payloads and signing are described in the triggers API.

MemoryCopy Anchor Link

Open Memory from the Assistant sidebar or the layout menu. Notes are Markdown files the agent can find and read:

Use New note, Rename, Delete, Edit (opens in the editor) and Search (full-text, file:line hits). Imported notes are not copied — they are read where they are.

The agent also learns on its own: a playbook of short verified tips with helpful/harmful counters and a trust score, lessons (symptom → believed → proved → fix) and episodes (goal, outcome, verified). Review them in Settings → Executor → Memory & tools: rate playbook items 👍/👎, Consolidate now (also runs after 10 idle minutes), Export JSONL (to %LOCALAPPDATA%\codai\exports\). They are stored in %LOCALAPPDATA%\codai\memory.sqlite and never leave this PC.

MCP serversCopy Anchor Link

Settings → Executor → MCP servers lists the servers the agent can use, with an Enabled switch, status (Connected · N tools, Error, Disabled), Reconnect and Reconnect all. Statuses appear after the first agent run.

Add servers in JSON — later files win per id:

1. ~/.codai/mcp.json
2. <folder>/.codai/mcp.json
3. <folder>/.vscode/mcp.json

Both servers (VS Code) and mcpServers (Claude Desktop) keys are accepted, so existing files work unchanged:

{
  "servers": {
    "files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "remote": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer …" } }
  }
}

Two transports: stdio (command, args, cwd, env) and Streamable HTTP (url, headers; "type": "sse" entries use the same client). The agent sees tools as mcp:<server>_<tool>, and every MCP call asks for approval like any other action.

One-click servers add a preset with a token stored in the OS keychain — currently Brivio (read-only). (v0.7+) Remote servers that require OAuth show a Sign in button instead of a token field.

Local modelsCopy Anchor Link

Two ways to run models on this PC (Settings → Providers):

• codai engine (Windows x64) — a managed llama.cpp server. The app downloads the right llama.cpp build for your GPU (CUDA 12, CUDA 13 on Blackwell, Vulkan, or CPU) to %LOCALAPPDATA%\codai\engine\, then GGUF models from Hugging Face (checksum-verified, resumable) to %LOCALAPPDATA%\codai\models\ or a folder you choose. Pick Download, Use, Switch or Stop; the server listens on a random 127.0.0.1 port and sleeps after 10 idle minutes. Re-tune GPU split measures how much of the model fits on your GPU and remembers it per model and driver.
• Ollama / LM Studio — if they are running on their default ports (11434 / 1234) they are detected and listed next to the codai engine.

ThemesCopy Anchor Link

Settings → Color Themes has 12 built-in themes — codai Dark (default), codai Light, Midnight Blue, Forest, Ember, Rosé Noir, Paper, Sky, Mint, Blossom, Dark High Contrast, Light High Contrast — plus Follow system.

Your own themes are JSON files in %USERPROFILE%\.codai\themes\ (Theme folder opens it). Use New theme, Duplicate, Edit JSON, Import JSON… or Export JSON…; changes to files apply within a couple of seconds, no reload needed. A theme file has id, name, base (dark/light), accentHue, colors (bg, bgElevated, bgPanel, border, borderStrong, foreground, muted, muted2, danger, success, warning) and optional terminal ANSI colours. Use for this project writes <folder>/.codai/theme.json.

WorkbenchCopy Anchor Link

In the Developer skin:

• Explorer (Alt+4), Quick open (Ctrl+P), Find in Files (Ctrl+Shift+F).
• Terminal — toggle with Ctrl+` , new with Ctrl+Shift+~, split with Ctrl+Shift+5. On Windows: PowerShell 7 (if installed), Windows PowerShell or Command Prompt.
• Tasks — defined in <folder>/.codai/tasks.json (label, command, optional args, cwd). Without that file, tasks come from package.json scripts and Cargo.toml. Each task runs in a visible terminal; Ctrl+Shift+B re-runs the last one.
• Source Control (Ctrl+Shift+G) — changes, commits and the Save to cloud card. (v0.7+) Open pull request and CI status for the current branch, through the GitHub CLI (gh, signed in).
• Detached windows — right-click an editor tab → Move into New Window.

Agent machineryCopy Anchor Link

Project instructionsCopy Anchor Link

At the start of a turn the agent reads, from the root of the open folder: AGENTS.md, CLAUDE.md (v0.7+ at the repo root), .claude/CLAUDE.md and .github/copilot-instructions.md; from your home folder ~/.claude/CLAUDE.md and ~/.copilot/copilot-instructions.md. Rules in .github/instructions/*.instructions.md and ~/.claude/rules/*.md are added when their applyTo: / paths: globs match the files being touched. Each file is capped at 12,000 characters (48,000 in total).

SkillsCopy Anchor Link

A skill is a folder with a SKILL.md. The agent sees an index and opens a skill when it fits. Searched in ~/.agents/skills, ~/.copilot/skills, ~/.claude/skills, ~/.codai/skills, then the project's .github/skills and .codai/skills — project skills override personal ones, which override the built-in ones.

SubagentsCopy Anchor Link

For larger tasks the agent can delegate:

• explore — read-only investigation in a fresh context; returns a summary with file:line references.
• review — scores a diff against the plan and returns findings.
• spawn_agent — roles explore, research, code, verify, review; up to 4 run in parallel after one approval, and a code agent may only edit the paths it was given.
• ask_expert — one question to the codai frontier model, at most 4 per task.

HooksCopy Anchor Link

Hooks run your scripts on PreToolUse, PostToolUse and Stop. They are read from ~/.codai/hooks.json, ~/.copilot/hooks.json, ~/.copilot/hooks/*.json, <folder>/.codai/hooks.json and <folder>/.github/hooks/*.json. Exit code 2 blocks the action and its message is shown to the agent; timeouts (default 5 s) and other errors let the action through. PreToolUse fires for file edits and desktop tools.

Rules gateCopy Anchor Link

A built-in floor always applies: the agent cannot change rules, hooks, skills, instruction files or keys (it can only propose changes), cannot pay above your wallet mandate, and cannot rewrite the audit trail. Your account's rules arrive as a signed manifest, refreshed every 6 hours. If rules cannot be loaded, autonomy is forced to Strict.

Autonomy levelsCopy Anchor Link

Autonomy controls what the agent may do on your computer without asking. It applies to computer control (Windows apps) and is shown in the status bar — click it to cycle.

Independent of autonomy, shell commands, file writes and browser actions ask for approval the first time per session: Allow once, Always allow (this session) or Deny. Reading files and taking a browser snapshot never ask.

Computer control and the overlayCopy Anchor Link

Settings → Computer control lets the agent see and operate Windows apps through UI Automation: read the controls of a window, click, type, scroll, open programs. Actions are gated by the autonomy level above and mirrored on the overlay — a ghost cursor, a highlight ring on the target and a caption saying what the agent is about to do. Turn the overlay off with Show the overlay while the agent acts if you find it distracting.

Kill switch: Ctrl+Alt+Space, or Esc twice, stops the agent instantly. Your own mouse or keyboard input pauses it. Windows-only.

Hosts — serve your phone and the browserCopy Anchor Link

Settings → Executor → Serve as a remote host for my phone turns this desktop into a host: a machine that your other clients can run terminal and file operations on, inside the allowed folders. The status bar shows Relay: online while the connection to the gateway is up.

Who uses it:

• The Android app — "run this on my PC" tasks and the hosts terminal backend.
• The web app at app.codai.ro — the Run on picker lists your online desktops; the browser chats, this machine executes. See Web.

Only devices signed in with the same account can see or use a host; a host drops off the list 45 seconds after its last heartbeat. Protocol details are on the hosts relay page.

Separately, Run tasks dispatched to this device (same settings section) lets your phone or the hub dispatch a whole task to this desktop; it polls every 30 seconds and runs it here.

Devices, floating chat and accountCopy Anchor Link

• Devices (sidebar, Alt+3) lists every device on your account — desktop, Android, iOS, web, CLI, agent — with this device and seen …. Revoke removes a device from presence and dispatch; it does not revoke that device's API key (do that in the hub).
• Floating chat — Ctrl+Alt+C from any app (the global shortcut is Windows-only), the tray item Floating chat, or the command palette. A small always-on-top window; closing the main window hides it to the tray, and Quit in the tray exits.
• Start with Windows (Settings → Chat) launches codai hidden in the tray at sign-in.
• Credits (Settings → Account) shows your prepaid balance, expiry, promotions and the last 10 entries.
• Referrals (Settings → Account) — pick a username and consent to get Your invite link; see Invited / Rewarded / Pending, or enter a friend's code before the deadline.

What it may touchCopy Anchor Link

Settings → Executor:

• Approved folders — the only places file tools can read or write. Default: your home folder. Paths are canonicalised, so .. and symlinks pointing outside are refused.
• Browser executable — autodetects Edge or Chrome; always launched with its own profile folder, so your tabs, cookies and passwords are never involved.
• Budgets — timeouts for one command (default 30 s), one tool call and a whole turn (default 10 minutes). Output is capped at 64 KB per stream.
• Semantic search — opt-in local model (multilingual-e5-small, one-time ~205 MB download) that indexes the workspace on this PC. Nothing leaves it.

UpdatesCopy Anchor Link

The app checks for updates 60 seconds after launch and then every 6 hours. If a newer version is listed it downloads the installer, verifies its minisign signature against the public key compiled into the app, and installs it once no workspace window is open. An update whose signature does not match is refused; the updater never downgrades. Check by hand from About → Check for updates.

The Microsoft Store build is updated by the Store instead; Check for updates there always reports the installed version as current.

ChannelsCopy Anchor Link

Settings → Device & gateway → Updates → Channel: Stable (https://codai.ro/api/desktop/latest.json, default) or Beta (https://codai.ro/api/desktop/beta/latest.json). The change applies at the next check, without a restart. Going back from Beta to Stable never downgrades — you keep your version until Stable passes it. If your account enabled Beta for you, your own choice overrides it.

Releases list windows-x86_64, plus linux-x86_64 when an AppImage was built for that version. The portable .zip has no updater.

Interface updatesCopy Anchor Link

Smaller fixes to the interface can arrive as a signed UI bundle without reinstalling. When one is ready you see Interface … is ready — reload to use it with Reload now or Reload when idle. Every file is checked against the signed manifest; if the new interface fails to start or crashes, the app goes back to the previous one and blocks the bad version.

Uninstall and data locationsCopy Anchor Link

Uninstall from Settings → Apps (Windows) or with your package manager (Linux). The uninstaller does not delete your data:

On Linux the same folders live under ~/.config/ro.codai.desktop and ~/.local/share/codai.

Before uninstalling, Settings → Sign out revokes this device's key on the server. If you forgot, revoke it from hub.codai.ro → Security → Devices.

Lists and Share to codaiCopy Anchor Link

Lists (sidebar, Alt+0) keeps links, text, images and files you send to codai: Inbox, Wishlist and Notes exist from the start, and you add or reorder lists under Settings → Lists. Paste from clipboard saves what you copied; without a list chosen it goes to Inbox and codai suggests where it belongs. Ctrl+Alt+S does the same from any app, and the Microsoft Store build appears in the Windows share sheet. A screenshot in the clipboard pastes straight into the chat composer as an image. Product links get title, image, price and stock; open a list to export it as Markdown or Ask codai about it. The same lists are on the phone (share sheet, Direct Share per list) and at hub.codai.ro/lists.

KeyboardCopy Anchor Link

Every binding can be changed in the keyboard shortcuts editor (Ctrl+K Ctrl+S).