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": 32 },
  "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

tools

context

memory

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, --ui, --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

--minimal-prompt implies both off; an explicit flag wins whichever order you give them in.

Speculative decoding

Speculative decoding is on by default under one name, --mtp. DeepSeek V4 Flash uses its auxiliary DSpark draft checkpoint: it 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. DeepSeek V4.1 Flash has no drafter upstream, so plank never pairs one with it and decodes target-only there. --mtp-off turns speculation off explicitly.

On V4 the support model (~5.6 GB) needs no flag of its own: it is the ds4vision engine's mtp companion, resolves to ~/.plank/ds4vision.mtp.gguf, and is offered for download through the same resumable path as the main model, unless --mtp-model names one. A model loaded by a bare path has no companions, so speculation there needs --mtp-model.

A drafter plank paired for you is no longer able to stop a model from loading. The engine refuses to open a model at all when the draft checkpoint does not match it, so a checkpoint the default drafter does not fit used to fail until you found --mtp-off; plank now retries the open once without the companion it chose and reports the original error only if that fails too. A companion you named with --mtp-model is never dropped. When speculation turns out not to run, the temperature you would have been sampling at is restored rather than left pinned at 0.

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. You rarely need to reach for --ssd-streaming yourself any more: plank measures the model file at startup and turns streaming on when it exceeds 80% of installed RAM less the engine's context buffers, printing the calculation it used. Passing the flag yourself skips that decision. --simulate-used-memory <N>GB pretends memory is already used, for testing those paths. Directional steering has a section of its own, Steering, below.

Steering

Directional steering nudges the model's activations along a direction, layer by layer, so it leans towards one kind of answer: terser, more cautious, less likely to refuse. plank keeps every direction you have in one file, ~/.plank/models/vectors.json, and you choose one by name:

plank --dir-steering succinct

The file is a JSON array with one entry per model, each listing its named directions. A direction's value is base64 of the raw little-endian f32 matrix the engine loads, one unit vector per layer:

[
  { "model": "ds4vision",
    "vectors": [
      { "name": "succinct", "value": "Pq3vPLnF...", "emoji": "📖" },
      { "name": "heretic", "value": "u0Kz/D2p..." }
    ] }
]

An entry's model is the engine name, so a direction built for ds4vision follows that engine whatever its file is called. A model loaded by a path that is no engine is looked up by its file name instead, and plank tries the engine name first and the file name second. A direction belongs to the model it was built on: the same name under another model is a different vector.

You rarely write the file by hand. pt vectorize, from plank-replay, builds a direction from two prompt sets (or from the difference between a model and a modified copy of it) and stores it under the name you give with -n, and pt install <repo>:<path> merges a vectors file someone else published into yours, asking before it replaces a direction of the same name. Both write the file in place through a temporary copy, and keep any fields they do not recognise. One such field is yours to add: a direction's optional emoji is how the status bar marks it while it steers, as 📖 ffn 2, with the direction's name standing in when it has none.

Holding the edit until your first message keeps the cached prompt unsteered, so a steered run reuses the same prompt checkpoint as an unsteered one. An attention edit cannot be held back that way, so a non-zero --dir-steering-attn means all.

Inside a session, /steer lists the model's directions with the loaded one starred, /steer <scale> changes the feed-forward scale on the spot (name the direction as well when the model has more than one), and /steer <name> [scale] switches to another direction. When you launch without --dir-steering, plank loads the model's first direction at scale 0, which changes nothing until a /steer turns it up. Switching to another direction swaps its vector into the running model, so it applies to the tokens generated next without a reload; the conversation so far keeps the activations the old direction produced. On an engine that cannot swap a vector live, plank restarts into the new direction instead and resumes the session where you were.

A profile can carry a direction too: a steering block pairs one with the profile's recommendedModel (see Profiles), and a --dir-steering on the command line overrides it, scales included.

Steering is a feature of the native DeepSeek and Qwen engine. The Gemma engine, --remote hosts and --provider models ignore it. The direction plank loads is decoded once into ~/.plank/cache/steering/, named by a hash of its contents, so two names for the same vector share one file. The old --dir-steering-file PATH, and a steering block on an engine in engines.local.json, are refused with a pointer to their replacements.

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

Environment variables

Next: Extending plank →

Conversation prefix

--prefix-file PATH (or a profile's prefix) reads a file of scripted turns and places them between the system prompt and the conversation, as if that exchange had already happened. The model then continues in the manner the turns demonstrate, which a local model follows more reliably than a rule stated in a prompt:

USER: Write terse answers.
This line is still part of the user turn.
ASSISTANT: Understood.
USER: Return code without an introduction.
ASSISTANT: I will return only the code.

A marker starts a turn only at the beginning of a line; the file must start with USER:, alternate, and end with ASSISTANT:, or plank refuses to start and says which line is wrong. The turns are read once at launch, are never saved with a session or compacted, and apply to whatever session the run starts or resumes. The format is ds4's --prefix-file.