Skip to content

Configuration ​

.netherite/config.yml configures a workspace. Only version is required; everything else has a default, and unknown keys are kept. netherite init writes it with the defaults as comments. Changes are picked up by a running server; moving content needs a restart.

The app can change states, freshness, context and inbox.rules. It edits only the lines for those values, keeps your comments and unknown keys, refuses an edit if the file changed since it was read, and never commits: a change shows up as an uncommitted edit to this file. Every other key is changed by hand.

yaml
version: 1
content: netherite
id_padding: 5
states:
  - { name: backlog, category: todo }
  - { name: doing, category: active }
  - { name: blocked, category: blocked }
  - { name: done, category: done }
freshness:
  drifting: 1
  stale: 10
context:
  budget: 8000
  targets: [claude, agents]
KeyDefaultWhat it does
version(required)the config format; 1
contentnetheritefolder, relative to the repository, that holds the item folders
id_padding5digits in an ID: TASK-00042 at 5, TASK-0042 at 4
statesthe four abovethe states a task can be in, in column order. Each has a name and a category
states[].categorytodo, active, blocked or done
freshness.drifting1commits since review (touching covered files) before a doc is drifting
freshness.stale10commits before it is stale
inbox.rules.<rule>trueset to false to stop the Inbox raising that rule: stale-doc, proposed-adr, orphan, overdue-task, closing-commit, new-todo, similar-tag
context.budget8000tokens the synced context may use per file (an estimate: characters / 4)
context.targets[claude, agents]claude writes CLAUDE.md, agents writes AGENTS.md, mcp serves it over MCP only

Task state values are checked against states, so renaming a state means updating the tasks that use it (netherite lint lists them). A task's colour and its counting as done follow the category, so you can name states freely: { name: in_review, category: active }.

Files Netherite writes outside the content folder ​

PathWhyCommit it?
.netherite/config.ymlthis fileyes
.netherite/local/per-user state: the agent activity logno (init ignores it)
CLAUDE.md, AGENTS.mdthe synced context, between markersyes
.claude/skills/netherite-*agent skills, installed by inityes

MIT licensed. Nothing is sent anywhere: it runs on your machine.