Configuration

@katforge/imp reads two files. Machine settings live in your home directory and hold the things that are true of you — which AI backend to use. Project settings live in a .imp file at a repo's root and hold the things that are true of the project — where its docs live, which commit types its changelog skips. Machine settings are private and per-developer; .imp is checked in and shared.

Machine settings

imp config writes ~/.config/imp/config.json, or $XDG_CONFIG_HOME/imp/config.json when XDG configuration is set.

{
  "provider": "claude",
  "model:fast": "haiku",
  "model:smart": "sonnet"
}

IMP_AI_PROVIDER, IMP_AI_MODEL_FAST, and IMP_AI_MODEL_SMART override the file. Run imp doctor after configuration. Claude uses the installed Claude CLI; Ollama uses the local service and keeps diffs on the machine.

Project settings: the .imp file

A .imp file at a repo's root declares how @katforge/imp should treat that project. It is JSON — the same format and colon-namespaced key grammar as the machine settings, so there is one parser and one mental model — and it is meant to be committed, so every developer and every CI run reads the same rules.

Run imp setup to write it interactively. Every key is optional, so a .imp only needs the settings a project actually overrides.

{
  "changelog:skip": [ "chore", "release", "merge" ],
  "docs:include": [ "reference", "hearth" ],
  "docs:mode": "reconcile",
  "docs:path": "../docs.example.com/content",
  "docs:release": false
}

Key	Purpose	Default
docs:path	Where this project's docs live, relative to the repo root. May point at a sibling repo. Required for docs sync.	—
docs:include	Subfolders under docs:path @katforge/imp may touch. Omit to consider every markdown file.	all markdown
docs:mode	reconcile adds docs for new surface and corrects statements the code contradicts; additive only adds.	reconcile
docs:release	Run documentation sync during imp release, over the released commit range.	false
changelog:skip	Commit types dropped from changelog entries.	chore, release, merge

The docs:* keys drive documentation sync; changelog:skip is used by the changelog. The smallest useful .imp is a single line — the docs path — with every other key taking its default:

{ "docs:path": "../docs.example.com/content" }

How settings combine

The two files are separate scopes, resolved independently:

• Machine settings (~/.config/imp/config.json) choose the AI backend and models, and are overridden by the IMP_AI_* environment variables.
• Project settings (.imp, read from the repo root) shape what @katforge/imp does in that repo — its docs and changelog rules.

Requirements

• Python 3.10+
• git
• gh (optional, for fix, pr, and GitHub releases)
• An AI backend: the Claude CLI or a running Ollama instance

No API key is required for Ollama.