Skip to content
/
Tier B A17 Compiled enforcement

DotForge

dotforge · luiseiman/dotforge · ★ 6 · last commit 2026-05-22

Declare behavioral policies for Claude Code and compile them into enforcing PreToolUse hooks, with cross-project audit and sync governance.

Best whenConfiguration declarations without compiled enforcement are theater — behavior governance requires hooks, not just CLAUDE.md.
Skip ifForce pushes, hard resets, clean -f, Writing without searching first
vs seeds
spec-kit's hooks are workflow decorators while DotForge's are behavioral enforcement mechanisms.…
Primitive shape 14 total
Commands 5 Hooks 9
00

Summary

DotForge — Summary

DotForge (v3.9.0, luiseiman/dotforge) is a Claude Code configuration governance tool that manages .claude/ directories across multiple projects. Its core value proposition is declaring runtime behavioral policies ("search before writing", "no destructive git", "verify before shipping") and compiling them into PreToolUse hooks that enforce a 5-level escalation (silent → nudge → warning → soft_block → hard_block) at session runtime. The behavior DSL (behaviors/index.yaml + per-behavior behavior.yaml) compiles to bash hooks in .claude/hooks/generated/ plus settings.json snippets. DotForge also provides a /forge audit command (scoring .claude/ quality 0-10 across 14 dimensions), /forge sync (propagating improvements across a registry of projects), and /forge init (zero-to-config in one command). State is maintained in .forge/runtime/state.json (counters, flags) and .forge/audit/overrides.log (override audit trail, git-tracked). It is distributed as a bash-script bundle cloned to ~/.dotforge, not an npm package.

differs_from_seeds: DotForge is the only framework in this batch that governs agent behavior through compiled runtime hooks rather than orchestrating spec-driven workflows. The closest seed is spec-kit (which also ships hooks — 18 of them), but spec-kit's hooks are workflow lifecycle decorators while DotForge's hooks are behavioral enforcement mechanisms with escalating severity levels. No seed framework provides cross-project config audit and sync governance.

01

Overview

DotForge — Overview

Origin

Published by luiseiman, v3.9.0, MIT license. Shell-based (bash). Actively maintained, tracking Claude Code releases closely — the README changelog is a meticulous record of Claude Code API/settings changes incorporated into DotForge's documentation domain. Last commit 2026-05-22.

Philosophy

From the README: "Behavior governance for Claude Code. Declare runtime policies on tool calls — 'search before writing', 'no destructive git', 'verify before shipping' — and enforce them via compiled PreToolUse hooks that share a session-scoped state file."

DotForge's manifesto distinguishes itself from simpler tools: "Other tools stop at configuration. dotforge governs behavior — and keeps auditing, syncing, and evolving your .claude/ setup across every repo you manage."

The core insight is that CLAUDE.md instructions are suggestions while compiled PreToolUse hooks are enforcement. DotForge compiles the gap between intent and enforcement.

Manifesto-style statements

  • "Other tools stop at configuration. dotforge governs behavior."
  • "Do not use dotforge if: you only have one small repo; you only want a CLAUDE.md generator; you do not care about sync, audit history, or cross-project consistency."
  • "Audit checklist item 14 fixed: scoring v3 behavior coverage now requires ENFORCEMENT (compiled hook under .claude/hooks/generated/ AND a settings.json reference), not just a behaviors/index.yaml declaration."
  • Runtime block example: "Bash(git push origin main --force) → PreToolUse:Bash hook returned blocking error → Destructive git operation blocked"

Target user

Individuals and teams managing multiple Claude Code projects who want consistent behavioral policies, auditable configuration quality, and cross-project config synchronization.

02

Architecture

DotForge — Architecture

Distribution

  • Bash script bundle (clone to ~/.dotforge)
  • No npm package, no Homebrew formula — pure bash

Install methods

# One-liner install
curl -fsSL https://raw.githubusercontent.com/luiseiman/dotforge/main/install.sh | bash

# Manual
git clone https://github.com/luiseiman/dotforge.git ~/.dotforge
export DOTFORGE_DIR="$HOME/.dotforge"
$DOTFORGE_DIR/global/sync.sh

Tech stack

  • Primary language: Bash (POSIX shell, macOS/Linux/WSL)
  • Optional: python3 (for compact-filter.py, dev-tui.tsx), jq (for hook support)
  • Behavior compilation: YAML → bash hooks + settings.json snippets

Directory structure

~/.dotforge/
├── behaviors/
│   ├── index.yaml
│   ├── no-destructive-git/behavior.yaml
│   ├── search-first/behavior.yaml
│   ├── verify-before-done/behavior.yaml
│   ├── respect-todo-state/behavior.yaml
│   ├── plan-before-code/behavior.yaml (opt-in)
│   └── objection-format/behavior.yaml (opt-in)
├── hooks/
│   ├── block-destructive.sh
│   ├── detect-claude-changes.sh
│   ├── hooks.json
│   ├── lint-on-save.sh
│   ├── session-report.sh
│   └── warn-missing-test.sh
├── commands/
│   ├── audit.md
│   ├── debug.md
│   ├── forge.md
│   ├── health.md
│   └── review.md
├── scripts/
│   └── compact-filter.py
├── agents/
├── practices/
├── registry/
│   └── projects.local.yml (gitignored — real registry)
├── stacks/
│   └── trading/rules/backtesting-adr-gate.md
├── template/
├── global/
│   └── sync.sh
├── docs/
│   ├── v3/SPEC.md, SCHEMA.md, RUNTIME.md, MIGRATION.md
│   └── domain/  (hook-architecture.md, hook-events.md, etc.)
├── .forge/
│   ├── runtime/state.json
│   └── audit/overrides.log
└── install.sh

Required runtime

  • bash (macOS, Linux, WSL)
  • git
  • Optional: python3, jq

Behavior DSL compilation pipeline

behaviors/<name>/behavior.yaml
  ↓ (compile)
.claude/hooks/generated/<name>.sh
  ↓ (observe)
.forge/runtime/state.json
.forge/audit/overrides.log
03

Components

DotForge — Components

Claude Code Commands

Command Purpose
/forge Main router: behavior list/describe/status/on/off/strict/relaxed, audit, sync, init, bootstrap, context-status, compact-task
/forge audit Score .claude/ configuration quality (0-10) across 14 dimensions
/forge sync Propagate improvements from dotforge template to registered projects
/forge init Zero-to-config in one command
/forge bootstrap Full interactive setup
/health Health check
/debug Debug mode
/review Code review

Behavior catalog (v3)

Behavior Category Default Description
no-destructive-git core on Block force push, hard reset, clean -f, forced branch delete
verify-before-done core on Require verification before claiming complete
respect-todo-state core on Respect TODO markers
search-first core disabled (false-positive issues) Search before writing
plan-before-code opinionated opt-in Plan before coding
objection-format opinionated opt-in Enforce objection format

Hooks

Hook Event Trigger Purpose
block-destructive.sh PreToolUse Bash Block destructive git operations (hard_block)
lint-on-save.sh PostToolUse Write|Edit Lint on file save
warn-missing-test.sh PostToolUse Write|Edit Warn when tests missing
session-report.sh Stop (all) Generate session metrics JSON
detect-claude-changes.sh Stop (all) Detect .claude/ changes for auto-stub
pre-session-check.sh Setup init|maintenance Validate settings.json, hook executables, behaviors/index.yaml
session-startup.sh SessionStart (non-compact) Capture branch, HEAD, working-tree drift
compact-filter.py PreCompact (via UserPromptSubmit) Smart auto-compact filter
pre-compact-warning.sh UserPromptSubmit (always) Warn at 80%/90% context fill

Scripts

  • scripts/compact-filter.py — Python script that filters compact summaries, collapsing excessive fenced blocks
  • global/sync.sh — Cross-project sync script
  • install.sh — Installer

Session state files

  • .forge/runtime/state.json — counters, flags, per-session (TTL 24h)
  • .forge/audit/overrides.log — permanent override audit trail (git-tracked)
  • .claude/session/last-compact.md — smart auto-compact last result
  • .claude/session/compact-history/ — rotating last 5 compaction checkpoints
  • .claude/session/last-startup.md + startup-history/ — session startup snapshots

Registry

  • registry/projects.local.yml (gitignored) — real source of truth
  • registry/projects.yml — example/reference file
05

Prompts

DotForge — Prompts

Verbatim excerpt 1: no-destructive-git behavior.yaml

schema_version: "1"
id: no-destructive-git
name: No Destructive Git Operations
description: >
  Block force pushes, hard resets, clean -f, and forced branch deletions.
  Safety-critical — no override allowed.
category: core
scope: session
enabled: true

policy:
  triggers:
    - event: PreToolUse
      matcher: "Bash"
      conditions:
        - field: command
          operator: regex_match
          value: 'git\s+(push\s+[^|;&]*(--force\b|--force-with-lease\b|-f\b)|reset\s+--hard\b|clean\s+-[a-z]*f[a-z]*\b|branch\s+-[a-zA-Z]*D[a-zA-Z]*\b)'
      logic: all
      action: evaluate

  enforcement:
    default_level: hard_block

  recovery:
    hint: >
      Destructive git operations are blocked. Use safe alternatives: git revert,
      git stash, git reset --soft, or create a new branch.
    suggested_tool: Bash
    suggested_action: "git revert <commit>  # or: git stash"

rendering:
  block_reason: "Destructive git operation blocked: force push, hard reset, clean -f, and forced branch delete are not allowed."

applies_to:
  tools: [Bash]
  agents: []
  profiles: [minimal, standard, strict]

metadata:
  author: dotforge
  version: "1.0.0"
  tags: [git, safety, core]

Prompting technique: Machine-readable declarative DSL for behavioral policy, not a natural-language prompt. This YAML compiles to a bash hook. The recovery.hint field provides the human-readable message injected when the behavior triggers. The regex_match operator is a specific condition type in the behavior DSL.

Verbatim excerpt 2: /forge audit command context (from commands/audit.md)

The /forge audit command is a Claude Code slash command. The full content is at commands/audit.md but the key insight from the README describes the 14 audit dimensions:

  1. CLAUDE.md present and quality
  2. Error ledger (CLAUDE_ERRORS.md)
  3. Hook wiring (hooks in settings.json)
  4. Behavior declarations
  5. Compiled hooks present 6-13. Various configuration completeness checks
  6. v3 behavior coverage (requires ENFORCEMENT, not just declaration)

Prompting technique: Structured scoring rubric injected as a command prompt. The command instructs Claude to apply 14-dimension evaluation and return 0-10 scores per dimension.

09

Uniqueness

DotForge — Uniqueness & Positioning

differs_from_seeds

DotForge occupies a unique niche among all seed frameworks: it governs Claude Code configuration across multiple projects rather than orchestrating a specific development workflow. No seed framework provides cross-project config audit (14-dimension scoring), behavior compilation (YAML → bash PreToolUse hooks), or config sync governance. The closest seed is spec-kit (also ships hooks — 18 of them as workflow lifecycle decorators), but spec-kit's hooks are command decorators while DotForge's hooks are behavioral enforcement mechanisms with a 5-level escalation system. The permanent override audit trail (.forge/audit/overrides.log, git-tracked) has no equivalent. DotForge also maintains the most comprehensive domain documentation of Claude Code's API changes of any framework in the ecosystem.

Positioning

  • Category: Claude Code configuration governance and behavioral enforcement
  • User: Individuals and teams managing 2+ Claude Code projects who want consistent behavioral policies and auditable configuration quality
  • Integration: ~/.dotforge global install + per-project .claude/ management
  • Value: Compile-time guarantee that declared behaviors are actually enforced (not just documented)

Observable failure modes

  1. session-report.sh silent corruption bug: The README documents a 5-month silent bug where grep -c ... || echo "0" emitted "0\n0" on no-match, corrupting 54 JSON files across 12 projects. Fixed in v3.3.1 but illustrative of bash scripting fragility
  2. search-first behavior disabled: Generated false positives in sessions with prior context — disabled until sticky-flag mode is implemented
  3. Compile step required: Declaring a behavior without running the compiler provides no enforcement (audit dimension 14 catches this)
  4. TTL 24h state: Session state expires after 24h — behaviors reset between long pauses
  5. Bash-only: No Windows support without WSL

Cross-references

  • Tracks: Claude Code API (Claude Code v2.1.108–v2.1.143 changelog incorporated)
  • Complements: claude-skills (alirezarezvani, 248+ skills), gstack (garrytan), duthaho/claudekit
  • Parallel to: agent-os seed (both manage .claude/ configuration, but agent-os focuses on markdown standards while DotForge focuses on compiled behavioral enforcement)
04

Workflow

DotForge — Workflow

Bootstrap → Audit → Sync lifecycle

Phase Actor Action Artifact
1 — Install Human `curl ... bash`
2 — Init Human/Claude /forge init .claude/ bootstrapped in project
3 — Audit Human/Claude /forge audit Audit score (0-10 across 14 dimensions)
4 — Sync Human/Claude /forge sync .claude/ updated from dotforge template
5 — Behaviors Human Declare in behaviors/index.yaml Behaviors compiled to hooks
6 — Compile Compiler YAML → bash .claude/hooks/generated/*.sh + settings.json
7 — Runtime Claude Code PreToolUse / PostToolUse hooks Enforcement with escalation levels

Behavior enforcement escalation

Level Effect
silent Counter incremented only
nudge Informational context injected
warning Warning message in Claude's context
soft_block continue: true — logged but not hard-blocked
hard_block continue: false — execution blocked

Approval gates

None — behaviors are automatic enforcement, not human approval gates.

Phase-to-artifact map

Phase Artifact
Behavior declaration behaviors/index.yaml, behaviors/<name>/behavior.yaml
Compilation .claude/hooks/generated/<name>.sh, settings.json entries
Runtime enforcement .forge/runtime/state.json updated
Override .forge/audit/overrides.log appended
Session startup .claude/session/last-startup.md
Compaction .claude/session/last-compact.md, compact-history/

Key design: compile step is mandatory

"Audit checklist item 14 fixed: scoring v3 behavior coverage now requires ENFORCEMENT (compiled hook under .claude/hooks/generated/ AND a settings.json reference), not just a behaviors/index.yaml declaration." — Declaration without compilation does not count as enforced.

06

Memory Context

DotForge — Memory & Context

State storage (multi-layer)

Session-scoped state

  • .forge/runtime/state.json: Counters per behavior, flags, pending_block reinvocation detection. TTL: 24h. Uses mkdir-based locking to prevent race conditions.

Permanent audit trail

  • .forge/audit/overrides.log: Every override of a blocked operation is logged here. Git-tracked — provides permanent audit history that survives session resets.

Session startup snapshots

  • .claude/session/last-startup.md: Captures branch, HEAD, working-tree count, recent .claude/ edits (24h), pending TODOs, behaviors disabled at session start
  • .claude/session/startup-history/<ISO>.md: Rolling last 5 snapshots
  • Injected into context only when noteworthy drift is detected (branch change, modified files, etc.)

Compaction state

  • .claude/session/last-compact.md: Smart-filtered compact summary (via compact-filter.py)
  • .claude/session/compact-history/: Rolling last 5 checkpoints
  • The compact filter collapses fenced blocks >40 lines, dense runs ≥30 lines, triplicate paragraphs — never drops headings, paths, or decision/error/fix lines

Cross-session handoff

The session startup hook (session-startup.sh) explicitly compares the current session state against the last startup snapshot to detect drift and inject relevant context. This is structured cross-session handoff.

Context compaction

Active: pre-compact-warning.sh warns at 80%/90% context fill. compact-filter.py applies conservative filtering to compact summaries before persisting. Evidence-based threshold: 80% of context window (from academic + field research).

07

Orchestration

DotForge — Orchestration

Multi-agent support

No explicit multi-agent orchestration. DotForge governs a single Claude Code session's behavior.

Orchestration pattern

Event-driven: Claude Code lifecycle hooks (PreToolUse, PostToolUse, Stop, SessionStart, Setup, UserPromptSubmit) trigger enforcement.

Isolation mechanism

None. Operates in-place.

Multi-model support

No. DotForge is Claude Code specific.

Execution mode

Event-driven (hooks fire on Claude Code lifecycle events).

Subagents

None.

Crash recovery

Not applicable in the agent sense. .forge/runtime/state.json uses mkdir-based locking to prevent corruption on concurrent access.

The behavior enforcement loop

Claude Code executes a tool call
  → PreToolUse hook fires
  → Bash hook evaluates conditions against the tool input
  → If conditions match: increment counter, check escalation level
  → If level ≥ soft_block: inject warning/block message into hook output
  → Claude Code respects hook output (continue: true/false)
  → Override attempts logged to .forge/audit/overrides.log

Stop hook loop prevention

Claude Code v2.1.141+ caps Stop hooks that return decision: "block" at 8 consecutive blocks (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP). DotForge documents this anti-pattern explicitly.

08

Ui Cli Surface

DotForge — UI & CLI Surface

CLI binary

None as a standalone binary. DotForge is invoked via Claude Code slash commands (/forge ...) and bash scripts.

Claude Code command surface

Command Subcommands
/forge behavior list, behavior describe <id>, behavior status, behavior on <id>, behavior off <id>, behavior strict <id>, behavior relaxed <id>, audit, sync, init, bootstrap, context-status, compact-task
/health Health check
/debug Debug mode
/review Code review

Demo GIFs (from README)

The README shows three animated demos:

  1. forge init — zero-to-config in one command
  2. forge audit — score your project's configuration
  3. forge bootstrap — full interactive setup

Observability

  • Override audit trail: .forge/audit/overrides.log — every behavior override logged permanently (git-tracked)
  • Session reports: session-report.sh generates metrics JSON at session end (tracking 12 registered projects)
  • Audit score: /forge audit returns 0-10 per dimension → aggregate score
  • Session startup snapshot: Drift detection at session start
  • Compaction history: Rolling 5-checkpoint history

IDE integration

None. Claude Code only.

Install scripts

  • install.sh — bash installer
  • global/sync.sh — cross-project synchronization

Domain documentation

The docs/domain/ directory contains extensive reference documentation tracking Claude Code API changes:

  • hook-architecture.md, hook-events.md (33+ hook event catalogue)
  • cli-flags.md (all Claude Code CLI flags documented)
  • parallel-sessions.md, permission-model.md
  • auth.md, plugin-distribution.md, compaction-strategy.md

Related frameworks

same archetype · same primary tool · same memory type

Chachamaru Claude Code Harness ★ 1.6k
A17 Compiled enforcement

Turns raw Claude Code sessions into a disciplined Plan→Work→Review→Release delivery loop with spec contracts and…

Liza ★ 227
A17 Compiled enforcement

Hardened multi-agent coding system with code-enforced role boundaries, adversarial doer/reviewer pairs, and 55+ failure mode…

Superpowers ★ 207k
A1 Skills-only

Enforces spec-first, TDD, and subagent-reviewed development as mandatory automatic workflows rather than optional practices.

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…