Get started
Your first session
The shortest path to seeing Deck work: one project, one session, one request, and the diff beside it.
Add the project
A project, in Deck, is a folder on your computer, usually a git repository. Add the first one by pointing at the repository you already work in. It shows up in the sidebar and becomes the place where sessions start.
Start with a repository you know well and whose work is already saved. The first session is for learning the flow, not for pointing the agent at something delicate.
Create the session
- With the project selected, open a new session.
- Pick the agent from the list. It shows the ones installed and signed in on your computer.
- Write the first request, or leave it empty and talk to the agent later, straight in the terminal.
- Confirm. The session opens with the agent already running and the terminal ready.
~/ingestao ❯ git log --oneline -3
4a093ce Sync tests
4edff57 Avoid duplicate records in the sync
3b1d01c Queue with a configurable limit
~/ingestao ❯ npm test --silent
New session
✓ Create isolated session (worktree)
Branches off main. Files and stage stay separate from the other tasks.
Plan mode (plans only, no edits)
In the background (without taking focus)
The dialog options
| Option | What it does |
|---|---|
| First prompt | What the agent gets the moment it opens. Optional. |
| Isolated session | Creates a worktree: a folder and a branch of its own, with files and a staging area separate from your other tasks. |
| Plan mode | The agent only plans and does not edit. Good for seeing what it intends before you let it touch anything. |
| In the background | The session starts without stealing focus, so you keep doing what you were doing. |
The first time, check Isolated session. That is what keeps the agent on a branch of its own, without mixing into what you have open. How it works is in Isolated tasks.
Follow along
From here you do not have to keep watching. The session changes state on its own and tells you when it needs you:
- Working. The agent is in its turn.
- Asking permission. It wants to use a tool and is waiting for your answer. The system notifies you.
- Turn finished. It is done with what it was doing and the result is there for you to read.
With more than one session open, the Grid shows them all at once. That is the subject of Agents in parallel.
Review
When the agent finishes, open the diff. It shows what changed on the session branch, file by file, beside the terminal. You can fix things right there in the built-in editor and keep the conversation going without switching windows.
~/ingestao ❯ git log --oneline -3
4a093ce Sync tests
4edff57 Avoid duplicate records in the sync
3b1d01c Queue with a configurable limit
~/ingestao ❯ npm test --silent
✔ saves each record once (2.3ms)
✔ skips duplicates on retry (0.4ms)
✔ reports received and saved (0.5ms)
ℹ tests 3 · pass 3 · fail 0
~/ingestao ❯
@@ -1,7 +1,14 @@
-// Ingestion sync.
+// Ingestion sync with duplicate protection.
export async function sincronizar(registros, salvar) {
- for (const registro of registros) {
+ const encontrados = new Set();
+ const novos = registros.filter(registro => {
+ if (encontrados.has(registro.id)) return false;
+ encontrados.add(registro.id);
+ return true;
+ });
+ for (const registro of novos) {
await salvar(registro);
}
- return { recebidos: registros.length, salvos: registros.length };
+ return { recebidos: registros.length, salvos: novos.length };
Against base 2
src/sincronizar.js+10 -3
test/sincronizar.test.js+21
Happy with the result? The path to the merge is in Pull requests. Not happy? Ask for the fix in the same terminal, or throw the worktree away and start over.
After the first one
Once the first session makes sense, these are the natural next steps:
- Projects, sessions and panes, to get organized before you open a lot at once.
- Agents in parallel, which is the reason Deck exists.
- Shortcuts, because the app was built to be driven from the keyboard.