plank user guide

plank is an interactive coding agent for the terminal: a full-screen TUI, a plain line REPL, and a headless one-shot mode, driving either a local DeepSeek V4 Flash model on Apple's Metal backend or a hosted provider.

This guide is for people using plank. For how it is built, see docs/ARCHITECTURE.md; for the exhaustive feature list, docs/FEATURES.md.

macOS only. Real inference uses the ds4 C engine with the Metal backend. Other platforms build and run against the echo stub, which is useful for development but not for real work.

Contents

• 1.InstallationHomebrew, channels, building from source, getting the model
• 2.Getting startedyour first session, the three front ends, one-shot mode
• 3.The interfacethe TUI tour, keybindings, @ completion, ! commands, images
• 4.Slash commandsthe complete command reference
• 5.Toolswhat the model can do, the sandbox, plan mode, questions, task lists
• 6.Sessionssaving, resuming, checkpoints, branching, export
• 7.Contextthe context window, compaction, AGENTS.md, memory
• 8.Configurationsettings.json, command-line flags, precedence
• 9.Extending plankskills, templates, subagents, hooks, MCP servers
• 10.Remote and hosted enginesserve, --remote, shared engines, providers
• 11.The arcadethe games that run over a live turn
• 12.Advanced workflowsbranching, delegation, long sessions, repeatability
• 13.Troubleshootingwhen something goes wrong

The five-minute version

brew install aovestdipaperino/tap/plank-agent
plank                  # first run offers to download the model

Then type. Ask a question, ask for a change, let it read and edit files. When you want to know what plank can do, /help; when you want to know where your context went, /context; when you want to come back tomorrow, just quit — the session saves itself and /resume brings it back.