settings.json

Where the file lives

.claude/settings.json

This is a Claude Code file, not a bassclef file. bassclef writes to it (via the sync hook) but the harness owns it. Adopters should treat it as bassclef-managed — read to understand what fires when, edit through bassclef's promote path when you want a change to propagate.

What each block controls

permissions.additionalDirectories

Directories Claude Code can read outside the current repo. bassclef uses this to load its substrate from a sibling checkout.

Sample from bassclef-web:

{
  "permissions": {
    "additionalDirectories": ["../bassclef"]
  }
}

Every path in this list must exist. Adding a bad path produces silent Read failures. Keep this list short; grant only what bassclef needs.

hooks.SessionStart

Fires every time a Claude Code session starts. bassclef uses this to sync substrate from upstream (if enabled) and to check for BLOCKED items from prior sessions.

Two hooks fire in order:

• $CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh — the project-scope sync entry point (thin pointer)
• $HOME/.claude/hooks/bassclef-sync.sh — the operator-scope sync fallback (installed by bassclef)

Timeout: 30 seconds each. Sync is fast under 5 seconds on a warm cache; the 30-second budget covers first-run tarball fetch on a slow network.

hooks.PreToolUse

Fires before every tool call. bassclef wires many hooks here — the sequence enforces safety, discipline, and adopter-facing prose quality before any tool actually runs.

Sample from bassclef-web (partial — bassclef ships around 30 PreToolUse hooks in total):

destructive-command-guard.sh       ← catches rm -rf, DROP TABLE, etc.
atomic-pr-check.sh                 ← one PR per WU rule
pre-gh-pr-body-scrub.sh            ← jargon check on PR body writes
pre-gh-pr-title-scrub.sh           ← jargon check on PR title writes
pre-git-commit-msg-scrub.sh        ← jargon check on commit messages
file-rename-discipline-check.sh    ← rename ships with migration entry
pre-commit-gate.sh                 ← temperance + diagnose + luminary gates
pre-gh-pr-body-closes-check.sh     ← PR body must Close a ticket
pre-gh-pseudonym-scrub.sh          ← operator-private pseudonym stripping
pre-gh-sibling-repo-scrub.sh       ← cross-repo reference discipline
type-check.sh                      ← TypeScript strict on Edit/Write

Each hook has a specific timeout budget. A hook that fires BLOCKED puts a structured message on stderr and exits non-zero; the tool call never runs until the block is resolved or explicitly deferred.

hooks.PostToolUse + hooks.Stop + others

Other lifecycle hooks fire at post-tool, session-stop, and other Claude Code events. See the file itself for the full list — bassclef adds hooks conservatively; every one should have a rule body in .claude/rules/ explaining why it exists.

When to edit

• Adding a project-specific hook — you have a check that bassclef does not ship. Add the hook file under .claude/hooks/ and register it in the matching lifecycle event array here.
• Extending additionalDirectories — you want Claude to read from a sibling repo (a shared design system, a canvas archive). Add the path. Keep it minimal.
• Adjusting a hook timeout — a hook is timing out on your machine. Bump the timeout AND file a /promote ticket so the substrate version gets updated.

When NOT to edit

• Do not remove bassclef-shipped hooks without a /promote ticket proposing the removal. The hook exists because a rule says so; removing the hook silently defeats the rule.
• Do not add hooks with unbounded network calls. Every hook runs on every relevant tool call; a slow hook multiplies across every session.
• Do not add permissions.allow for destructive tools without operator sign-off. The permission stack has security implications.

Sample — full file

The bassclef-web repo ships a settings.json with around 30 PreToolUse hooks, 3 PostToolUse hooks, SessionStart wiring, and Stop hooks. Read it in context:

.claude/settings.json

Related

• bassclef-configs.jsonc — adopter behavior config
• Substrate config (.bassclef-source.json) — sync source
• Directory layout — where each hook lives
• Failure-mode playbook — what to do when a hook fires unexpectedly