fallow init

Start a fallow config with editor autocomplete and validation. Fallow init generates a .fallowrc.json or fallow.toml configuration file with schema support.

Use fallow init to create a configuration file for your project. The generated config has a $schema field, so your editor gives autocomplete and validation.

fallow init detects your project setup and adapts the generated config to it:

• TypeScript: finds tsconfig.json and turns on TypeScript-aware defaults.
• Monorepo: finds workspace configurations (npm, yarn, pnpm) and adds the workspace patterns.
• Frameworks: finds installed frameworks (Next.js, Remix, Vite, and others) and adds the matching entry point patterns.

fallow init

Options

Agent guide scaffold

fallow init --agents gives coding agents a starting guide for your project. It writes a short starter AGENTS.md with prompts for these sections: project overview, architecture, commands, fallow workflow, and agent rules.

The file also has a task-to-command matrix. The matrix sends common agent tasks to the right fallow command, for example: delete "unused" code, commit, prioritize refactors, and consolidate duplication. It is the same matrix as task_matrix in fallow schema.

The command does not overwrite an existing AGENTS.md. The file is guidance for agents. It is not a readiness score.

When fallow can reliably detect the project shape, it prefills these lines:

• 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

Fallow leaves an ambiguous line blank and does not guess:

• It never infers a package manager from lockfiles.
• It leaves the test line empty when more than one test framework is installed.
• It names the workspace tool only when the packageManager field or pnpm-workspace.yaml proves it.

Each prefilled command line has an HTML comment that shows where the value came from. Confirm these lines before you rely on them.

fallow init --agents

fallow agent install writes the same guide. It also writes the skill, the MCP registration, and the commit and push gate for each harness that it detects.

Pre-commit hook

To check each commit before it lands, install a git hook. The hook runs fallow audit against the base branch before each commit:

fallow hooks install --target git

fallow init --hooks does the same, as a shortcut during project setup.

Fallow detects your hook manager and writes to the matching 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:

• Has a binary guard (command -v fallow), so commits still work when fallow is not installed.
• Finds the base ref at commit time. When an upstream is set, it uses git merge-base @{upstream} HEAD. Otherwise it uses the configured branch, or main. A feature branch from a non-default integration branch (next-release, hotfix, or LTS) thus compares against the correct base, and not against its own remote tracking branch.
• Runs fallow audit --base "$BASE" --quiet, which combines dead-code, complexity, and duplication analysis.
• Uses gate=new-only by default. Only findings that the changeset introduces fail the gate. Older findings in touched files do not block the commit. To fail on every finding in changed files, set [audit] gate = "all" in fallow.toml.
• Returns exit code 1 on verdict: "fail", as audit does by default. You do not need --fail-on-issues.
• Prints git commit --no-verify as the bypass option in the success message.

Custom base branch

To change the fallback base branch that the hook uses when no upstream is set, pass --branch:

fallow hooks install --target git --branch develop

Gitignore

fallow init adds .fallow/ to the .gitignore of your project. The .fallow/ directory holds machine-local data (parse cache, regression baselines, snapshots). Do not commit this data.

• If .gitignore exists and already contains .fallow/, nothing changes.
• If .gitignore exists without the entry, fallow appends it.
• If .gitignore does not exist, fallow creates it.

Output

By default, fallow init creates .fallowrc.json. The file content is JSONC, with comments. For a plain JavaScript project, the file looks like this:

{
  // This file is JSONC: fallow reads these comments; generic JSON tools may not.
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": [
    "src/index.{js,jsx,mjs}",
    "src/main.{js,jsx,mjs}"
  ],
  "duplicates": {
    // Hide pair-only clones; focus on widespread copy-paste
    // worth refactoring. Lower to 2 to report every duplicate pair.
    "minOccurrences": 3
  },
  "rules": {}
}

The detected entry patterns change with your project setup. The real file also has commented-out duplicates.ignore examples.

With --toml, it creates fallow.toml. To get editor highlighting for JSON with comments, rename the file to .fallowrc.jsonc. Fallow finds both names.

If .fallowrc.json, .fallowrc.jsonc, fallow.toml, or .fallow.toml already exists, fallow init changes nothing and exits with code 2.

See also