fallow init

Create a configuration file for your project. The generated config includes a $schema field so your editor can provide autocomplete and validation.

Fallow's init command auto-detects your project setup and tailors the generated config accordingly:

• TypeScript: Detects tsconfig.json and enables TypeScript-aware defaults
• Monorepo: Detects workspace configurations (npm, yarn, pnpm) and includes workspace patterns
• Frameworks: Detects installed frameworks (Next.js, Remix, Vite, etc.) and adds appropriate entry point patterns

fallow init

Options

Flag	Description
--toml	Generate fallow.toml instead of .fallowrc.json
--agents	Scaffold a starter AGENTS.md guide for coding agents, prefilled from detected project info
--hooks	Scaffold a pre-commit git hook that runs fallow on changed files. Alias for fallow hooks install --target git
--branch <REF>	Fallback base branch for the hook when no upstream is set (requires --hooks, default: main)
--decline	Record that this project deliberately stays unconfigured, so the first-contact setup hint and the setup next-step stop appearing. Writes no config file; idempotent

Agent guide scaffold

fallow init --agents writes a short starter AGENTS.md with project-overview, architecture, command, fallow workflow, and agent-rule prompts, plus a task-to-command matrix that routes common agent intents (deleting "unused" code, committing, prioritizing refactors, consolidating duplication) to the right fallow command. The matrix is the same one exposed as task_matrix in fallow schema. It refuses to overwrite an existing AGENTS.md, and it is guidance for agents, not a readiness score.

When the project shape is reliably detectable, the scaffold prefills:

• Install from the packageManager field in package.json, or pnpm install when pnpm-workspace.yaml is present
• Test with the detected test framework (Vitest, Jest, or Playwright), but only when exactly one is present
• Typecheck or lint with tsc --noEmit when tsconfig.json exists
• Module boundaries with the workspace patterns for monorepos

Anything ambiguous stays blank rather than guessed: fallow never sniffs a package manager from lockfiles, leaves the test line empty when several frameworks are installed, and labels the workspace tool only when the packageManager field or pnpm-workspace.yaml proves it. Prefilled command lines carry an HTML provenance comment so you know to confirm them.

fallow init --agents

fallow agent install writes the same guide together with the skill, the MCP registration, and the commit/push gate for every harness it detects.

Pre-commit hook

Use the hooks namespace to scaffold a git hook that runs fallow audit against the base branch before each commit:

fallow hooks install --target git

fallow init --hooks remains available as a project-initialization shortcut.

Fallow detects your hook manager and writes to the right location:

1. Husky -- adds to .husky/pre-commit
2. Lefthook -- adds to lefthook.yml
3. Bare hooks -- writes .git/hooks/pre-commit

The generated hook:

• Includes a binary guard (command -v fallow) so commits still work when fallow isn't installed
• Resolves the base ref at commit time: git merge-base @{upstream} HEAD when an upstream is set, falling back to the configured branch (or main) otherwise. Feature branches forked from a non-default integration branch (next-release / hotfix / LTS) compare against the right base, not against their own remote tracking branch
• Runs fallow audit --base "$BASE" --quiet, which combines dead-code, complexity, and duplication analysis
• Defaults to gate=new-only, so inherited findings on touched files do not block the commit; only findings introduced by the changeset fail the gate. Set [audit] gate = "all" in fallow.toml to fail on every finding in changed files
• Returns exit code 1 on verdict: "fail" (default audit semantics); no --fail-on-issues is needed
• Prints git commit --no-verify as the bypass option in the success message

Custom base branch

Override the fallback base branch the hook uses when no upstream is set:

fallow hooks install --target git --branch develop

Gitignore

fallow init automatically adds .fallow/ to your project's .gitignore. The .fallow/ directory contains machine-local data (parse cache, regression baselines, snapshots) that should not be committed.

• If .gitignore exists and already contains .fallow/, nothing changes
• If .gitignore exists without it, the entry is appended
• If .gitignore doesn't exist, it is created

Output

By default, creates .fallowrc.json:

{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "rules": {}
}

With --toml, creates fallow.toml.

See also