Fallow: Codebase Intelligence for Maintainable AI and Hand-Coded Projects

Introduction

Fallow is a free, open-source codebase intelligence tool for TypeScript and JavaScript that helps improve code maintainability. It identifies common issues like dead code, duplication, and high complexity, making it invaluable for both AI-generated and hand-coded projects.

Configuration Checklist

Element	Version / Link
Language / Runtime	TypeScript, JavaScript, Node.js
Main library	Fallow
Required APIs	Not explicitly mentioned for static analysis
Keys / credentials needed	None for static analysis

Step-by-Step Guide

Step 1 — Run Fallow without installing

To get a quick overview of your project's code health without any setup, you can run Fallow directly using npx. This will detect plugins, analyze metrics, and report on various code quality aspects.

npx fallow

Step 2 — Install Fallow as a dev dependency

For consistent use across a project and by team members, it's recommended to install Fallow as a development dependency. This ensures everyone uses the same version and configuration.

npm i -D fallow

Step 3 — Initialize Fallow configuration

To customize Fallow's behavior, such as ignoring specific files or changing detection modes, you need to initialize a configuration file. This creates a fallowrc.json file in your project root.

npx fallow init

Step 4 — Configure Fallow to ignore specific files/patterns

Edit the generated fallowrc.json file to specify patterns for files or directories that Fallow should ignore during analysis. This is useful for test files, generated code, or specific data definitions that naturally contain duplication or are not meant for manual refactoring.

{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": [
    "src/index.{ts,tsx,js,jsx}",
    "src/main.{ts,tsx,js,jsx}"
  ],
  "duplicates": {
    "minOccurrences": 3,
    "ignore": [
      "src/data/product-info/**",
      "**/__tests__/**"
    ],
    "mode": "semantic"
  },
  "rules": {
    "unused-dependencies": "warn"
  }
}

Step 5 — Use Fallow with AI Agents (Skills)

Fallow can be integrated into AI agent workflows by adding it as a skill. This allows your AI agent to leverage Fallow's analysis capabilities to identify and potentially fix code quality issues automatically.

npx skills add fallow-rs/fallow-skills

Step 6 — Run Fallow with specific metrics

You can run Fallow to focus on particular code quality metrics like dead code, duplication, or overall health. This helps pinpoint specific areas for improvement.

npx fallow dead-code
# Output will show unused files, unused exports, unused types, and unused dependencies.

npx fallow dupes
# Output will show duplicated code blocks and clone groups.

npx fallow health
# Output will show file health scores, large functions, and high complexity functions.

Step 7 — Fix issues automatically

Fallow can automatically fix certain types of issues, such as unused exports or dead code, reducing manual effort. Use the --dry-run flag first to preview changes.

npx fallow fix --dry-run
# Review changes, then run without --dry-run to apply fixes.

// Example of ignoring a specific line for unused export
// fallow-ignore-next-line unused-export
export const handler: GameEffectHandler<Payload> = (amount, cardInstanceId, state) => {
  // ... code ...
}

// Example of ignoring a file for code duplication
// fallow-ignore-file code-duplication
// ... entire file content ...

Step 8 — Run Fallow audit for pull requests

To ensure new code adheres to quality standards, Fallow can audit changes introduced in a pull request by comparing them against a base branch (e.g., main). This helps maintain code quality over time.

npx fallow audit
# This compares current branch changes against the main branch.
# Output will highlight new issues introduced in the current branch.

Step 9 — CI Integration

Fallow offers full CI integration, allowing you to automate code quality checks on every push or pull request. This ensures that code quality is consistently maintained before merging into the main branch.

name: Fallow analysis
on: [push, pull_request]
jobs:
  fallow:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: fallow-rs/fallow@v2
        with:
          format: sarif

⚠️ Common Mistakes & Pitfalls

1. Ignoring Test Code Duplication: While test code often has intentional duplication for clarity, Fallow might flag it. Use the ignore patterns in fallowrc.json (e.g., **/__tests__/**) to prevent false positives.
2. Not Installing as a Dev Dependency: Running npx fallow without installing it as a dev dependency can lead to inconsistent Fallow versions across development environments. Always install with npm i -D fallow.
3. Running fallow fix in Non-TTY Environments: The fix command might prompt for confirmation in interactive terminals. In CI/CD pipelines, use --yes flag (e.g., fallow fix --yes) or --dry-run with --format json --quiet to manage output.
4. Overlooking High Complexity: AI-generated code can often be overly complex. Fallow's complexity metrics (Cyclomatic, Cognitive, CRAP) help identify functions that are hard to read, test, or maintain, which should be prioritized for refactoring.
5. Not Using Semantic Mode for Duplication: The default