Configuration

Files to copy into a fresh tree (.env, local config) are listed in the repository’s own .worktreeinclude (gitignore syntax, also read by Claude Code). Only gitignored files are copied; a symlink out of the repository is refused, nothing is written through a symlink, and nothing at the destination is overwritten.

[gates]

[gates.named.<name>]

[gates]
check   = ["cargo test --locked"]
timeout = "20m"
on_fail = "escalate"

[gates.named.bench]
run     = ["cargo bench --no-run"]
timeout = "5m"

A change is verified when the latest check report passed and its tree digest equals the working tree’s. A [gates.named] gate is evidence you ask for (devplane gate --name bench) and never makes a change verified; an undeclared name is an error. See Verified done.

[policy]

[policy]
never_auto = [
  "Bash(rm *)",
  "Read(./.env)",
  "WebFetch(domain:pastebin.com)",
]
always_ask = ["Bash(git push *)", "Bash(npm publish *)"]
max_parallel_runs = 3

Neither list grants anything; allow rules go in your agent’s own permissions.allow. The rule syntax is on Permissions.

[budget]

One budget per change. A change that passes any bound stops and raises a cost_spike item naming which one. Zero means off.

usd binds only an agent that reports its cost, which the Agent Client Protocol makes optional. Turns and runtime are counted by Devplane and bind every agent. devplane check warns when usd is the only bound, and devplane change show says not reported rather than $0.00.

[transcripts]

Off stores nothing, including the prompts Devplane sent. Sessions Devplane only watches carry no prose either way.

[spec]

[spec]
plans          = "specs"   # Kiro ".kiro/specs", OpenSpec "openspec/changes"
open_questions = ["NEEDS CLARIFICATION"]
tokens         = ["REQ-"]  # REQ-3 in heading and task line: one edge

• plans has no default. Unset, the Specifications view says not configured for this project.
• open_questions is matched per line, case-insensitively, outside code. Each project with an open question in a specification under way gets one inbox item naming the count.
• tokens replaces the default list. A prefix may not contain a digit; a repository that numbers requirements bare writes the word in front (tokens = ["Req "] matches Req 12). An empty list is an error.

See Specifications.

[questions]

[questions]
deadline = "4h"
hold     = true     # 30s; a duration names its own, up to 120s

By default only a person ends a question. A deadline that fires tells the agent no, and devplane audit names a timer as the authority, with the duration and this file. The clock runs only while a host is up. A value that will not parse fails devplane check and the wait stays unbounded.

hold applies only to calls your always_ask rules matched; a never_auto refusal is never held. The permission becomes an ask that devplane answer or the workbench can answer, with no host needed. If nobody answers, the ask ends with nobody as the authority and the vendor’s dialog appears. It does not fire in Claude Code’s auto mode, where no dialog would appear.

[review]

How devplane change review and the Review tab order a change. Nothing is inferred from file names. Checks weakened or changed always come first, before any role.

[review.roles]
shared      = ["src/schema.sql"]
logic       = ["src/core/**", "!src/core/auth.rs"]
security    = ["src/core/auth.rs"]
integration = ["src/clients/**"]
wiring      = ["src/cli/**"]
tests       = ["tests/**"]

[[review.covers]]
test  = "tests/auth.rs"
paths = ["src/core/auth.rs"]

Patterns are gitignore syntax, relative to the repository. A file takes the first role that matches; unmatched files follow, in path order. Without [review] roles the review says it is unordered. Without any [[review.covers]] the coverage column is absent, which is different from not covered.

[github]

[reports]

A report always reaches this project’s person in the inbox. A report from a project named here is also handed to the latest open change’s live agent, quoted and attributed, and recorded with authority rule. "*", empty names and unregistered projects are refused by devplane check. See Reports between projects.

Machine-wide files

All under ~/.devplane/ (or DEVPLANE_HOME).

policy.toml: never_auto and always_ask in a [policy] section, applied to every project. Only [policy] is allowed. max_parallel_runs and stall_timeout parse there but do nothing: they are read only from a project’s devplane.toml. A file that will not load fails closed, like a broken devplane.toml.

app.toml: the window of devplane app, and which GitHub this machine signs in to:

# ~/.devplane/app.toml
[app]
shortcut = "CmdOrCtrl+Shift+Space"   # the one global shortcut
port     = 47831                     # the host's port; 0 picks a free one

[github]
host      = "ghe.corp"               # the configured host; github.com unless set
client_id = "Iv1.…"                  # that host's OAuth App, for the device flow

[github.hosts."ghe.other"]
client_id = "Iv1.…"                  # another Enterprise server's own app

A client id is public (the device flow has no secret). A release build carries its own for github.com only; a host with none signs in with a token on stdin (devplane login github --with-token).

A missing file means these defaults. A file that will not parse, or a shortcut that cannot be registered, is reported by devplane doctor. The default, 47831, is the port devplane connect claude writes into the telemetry settings. With port = 0 the window’s host picks a new port each start and agent telemetry (cost, context) no longer reaches it.

agents.toml: agents added by name, beside the built-in ones. See Driving agents.

Environment

Something wrong or out of date? Edit this page.