How to use deck

Install

One script. It downloads deck for your machine, checks that the download is intact, puts it on your PATH, and then runs deck setup.

macOS and Linux

Windows, in PowerShell

• Run it as yourself, not with sudo.
• Running it again keeps your settings and your decks.
• deck updates itself on macOS and Linux. On Windows, run deck upgrade when you want the next release.

Build it from source

You need Rust. On Linux you also need WebKitGTK, which the window uses to draw pages.

cargo install --git https://github.com/henit-chobisa/deck deck-app
deck setup

Set it up once

deck setup is the one thing only you can answer. It:

1. Asks how deck should look. It can borrow your editor's colours, so a deck looks like the code you already read all day.
2. Teaches your agents. It installs a short skill into each coding agent it finds on your machine, so they know when to reach for deck and how to write a good one.
3. Offers the catch. A hook that sends a reply full of file:line locations back to your agent to become a deck instead.

It writes your answers to ~/.deck/config.toml. Run it again any time to change them.

Your first deck

Ask your agent about some code, the way you already do: a bug, a plan, a review, or how something works.

1. The agent writes a deck. A title, then one group at a time. Each group is one thing it wants to say, and the code that shows it. deck refuses a group that points at a file or a line that does not exist.
2. A bar appears at the bottom of your screen. It names the deck and shows how far along it is. Open it when you are ready. The agent cannot open it for you, and there is no flag that lets it.
3. You read it. Each sentence lights the code it is about.
4. You answer. Comment on the lines you disagree with, ask a question, or submit.
5. The agent gets your answer. The command that opened the deck has been waiting the whole time. When you submit, ask, or close the deck, it ends and hands your agent what you said, pinned to the lines you said it about.

The window

Walk the argument, not the diff

A deck is a sequence of groups. Each group is one claim with the code that proves it: an enum and the column that stores it, a writer and the reader that consumes it. The relationship is on screen instead of in your head. n and p move between groups.

The light follows the sentence being read, not your scrolling. Press a sentence in the narration and the code it is about lights up, in whichever pane is showing it.

Put it away without losing it

Press h and the deck goes back to the bar with your comments still in it. When several decks are waiting, the bar says which one you are on, as in 2 of 3.

Arrange it the way you read

Drag a seam to resize a pane, press t to turn the panes a quarter, and the shape is remembered for next time.

Keys

Comments and questions

Drag across lines and press c. Drag across the narration itself to answer a sentence rather than a line; that is where this whole approach is wrong goes. Then finish it one of two ways:

esc discards. When the agent is not listening, Ask now is off and says why; the review still takes the comment.

Every comment is pinned to the lines it was about, together with the text it was written against, so it survives the file moving underneath it. When it comes back to your agent it says how far to trust the location: diff, fingerprint, or stale.

Asked something mid-deck, your agent can answer with a pane rather than a paragraph: a file it brings in, or a chart drawn there and then, folded in beside what you were already looking at.

The walk and the voice

The rail beside the panes holds everything said in the deck. The agent that wrote it can move your eyes while it talks: show you lines, bring in a file the group never showed, fold a pane away to its spine, or say something new.

Movement is yours the moment you take it. Scroll, select, or start typing and the agent stops moving you; the rail says paused. It lapses by itself after a few seconds of stillness, and f hands control back straight away.

Reading aloud

With a voice set up, w reads the deck aloud and the light moves through the code in time with the words, timed from the sound itself. Set it up once:

deck walk

It lists the Google Chirp 3 HD voices and plays one before you choose. Until you do, the window does not offer w at all, and everything else works without it.

The key can live in DECK_SPEECH_KEY rather than in a file. To be plain about it: the narration is sent to Google to be turned into sound. The narration, not your code, and nothing is sent until a key is set up.

What comes back

For a walked deck your agent also gets a transcript: what you were shown, in what order, and what you said about each part.

Diagrams and pages

Diagrams

Some things are in no file at all: how a click reaches a controller, or the order four services touch one request. A group can carry a picture beside its code. A flow is a named path through it. Press the flow and a current travels the route while the rest of the picture steps back.

A sentence can light lines and a block in the picture at once. That is what a diff or a diagram cannot do on its own. Drag the drawing anywhere. Hold ⌘ or Ctrl and scroll, or pinch, to zoom.

Pages, for the idea that only moves

Two workers racing for one count, a queue filling until the producer is told to stop, a latency chart bending when the cache goes cold. When the argument is the movement, a group can carry a page: a small piece of HTML your agent writes, drawn in deck's own colours. It hears the same points the code does, so it moves with the sentence being read rather than with a clock.

Pages are narrow on purpose: at most forty words on screen, nothing fetched from the network, and deck's palette instead of their own.

Theming

deck borrows your editor's colours: the page, the text, an accent and the syntax. The shapes and the spacing are always deck's.

# ~/.deck/config.toml
[theme]
editor = "vscode"   # nvim | zed | vscode | cursor | windsurf

Try a theme on without changing your editor:

deck open <deck> --theme "vscode:Solarized Dark"

Light or dark follows your machine unless you pin it, which is worth doing for a recording:

deck open <deck> --mode dark --paper warm

Configuration

Everything lives in one file, ~/.deck/config.toml. deck setup and deck walk write it for you, and every setting has a default, so an empty file and no file behave the same. Here is every setting, at its default unless a comment says otherwise. editor and voice show example values.

# ~/.deck/config.toml

[theme]
# Borrow an editor's colours: nvim, zed, vscode, cursor or windsurf,
# or one of its themes, as "vscode:Solarized Dark". Default: none.
editor = "vscode"
paper  = "grey"      # the neutrals when nothing is borrowed: grey or warm
mode   = "auto"      # auto follows your machine: auto, light or dark

[theme.colors]
# None by default. Any set here wins over everything else.
# These values are only examples, from gruvbox.
accent  = "#fe8019"  # lit lines, names and buttons
bg      = "#282828"  # the page
fg      = "#ebdbb2"  # the text
muted   = "#a89984"  # secondary text
edge    = "#3a3735"  # borders and seams
add     = "#b8bb26"  # added lines in a diff
del     = "#fb4934"  # removed lines in a diff
comment = "#928374"  # comments in code
# Also: band, wash, focus, on_accent, gone, fresh, ground.

[layout]
arrange        = "stacked"  # how panes fill: stacked, columns or grid
max_columns    = 3          # never more columns than this
min_pane_width = 60         # drop a column before a pane gets narrower
max_panes      = 4          # more refs than this go to the next page

[zen]                # z, the lights: how the screen behind dims
dim  = 0.7           # 0 to 0.92, how far down the rest goes
blur = true          # blur what is behind, as well as dim it

[speech]             # written by deck walk
aloud = true         # read the narration aloud while walking
voice = "en-US-Chirp3-HD-Kore"  # deck walk lists the voices
rate  = 165          # words per minute
pause = 420          # milliseconds between paragraphs
# key = "…"          # better in DECK_SPEECH_KEY, which is read first

[updates]
automatic = true     # false stops every request deck makes by itself

Colours are hex, as "#rrggbb". A key deck does not know is an error that names the key, rather than a setting quietly ignored: a misspelt acent tells you so instead of leaving the deck looking the same all afternoon.

The catch

A skill is a suggestion, and an agent that has just finished an investigation is very inclined to type out what it found. So setup offers the catch: it reads each finished reply, and when one names two or more file:line locations, it sends the reply back and asks for a deck instead, while the agent still holds everything it just learned.

It stays quiet whenever it might be wrong: when a deck was already built in that turn, when the reply is about deck itself, when one location is repeated, or for a version number or a time that only looks like a location.

From 0.1.5, the same hook also helps after a long session is compacted. When a session that has used deck picks up after a compaction, it tells the agent to load the deck skill again, so the decks it writes afterwards are as good as the first ones.

The catch needs an agent with reply hooks. deck setup offers it when yours has them. Say no and everything else still works; turn it on later by running deck setup again.

What your agent runs

You will rarely type these. The skill tells your agent when and how. They are plain shell commands, which is why deck works with any agent.

Writing a deck

deck new --title "The batch counter stalls at 63" --total 2   # prints the deck's path
deck open <path>                                               # the bar, then the wait
deck group <path> --say "The counter is decremented on the **error path** too." \
  --ref "src/batch.ts:140-148 decremented *twice* when the write fails"
deck seal <path>                                               # no more groups

While you read

deck show  <deck> --ref "src/view.rs:106-110"   # move your eyes here
deck say   <deck> --text "…"                    # say something, aloud if there is a voice
deck next  <deck> --after <cursor>              # wait until you do something
deck fold  <deck> --pane protocol               # fold a pane away to its spine
deck bring <deck> --ref "src/live.rs:40-60"     # bring a file the group never showed
deck clear <deck>                               # put the borrowed panes back

Yours

Why the waiting command is the one that ends: an agent is woken by a process ending. The window cannot be that process, because someone asking a question still wants the deck in front of them. So the window runs on its own, and deck open, the command your agent ran, is the one that ends with your answer.

A deck on disk

d-1788265010-8842.deck/
  deck.json      the header: title, project, how many groups are coming
  g1.json        one claim, and the code that shows it
  g2.json
  done           written last
d-1788265010-8842.review    your answer, written beside it

You can start reading group one while group four is still being written. PROTOCOL.md is the full specification, frozen at version 1.

Can it make things up?

Not the half that can be checked. deck group opens every file a ref points at and refuses the group if the file is missing or the range runs past its end. A deck cannot be written against code that does not exist, and your agent is told while it is still working, so it can go and look.

The other half is whether the claim about those lines is true. deck's answer is that you are looking at the lines while you read the claim. A summary in chat asks you to believe it. A deck puts the evidence next to the argument and gives you a key to disagree on.

Questions