Skip to main content

Configuration reference

Every key fencepost understands, with its type, default, and how it merges across config layers. For guided introductions, see the Configuration section; this page is the complete map.

JSON Schema​

A machine-readable schema ships with fencepost at schema/fencepost.schema.json and is published at https://ch4nn0n.github.io/fencepost/fencepost.schema.json. Point your editor at it for completion, hover docs, and validation — with the YAML language server (VS Code YAML extension, coc-yaml, …), add a modeline at the top of your config:

.claude/fencepost.yaml
# yaml-language-server: $schema=https://ch4nn0n.github.io/fencepost/fencepost.schema.json
import:
- claude
default: ask

Resolution order​

fencepost loads the first layer that exists; later layers are not consulted:

  1. {project}/.claude/fencepost/config/*.yaml — project conf.d directory, merged alphabetically
  2. {project}/.claude/fencepost.yaml — project single file
  3. ~/.claude/fencepost/config/*.yaml — user-level conf.d directory
  4. ~/.claude/fencepost.yaml — user-level single file
  5. Built-in defaults (no config is not an error)

Presets named in import: are merged first, as a base; the host config is applied on top. A present-but-broken config file records an error and the run fails closed (deny). Run fencepost config to see the sources, issues, and effective config.

Top level​

import: [claude, git]   # presets to layer in as a base
default: ask # fallthrough decision
onError: ask # posture when a command can't be checked
tools: { ... }
guidance: { ... }
redirect: { ... }
secrets: { ... }
KeyTypeDefaultMergeNotes
importlist of preset names[]n/aBare identifiers only ([a-zA-Z0-9_-]+), resolved against the bundled presets. all expands to every bundled preset; user pulls in your user-level ~/.claude config as a base layer. Nested imports (inside a preset or the user-level file) are ignored.
defaultallow | deny | askaskset-winsDecision when no rule matches. The last explicitly set value wins; a layer that omits default inherits it (mirrors onError).
onErrorallow | deny | askaskset-winsUsed when fencepost runs but can't reach a decision (e.g. unparseable Bash). A broken config always fails closed regardless. See Failure posture.
toolsobjectsee belowper-fieldTool and Bash rules.
guidanceobjectsee belowblock last-winsSessionStart guidance.
redirectobjectsee belowblock last-wins/tmp sandbox redirection.
secretsobjectsee belowfield-levelSecrets scanning.
meta{title, description}—n/aPreset metadata for the docs catalog; ignored at evaluation time.

tools​

See Tool rules.

KeyTypeDefaultMergeNotes
tools.denylist of {tool, description, alternative?}[]concattool is a name glob (e.g. mcp__dangerous_*); description/alternative are shown to the model.
tools.asklist of name globs[]concatRequire user approval.
tools.allowlist of name globs[]concatAllow without prompting. Listing Bash here has no effect — Bash always goes through the bash pipeline.

tools.bash​

String and regex rules over the normalised command — see Bash rules.

KeyTypeDefaultMergeNotes
bash.normaliselist of {prefix, strip: [regex]}[]concatStrips noise (e.g. -n <ns>) from commands with the prefix before any matching.
bash.denylist of command prefixes[]concat
bash.checkslist of {test: regex, description, alternative?}[]concatSmart deny: regex over the whole normalised command.
bash.allowCheckslist of regexes[]concatSmart allow: regex over the whole normalised command, so an anchored pattern can confine an allow to a path. Evaluated above ask/allow.
bash.asklist of command prefixes[]concat
bash.allowlist of command prefixes[]concat
bash.discourageChainingbooleantrueset-winsDeny &&/;/|| chains that would need approval, with guidance to run the parts separately. Pipes and control-flow constructs (if, for, while, ...) are exempt: any control-flow node exempts the whole command. See Guidance & chaining.
bash.offerManualRunbooleantrueset-winsOn deny, offer the verbatim command for the user to run via ! <command>.
bash.redirectslist of redirect rules[]concatSee below.
bash.argumentslist of argument rules[]concatSee below.
bash.interpretersmap keyed by python / javascript{}per-languageSee below.

bash.redirects[]​

Structured rules over redirection targets (>, >>, <) — see Structured bash rules.

FieldTypeRequiredNotes
moderead | write | append | anyyesWhich redirections the rule applies to.
outsidelist of rootsexactly one of outside/globFires if the target is outside all roots.
globpath globFires if the target matches.
decisionallow | deny | askyes
description, alternativestringnoShown to the model when the rule fires.

bash.arguments[]​

Rules that reason about every argument of a command, not a prefix.

FieldTypeRequiredNotes
commandcommand-name globyese.g. "rm|rmdir|mkdir".
anyArgOutsidelist of rootsexactly one predicateAny path-like arg outside all roots.
allArgsInsidelist of roots≥1 path-like arg, all under some root.
anyArgMatchesregexAny raw arg matches.
allArgsMatchregexEvery raw arg matches.
decisionallow | deny | askyes
description, alternativestringno

bash.interpreters.<lang>​

Inline interpreter analysis (python -c, node -e, heredocs) for python and javascript — see Nested interpreters. Merge: names union, calls/imports concat, writes last-wins.

FieldTypeNotes
nameslist of stringsBash command names that invoke this interpreter, e.g. [python, python3].
callslist of {match, argMatches?, pathArgsOutside?, decision, description?, alternative?}match is a qualified callee glob (shutil.rmtree, subprocess.*); argMatches narrows to calls whose argument text matches the regex; pathArgsOutside fires only when a string path argument is outside all roots.
importslist of {match, decision, description?}match is a module-name glob.
writes{outside: [roots], decision, description?, alternative?}Sugar for "a file is opened for writing" outside the roots.

guidance​

SessionStart guidance injected into Claude's context — see Guidance & chaining. The whole block is last-wins on merge.

FieldTypeDefaultNotes
enabledbooleantrueEmit SessionStart context at all.
includeDefaultsbooleantrueInclude fencepost's built-in guidance lines.
extralist of strings[]Additional lines appended after the defaults.

redirect​

Tool-input redirection — see The sandbox. Off by default; the claude preset turns it on. The whole block is last-wins on merge.

FieldTypeDefaultNotes
tmpbooleanfalseRewrite bare/prefixed /tmp paths in tool inputs to tmpTarget.
tmpTargetstring/tmp/claudeDestination directory.

secrets​

Secrets scanning — see Secrets protection. Off by default; the secrets preset turns it on. Merged field-by-field (a preset's enabled: true survives a user config that only adds allowlist entries); the allow lists concatenate.

FieldTypeDefaultNotes
enabledbooleanfalse
scannerauto | gitleaks | betterleaks | trufflehog | detect-secretsautoauto probes PATH in preference order; a name pins one scanner.
scanInputsbooleantruePreToolUse: deny tool inputs that contain secrets.
scanOutputsbooleantruePostToolUse: redact secrets from tool output.
inputToolslist of tool names[Write, Edit, NotebookEdit, Bash]
outputToolslist of tool names[Read, Bash, Grep, WebFetch]
allow.pathslist of path globs[]File inputs exempt from scanning (e.g. .env.example).
allow.ruleslist of <scanner>:<ruleId> globs[]Findings to ignore (e.g. gitleaks:generic-api-key).
maxScanBytesnumber > 05242880 (5 MiB)Content larger than this is not scanned.
timeoutMsnumber > 010000Hang ceiling per scanner invocation.

Validation behaviour​

Config problems come in two severities, both reported by fencepost config:

  • Errors (wrong top-level shape, invalid default/onError, unreadable file, YAML parse failure) — the config fails closed: everything is denied until fixed.
  • Warnings (a malformed rule, an invalid regex, an unknown scanner name) — the offending rule is skipped; the rest of the config still applies.

Unknown keys are ignored at runtime, which is exactly why editor validation via the JSON Schema is worth setting up: a typo like dney: silently does nothing otherwise.