2. Getting started

Launching

plank              # interactive
plank --help       # every flag

plank picks its front end from your terminal, not from a flag:

The TUI and the REPL support the same slash commands and the same tools. The TUI adds markdown rendering, syntax highlighting, mouse scrollback, the status bar, panels for /btw and questions, and the arcade.

Your first turn

Start plank in the project you want to work on:

cd ~/Code/my-project
plank

At startup plank gathers session context — git status, the date, any AGENTS.md it finds — and hands it to the model before your first message, so you can open with "why is the parser dropping the last token?" rather than explaining where you are.

Then type. A few things to know immediately:

• You can keep typing while it works. Each turn runs on a worker thread; the prompt stays live during generation and your next message queues, held in a pinned region under the status bar until the turn picks it up.
• Ctrl-C interrupts the turn, it does not kill plank. At an empty prompt it clears the input line.
• Esc also interrupts a running generation.
• The turn ends when the model stops calling tools. plank runs generate → dispatch tools → feed results back → generate again, until a generation asks for nothing.

It is not only for code

plank is built as a coding agent, but nothing about it is restricted to code. In practice it gets used for:

• Questions with no repository involved — "how do you write a lock-free queue?", "how is the diagonal function computed in a residual number system?" Ask; there is no requirement that a session touch a file.
• Web research — "search the web for the latest news about X and summarize". The model searches, visits pages, and reports back. See Tools.
• Documents — point it at a PDF and it reads it: "summarize the first few pages of manual.pdf".
• Other languages — the model answers in whatever language you write in.
• Writing — prose, posts, poems. Handing it a style file ("write a post about X using the style in style.md") works better than describing the style.

Short follow-ups work the way they do in a conversation: "what else", "keep going", "now one in Pascal", "summarize it here". You do not need to restate context that is already on screen.

Working directory

plank operates in the directory it was launched from. Tools resolve relative paths against it, the bash sandbox writes only inside it, and project-scoped config (./.plank/, ./.mcp.json) is read from it.

plank --chdir ~/Code/other-project

changes the working directory before starting. One caveat: project settings are read from the launch directory, so ./.plank/settings.json does not follow --chdir.

One-shot mode

plank -p "summarize what changed in the last three commits"

Runs a single prompt with all tools available, prints the reply, and exits. Works with hosted providers too:

plank --provider anthropic --model claude-sonnet-4-5 -p "review src/parser.rs"

Headless mode

--ui picks the front end. --ui tui is the default (the full interactive UI, or the plain REPL when either end is piped). --ui console disables the interactive UI: with -p it runs the one prompt and exits, and without one it reads a line protocol from stdin — the mode to drive plank from a script or another program. --ui chart runs a single -p prompt with its output swallowed and prints nothing but the /toks throughput chart for the run, painted live — it fills in place as the model generates, and shows prefilling... until the first sample lands, which is what you want when you are measuring the engine rather than reading the reply; --ui quiet is the smallest front end there is: it prints Prompting. as the turn starts, Started working... when the model begins generating, and done. when the turn ends, all on one line and nothing else — for a script, or for watching a long run from the corner of your eye. Both chart and quiet need a -p prompt and refuse to start without one. For driving the TUI from a test harness, see --ui-remote in Remote and hosted engines.

Leaving and coming back

Type /quit (or /exit, or Ctrl-D at an empty prompt). Your session is saved automatically.

plank /resume            # most recent session
plank /resume amused     # by name prefix

or from inside plank, /resume with no argument to pick from a list. A resumed session replays through the same renderer, so history comes back as markdown with thinking dimmed — and plank restores the engine KV alongside the transcript, so it does not have to re-read the whole conversation before your first new message.

On the way out plank prints what the run cost:

Session stats  ↓ 128,209 ↑ 8,269  ·  12:20
  glm5.2          ↓ 120,000 ↑ 7,900
  ds4 (local)     ↓   8,209 ↑   369

Tokens in and out, and the wall clock. The per-engine breakdown appears only when more than one engine served the session — which is the case worth reading, since it separates what a hosted provider billed you for from what ran on your own machine.

See Sessions for the full story.

Telling plank about your project

Two files change how every session in a directory starts:

• AGENTS.md — project instructions, discovered and injected at session start. /init generates one by having the model read your repo.
• ./.plank/MEMORY.md — durable facts about goals and constraints, appended with /remember.

See Context.

When something is ambiguous

The model can ask you rather than guess: the ask tool opens a multiple-choice panel (a numbered list in the REPL) and blocks until you pick. It degrades cleanly when there is nobody to ask.

If a task is risky, the model can enter plan mode — read-only until it proposes a plan and you approve it. See Tools.

Next: The interface →