For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/desktop/agents.md (or send Accept: text/markdown).
Build with a coding agent
Hand tasks to a coding agent: the files it reads, the shipped skills, and the review that keeps you in control.
Beginner walkthrough
Prerequisites: Read the two beginner guides below and finish Desktop local setup. A coding agent is an AI tool — Cursor, Claude Code, Devin or a similar assistant — that reads your project, edits files and runs commands. Everything on this page applies to whichever one you use.
Quick terms: a prompt is the instruction text you paste into the agent. A diff is the list of file changes it proposes. The repository root is the top folder containing package.json — the agent should always start there.
1. Open .agents/skills/ in the repository root and copy the skill closest to your task — add-a-desktop-capability is a good first try.
2. Paste it into your agent and describe your change, then add one line: Read llms.txt, then AGENTS.md, then .ai/PROJECT_CONTEXT.md before touching code.
3. Let the agent list the files it will change and the checks it will run before it edits. When it finishes, review the diff — you are approving real changes to your product.
4. Publishing, releasing installers and paid provider calls are never part of a task prompt. Keep them as separate steps you approve explicitly.
The files your agent reads
The repository ships a small stack of files written for agents, not only for humans. You never paste this context by hand — point the agent at llms.txt and it reads the rest itself.
Read order matters: llms.txt is the map, AGENTS.md sets the boundaries, and .ai/PROJECT_CONTEXT.md carries what earlier sessions learned. An agent that skips the boundaries produces code you cannot ship.
| File | What it gives the agent |
|---|---|
| llms.txt | The repository entry map, generated to list only what this checkout actually ships |
| AGENTS.md | The non-negotiable boundaries: local work only until you approve more, the shell never forks product UI |
| .ai/PROJECT_CONTEXT.md | Cross-session memory — what changed recently and why; read before code changes |
| .ai/ mirror docs | A matching .ai/<path>.md note beside important files, recording per-file decisions and open threads |
| .agents/skills/ | Task runbooks written for agents — the five desktop skills listed below |
| docs/agent-security.md | The acceptance checklist — authentication, workspace and permission checks, redacted logs |
| docs/desktop-updates.md | The update-channel runbook — signing keys, endpoints and release channels |
| .env.example | The complete environment inventory — the agent never invents a variable name absent from this file |
The shipped skills
Each file under .agents/skills/ is a complete brief: paste it or let the agent read it, and the kit's rules travel with it — product UI stays in the web app, only OS behavior goes in Rust.
The pasteable prompts/ library ships only in the Web repository; this checkout carries skills instead. For an unattended setup, use the ready prompt in the agent-setup guide.
add-a-desktop-capability— window, tray, shortcut, update or build changesadding-a-dependency— add, upgrade or move an npm dependency safelyreviewing-a-pr— review a diff for correctness, workspace isolation and secretsupgrading-from-upstream— pull a newer kit release into your shellverify-changes— choose and run the right checks before handoff
How the agent remembers between sessions
Agents have no memory between sessions — the .ai/ folder is the memory. .ai/PROJECT_CONTEXT.md records what changed recently and why. Beside it, a mirror doc such as .ai/apps/desktop/src-tauri/src/lib.md explains the decisions behind apps/desktop/src-tauri/src/lib.rs that the code alone does not show.
The contract is simple: read a file's mirror before editing it, and update the mirror when the change lands. Open Threads entries record unfinished work so the next session resumes instead of starting over. A stale mirror is worse than none — when you review the agent's diff, check that the mirrors of changed files moved with it.
Review the agent's work honestly
A finished task is evidence, not a summary. Before you keep the agent's work, check it the way docs/agent-security.md checks a deployment:
When something is wrong, send the diff back — the agent fixes its own work fastest when you name the failing check. For anything it should never have attempted alone, say so explicitly once; the boundary holds for the rest of the session.
- It ran the checks it claims — cargo test, cargo check or the release preflight — ask for the command and its output, not a conclusion.
- Secrets stayed server-only — no signing key or certificate was printed into a report or commit, and the shell still carries no provider credentials.
- Product behavior stayed in the web app — the diff adds no parallel UI, auth or chat logic in Rust.
- The
.ai/mirror of each changed file moved with the code. - Publishing, releasing installers and paid provider calls stayed separate steps you approved — the agent never merged, pushed or released on its own.
- If a step failed twice, it stopped and reported the failing command instead of improvising around it.
If you want to continue setup, read Create desktop release accounts.