How configuration works
docs/ai/config.md is the file that steers how the project is worked on. It is a set of Markdown tables, one section per topic. init fills in the values from what it asked or detected; you change them any time. Nothing needs a rebuild: the session-start hook reads the file and reports what changed since the last sync. Every key with its allowed values is listed in the configuration reference; this page explains what the groups are for. /act-config shows and sets these values without a model turn, see Changing the file.
Groups
Section titled “Groups”- Project: name, owner,
language-chatandlanguage-docs,stack, the lint/typecheck/testcommands(optionally a fourth for the full or E2E suite, run before a push), thetoolsyou use and themode(soloorteam, see Work entries).language-chatis the language the assistant talks to you in (autofollows your messages);language-docsis the language of everything it writes underdocs/..act/stays English either way. A command set to(not set)skips the matching check before a commit.runis the command that starts the application;(not set)means none is recorded. - Scope:
profile(minimal,standardorfull; a missing key counts asfull;initwritesfullfor a web project andstandardfor any other,--scopedecides otherwise, andupdatenever changes it) andexclude(noneor a comma-separated list) trim the template per project:standardleaves out the web, design and teaching skills,minimalkeeps only the core skills and roles (act-packagesis one of them), andexcludenames single skills, roles, rule files such asorchestrator/30-cost.md, or topics on top. The session start removes the copies of what is left out, switches the import line of an excluded rule file indocs/ai/rules.mdto a bare path (Claude Code stops loading it) and says so in one line; a change takes effect from the next session.shared/10-safety.mdcannot be excluded, and the checks stay on either way. To undo it, setprofiletofullandexcludetonone.methods(noneby default, or a comma-separated list oftest-first,spec-firstandsimple-changes) switches on working methods: rule sets for how the assistant works, from.act/methods/or your own indocs/ai/local/methods/. The session start,act-updateandpython .act/scripts/rules.py --sync-methodswrite each named method intodocs/project/coding_rules.mdas an imported set, so the orchestrator and every worker load it, and a single group can be unchecked there;initasks once andact-doctorreports a name without a file or a section that no longer matches the row. The skill and role lists are in the configuration reference. - Board:
boardchooses where the generated board goes (docs,shared,local);board-otherstoggles the section for tasks assigned to other people. - Inbox:
inbox-decisionsdecides where an open decision waits. Withimmediateit goes into the inbox as soon as it is booked; withat-starta backlog entry may keep it until work on it starts.quick-capture(onoroff, defaulton) lets theUserPromptSubmithook file a chat message that begins withtodo:,note:oridea:without a model turn, see Work entries. - Output depth:
output-depth(verbose,normal,sparse) controls how much the assistant writes in chat, not what your tool displays. - Session length:
context-hint(a token count, default 180000, oroff) is the context size at which the assistant suggests/clearor a new session at the next task boundary. Before it says “now/clear”, the assistant checks the handover itself (handover.py); there is no sentence to copy, and after/cleara bare “continue” picks up from the board.session-name(project,autoor any other text, defaultproject) sets the Claude Code session title at start, resume and fork:projectuses the project’sname(else the folder name), so a Remote Control session on the phone shows which project it is;autoleaves it to the tool; other text becomes the title. A title set with/renameorclaude -nis never overwritten.task-wait-hours(default 12) is how long a started task may stay quiet before it counts as waiting.board-at-start(onoroff, defaulton) adds an excerpt of the board to the session start.artifacts(onoroff, defaultoff) set tooffkeeps Claude Code from loading theArtifacttool, about 13,700 tokens saved per session start. - Teaching:
teach-lessons(local,docs) sets whereact-teachkeeps its lessons:localunder.act-local/learn/for you alone,docsversioned underdocs/learn/for the team. The learning record stays local either way. - Dependencies and Docs audit:
dependency-checkanddocs-audit-duecontrol the reminders to runact-depsandact-audit-docs. New projects getdependency-check: regularly: the session start notes once that noact-depsrun is on record yet, then again whenever the last one is older than 30 days.onceinstead files a single inbox entry afterinit; values already set stay. - Update:
update-channel(releaseorlatest, defaultrelease) chooses whatact-updatebrings:releaseonly the newest stable release tag of the template source,latestthe tip of its default branch. The session start announces a new release (onlatest: a newer tip), and/act-versionshows three lines (installed, newest in the channel, whether an update is available),/act-version --allthe full list (update.py --versions) with the releases and what an update would take. The announcement is not a one-off: the daily check records it, the session start repeats it at every start, the board lists it under Status and Claude Code’s status line showsupdate: 2.4.0(onlatest:update: <date>) until the update is installed.--versions,--planand an update run refresh the note or clear it when the project is up to date.update-checkswitches the note off.initasks for the value;act-doctorreports an invalid one. A source without release tags is followed at its tip, with a note. The daily check’sgit ls-remoteallows only thefile,git,http,httpsandsshprotocols; a source behind another remote helper (such asext::) gets no note at session start,act-updateitself is unchanged.advisory-check(onoroff, defaulton) lets the same daily check ask the template source for warnings about template versions with a known serious problem; those that match your installed version show at session start;criticalones also in the status line (⚠ A<n>), right below the board title and once as an inbox todo (a todo that was done and deleted is looked up in the git history, read only and within a few seconds, so another workstation does not file it a second time). They stop when an update brings a version outside the affected range, when the files the advisory names no longer hold the faulty text, or when you acknowledge them (say “warning acknowledged”, or runpython .act/scripts/advisory.py --ack A<n>).offasks and shows nothing;update-check: offstops the lookup too;advisory.py --statusshows the state. See Update channel. - Packages:
packages-unverified(block,scanorallow, defaultblock) decides whatpackages.pydoes with a package that has no valid signature of the template author; a signature that does not match is always refused.packages-sourceslists wherepackages.py fetch <id>looks (anhttps://address or a folder with anindex.json), andpackages-update(askoroff, defaultask) letsact-updateoffer every installed package with a newer version, see Update. - Archive:
archive-compact(<n>d <n>oroff, default30d 300) says when the session start notes thatact-compactis due: the oldest entry in the archive or journal folder is older than that many days, or the folder holds more than that many files.act-compactonly merges, word for word; the former keyarchive-shortenis gone and a value left in a project is passed over. A finished entry is always moved to the archive and nothing leavesdocs/before it stands in its monthly file. The former keydone-entriesandentries.py purgeare gone: a leftoverdone-entriesrow is ignored and the update removes it, and apurgecall only prints a notice. See Work entries. - Formats: how the assistant words what it writes.
commit-format(auto,conventional,plain),changelog-format(keep-a-changelog,at-release),release-notes-format(standard,changelog-copy) andreadme-format(standard,with-toc,minimal) each pick a preset from.act/formats/; a filedocs/project/formats/<name>.md(commit.md,changelog.md,release-notes.md,project-readme.md) replaces the template’s format for that subject completely and wins over the row.changelog(file,release-notes-only,off; defaultfile) decides whether the project keeps aCHANGELOG.mdin its root:initcreates it with an empty## [Unreleased],act-updateoffers it once to an older project, and neither writes over an existing file or adds a second one next to a changelog under another name. With the default formatact-commitadds a line under[Unreleased]for every commit with a visible effect and keeps the section’s one-sentence head line current;at-releaseleaves that toact-release. An existingconfig.mdhas no Formats section until you add it by hand from.act/skeleton/config.md. See the configuration reference. - Git hosting:
target-branch,forgeandforge-hosttell the pull-request skill where to go. github.com and gitlab.com receive the token without being named; a self-hosted host only after you have named it. - Checks: mechanical guards that run before an action (below).
- Logging:
loggingandlog-levelwrite every agent action toai.logat the project root, not versioned, handy to follow along in a second terminal. - Feedback: voluntary feedback to the template author; new projects start with
feedback: confirm, so nothing is sent without your yes.feedback: localmakes the project never send anything to the template author:feedback.py --send,--directand--addrefuse, reminders never fall due, and a template bug, a hand-writtenfeedback: <text>or a recurring finding becomes a backlog entry in the project instead. See Sending feedback. - Tips:
tips(never,occasionally,regularly) controls how often the session start shows a tip. Your own reminders indocs/ai/local/reminders.mdare not affected. - Roles: per-role (and per-skill) overrides of tier and reasoning, and of the Copilot models, see Tiers and reasoning.
Checks: block, warn, off
Section titled “Checks: block, warn, off”Each row of the checks table names a guard that runs before the action it describes, for example a commit, a write under .act/, or a worker leaving its write scope.
| Value | Effect |
|---|---|
block |
the action is refused |
warn |
the action goes ahead with a note |
off |
the check is skipped entirely |
A check marked in the table as “never refuses” treats block as warn. One check is different: security-check takes off, local, deps or full, see The security check.
A spent time limit or a crash is never a pass: a check that can refuse refuses the call when it runs out of time or breaks (in warn mode it notes) and names the row that switches it off (<row>: off); run the command again. A check that never refuses says “incomplete” instead of staying silent.
Turning a check down is your decision. Checks such as secret-scan or git-reset-hard protect against things that cannot be undone; lower them only with a reason.
secret-scan holds a commit whose staged diff contains a key or token pattern. A line that carries an act:allow-secret comment is exempt. For a file that cannot hold comments (JSON), list the line in docs/ai/local/secret-accepted.md as - <path> <hash>: <reason>; the hold message prints the finished entry (path and a line hash, never the value). A changed line, the same line in another file, or a missing or unreadable list is held again. The override hashes that doctor --accept writes into .act-lock.json at the project root (a rule ID as key, exactly 64 lowercase hex digits as value, nothing else on the line) are not held. What each check recognises and where its limits lie is on the checks page.
protected-watch (block by default; warn or off) watches the files that R-safe-git-metadata protects (git hooks and the config keys that start code, Claude settings, agents, skills and commands, Copilot role files under .github/agents/, .mcp.json, .envrc, .devcontainer/**, .vscode/tasks.json): after every tool call it compares them with a snapshot from the session start, so it also sees a change made by a script file or inline code that the static check git-metadata-guard cannot read. At block, a change made in a worker’s call is put back at once and the changed version is kept under .act-local/protected-watch/kept/; a change by the orchestrator is only reported, with the command that puts the previous version back. At warn, every change is only reported. Claude Code’s own “always allow” entries in settings.local.json are left alone and only reported. It reports after the call and prevents nothing; its limits are on the checks page.
model-switch (warn by default, off skips it; it never refuses) tells you when a worker or the session itself continues on another model, typically after the safety filter refused a request, which Claude Code does not announce in a sub-agent: at SubagentStop and Stop the orchestrator is told with its next tool call, naming the role and the models, and tells you in chat. The hook itself shows you nothing, because Claude Code records the message of these events without displaying it.
outside-root keeps reads and writes inside the project root and its allowed places, for the assistant and its workers alike. It starts at block in new projects; a project without the row runs it as warn. Exceptions go into outside-root-allow: paths relative to the project root, starting with ~ or absolute, each optionally followed by (read). An absolute entry outside the project and your home folder, such as a browser’s program folder (D:/Program Files/Browser), is read-only like (read) (one with a glob character stays writable unless (read) follows it): the assistant may read and start programs below it, and the writes the check recognises are refused. A file: entry is ignored, and a file: URL in a command is read as the path it names. Both rows are described in the configuration reference, the rule in R-safe-outside-root.
secret-read-allow (none by default) lists files secret-read may let through although they look like secrets: relative to the project root, starting with ~, or absolute, with a * only inside the last part of the path. Every other secret file stays refused. Only you write this row; a package cannot set it.
docs-order (warn by default) checks that the project docs stay findable under R-docs-order: every folder under docs/project/ with five or more entries has a README.md with one line per file and subfolder. The doctor reports a missing or stale index line, a dead link and a concept that has already been decided. It also notes, without refusing, a docs/project/ file of 300 lines or more (split it into a folder with a README.md) and a docs/README.md index line that points below a subfolder (it belongs in that folder’s README.md). move_doc.py moves a document and pulls links and the index line along.
cd-git (block by default; warn or off; runs only when tools holds claude-code) refuses a Bash call that chains cd or pushd with git, because Claude Code asks you for approval each time for that combination, and names git -C <folder> <command> in a call of its own instead. warn names the way and lets the call pass.
commit-hashes (warn by default, off skips it; it never refuses) notes a commit hash in backticks that no repository knows, in a commit message or in a line added to a staged journal file. A template commit recorded in .act-lock.json counts as known, so the base-commit change an update journals gives no note. commit-hashes-repos lists further repositories to look in (none, or comma-separated paths such as ../agentic-coding-template), for a journal that names commits of another repository (R-work-evidence).
throwaway-place (warn by default, off silences it; it never refuses) notes, in the main session only, a command or file write that puts throwaway output in the system temp directory or directly under .act-local/, and names .act-local/tmp/<task-id>-<slug>/ or .act-local/tmp/<YYYYMMDD>-<slug>/ instead (R-work-throwaway). All three rows are in the configuration reference.
changelog-length (warn by default, off skips it; it never refuses) makes act-doctor name an entry under [Unreleased] in CHANGELOG.md that is longer than 250 characters, with its first words.
own-rules-budget (default 6000 characters, off or 0 skips it) keeps your own rules short. act-doctor warns when the “Own rules” sections of docs/ai/rules.md and docs/project/coding_rules.md together exceed it, names the size and up to five lines that read like history (a date, an entry identifier, “formerly … since …”) with the hint to send what of them would help every project as feedback (act-feedback), and never blocks. The “Own rules” section of the coding_rules.md scaffold has a table of where each kind of rule belongs.
own-rules-review (warn by default, off skips it; it never refuses) has two parts. act-doctor names a local skill that overrides a template skill of the same name until you keep it with python .act/scripts/doctor.py --accept skill:<name> (a kept one shows as stale when the template skill changes). After an update, act-update sets the new and changed rules and skills against your own rules, overrides and skills in one inbox question: drop, keep or adapt; nothing is deleted.
act-local-tidy keeps .act-local/ small. At session start, at most once a day and in a background process, it removes tmp/ entries and unknown entries directly under .act-local/ (none that a template script creates) that are older than 7 days and whose name does not start with an open task’s id, all but the newest 5 backups of update, and compiled-module files under .act-local/pyc/ that belong to another Python version than the running one and are older than 7 days. The next session start reports count, size and kinds; it names only entries that could not be removed. The first run in a project only reports what it would remove; removal starts on a later day, after a session start has shown that report. warn only reports, off skips it. act-local-keep lists patterns relative to .act-local/ (for example exports, tmp/long-*) that are never removed, or none. python .act/scripts/act_local_tidy.py shows the plan without removing anything. The rule behind it is R-work-throwaway.
Ignore files and what the checks are not
Section titled “Ignore files and what the checks are not”There is no .claudeignore: Claude Code skips such a file without a word. Its Glob and Grep tools already leave out what .gitignore excludes, node_modules and build folders included, so the template adds no ignore file of its own. permissions.deny with Read(...) rules reaches Claude Code’s own file tools, but a shell command only where its sandbox is switched on. A targeted, bounded look into a library’s source (grep -n … | head) stays allowed; it is often how a bug in a dependency is found (R-work-bounded-output). Secret files are refused by secret-read, in shell commands too, within the limits its rule names (R-safe-no-secret-read). The checks are guard rails against mistakes, not a sandbox: neither an ignore file nor a deny rule on its own keeps an agent, or text injected into its prompt, from reading a file through the shell. That takes isolation outside the agent, such as a container or the tool’s own sandbox. Which switches the tools offer for that, and where they stop, is in the Isolation guide.
File and environment
Section titled “File and environment”config.md describes the project and is versioned. Secrets and per-machine or per-run deviations belong in the environment (for example AGENTIC_FEEDBACK_URL or ACT_FORGE_API_URL), which overrides the file for that run and never the other way round. The session start names every environment override that is active, names only, never values.
Changing the file
Section titled “Changing the file”/act-config lists every setting, /act-config <key> shows one with its allowed values, its default and when a change takes effect, and /act-config <key> <value> writes the value into that one table cell. Nothing is committed and the rest of the file stays byte for byte. In Claude Code the UserPromptSubmit hook answers the command; elsewhere run python .act/scripts/config.py [<key> [<value>]]. The Roles table is shown but edited by hand.
By hand, edit the values in the tables, not the key names or the marks (<!-- act:... -->): those are what the mechanism reads. An update keeps your values. act-doctor checks the value of every key that has a fixed list or format and reports an invalid one as config-value. If the project changes in a way config.md describes, the assistant updates it in the same step.