8. Configuration

Precedence

Each layer overrides the one before it:

built-in defaults → ~/.plank/settings.json → ./.plank/settings.json → environment → command-line flags

The rule of thumb: settings.json holds preferences, flags hold per-run choices.

settings.json

Hierarchical like the MCP config: ~/.plank/settings.json applies everywhere, ./.plank/settings.json in the working directory overrides it key by key. Everything is optional — the file need not exist, and any subset of keys works.

{
  "engine": { "model": "~/models/ds4.gguf", "threads": 8,
              "backend": "metal", "power": 80, "ctx": 262144,
              "thinkingToolCalls": true },
  "ui":     { "respectGitignore": true, "popupRows": 15, "indexRefreshSecs": 5,
              "historySize": 512, "showToolCalls": false, "showToolResults": false,
              "showThinking": true, "notifications": "always", "notifyAfterSecs": 10 },
  "safety": { "sandbox": true, "btwSuspend": true },
  "mcp":    { "timeoutSecs": 30 },
  "ask":    { "maxOptions": 7 },
  "update": { "check": true },
  "agents": { "autoRoute": true, "maxParallel": 4 },
  "git":    { "signCommits": true },
  "worktree": { "sparsePaths": ["src", "docs"],
                "symlinkDirectories": ["target"], "isolateAgents": false }
}

Edit it in-session with /config (an interactive form) or one key at a time:

/config ui.showThinking false

Changes write ./.plank/settings.json and apply immediately. The one-key form behaves the same in the TUI and in the plain REPL; only a bare /config opens the interactive form.

engine

ui

None of showToolCalls, showToolResults, or showThinking change what the model receives — only what you see.

safety

mcp, ask, update, agents

git

kvcache

How long plank keeps the KV snapshots under ~/.plank/kvcache/, and how much disk they may occupy in total. Ages are measured from a blob's last use, so a checkpoint you keep hitting never expires.

Three things always survive both passes: anything you have pinned in /kvcache, the chain the current launch is actually using, and any checkpoint that something newer still builds on. A budget is a target rather than a licence, so if everything left is protected plank stays over budget instead of deleting something it should not.

worktree

Two things the file deliberately will not do

• No secrets. ./.plank/settings.json sits inside your working tree and is easy to commit by accident, so there is no API-key setting. Keep keys on --api-key or the provider's environment variable.
• No per-run choices. --prompt, --non-interactive, --ui-remote, --trace, --chdir, --seed, --worktree, and the serve/control options describe one invocation, not a preference, so they have no settings key.

When it goes wrong

A broken settings file never stops plank from starting. Malformed JSON, a wrongly-typed value, an unknown key, an unrecognised backend name — each falls back to that key's default. (The same bad name passed to --backend is an error: a flag is an explicit instruction, a config file is a preference.)

Because a settings file can quietly move you off Metal or shrink the context — both of which show up only as "plank got slow" — plank prints one startup line naming what is in force, listing only settings actually in effect. With no settings file, or one that changes nothing, there is no line at all.

One limitation: settings come from the directory plank launches in, so project settings do not follow --chdir.

Command-line flags

plank --help prints the full list. The ones you are most likely to want:

Model and engine

Sampling and reasoning

Session and mode

Safety and extensions

Speculative decoding

DSpark speculative decoding is on by default: DeepSeek's auxiliary draft checkpoint for V4 Flash proposes up to five tokens ahead and the main model verifies them, committing only the prefix it agrees with, so one verification pass can advance the stream by several tokens. --dspark-off turns it off for target-only decode. The support model (~5.6 GB) needs no flag of its own — it resolves to ~/.plank/ds4flash.dspark.gguf and is offered for download through the same resumable path as the main model, unless --mtp names one.

Verification is argmax, so proposals are only used at --temp 0; sampled decoding ignores them. Whether it pays depends on the engine build, the quant and the machine: on an M5 Max it was a 0.71× slowdown until the Metal verifier was pipelined upstream, after which the same measurement read 1.19×. The peak rates in the exit message are the way to check on your own hardware.

Advanced engine tuning

--mtp PATH, --mtp-draft N, --mtp-margin F configure multi-token prediction with a draft model. --ssd-streaming and its companions (--ssd-streaming-cold, --ssd-streaming-cache-experts, --ssd-streaming-preload-experts) stream experts from SSD instead of loading them resident, which is how you run a model that does not fit. --simulate-used-memory <N>GB pretends memory is already used, for testing those paths. --dir-steering-file, --dir-steering-ffn, --dir-steering-attn apply directional steering vectors.

Remote, shared-engine, control, and provider flags are covered in Remote and hosted engines.

Environment variables

Next: Extending plank →