Ratchet Documentation

npm install -g ratchet-run

ratchet --version
# ratchet v1.0.8

ratchet login your-license-key-here

cd my-project
ratchet init

✓ Detected: Node.js / TypeScript (Express)
✓ Wrote .ratchet.yml
✓ Detected test runner: Jest
✓ Set test_command: "npm test"
✓ Guard profile: refactor (default)

Run `ratchet scan` to score your codebase, or `ratchet torque` to start improving.

# Baseline score
ratchet scan

# Run 7 autonomous improvement clicks (default)
ratchet torque

# Run 3 clicks on a specific target
ratchet torque --target api --clicks 3

# Plan first, then execute (review mode)
ratchet torque --plan-first

$ ratchet torque

  ⚡ Ratchet v1.0.8 — Torque Mode
  ─────────────────────────────────
  Target:     full codebase
  Guard:      refactor (3 files / 60 lines max)
  Scope:      staged (auto-detected clean state)
  Clicks:     7 (default)

  Click 1/7  ✓ Error handling — added try/catch to auth middleware
  Click 2/7  ✓ Type safety — inferred missing TypeScript types in user.ts
  Click 3/7  ✓ Security — sanitized SQL input in user queries
  Click 4/7  ✓ Testing — added edge case tests for payment module
  Click 5/7  ✓ Code quality — extracted duplicate validation logic
  Click 6/7  ✓ Performance — added DB index hint for hot query
  Click 7/7  ✓ Error handling — centralized error response format

  ─────────────────────────────────
  Score: 68 → 84 (+16 pts)
  Status: GUARDED  (all tests passing)
  ─────────────────────────────────

  Run `ratchet tighten` to finalize or `ratchet log` to review changes.

ratchet init
ratchet init ./my-service

# Standard 7-click run
ratchet torque

# Aggressive: 15 clicks, broad guards, no PR comments
ratchet torque --clicks 15 --guards broad --no-pr-comment

# Review mode: plan first, then confirm
ratchet torque --clicks 3 --plan-first

# Targeted: only the "api" target, tight guards
ratchet torque --target api --guards tight --clicks 5

# Glob scope: only TypeScript files in src/
ratchet torque --scope "glob:src/**/*.ts"

# Staged files only (for PRs)
ratchet torque --scope staged

# JSON output (for scripting)
ratchet torque --clicks 3 --json > run.json

# Improve until score ≥ 85 or budget exhausted
ratchet improve

# Improve only staged files
ratchet improve --scope staged

# Score the current project
ratchet scan

# Score with detailed explanations
ratchet scan --explain

# CI mode: fail if score < 80
ratchet scan --fail-on 80

# JSON output for pipelines
ratchet scan --output-json > score.json

# Fail on specific category
ratchet scan --fail-on-category "security=70" --fail-on-category "testing=60"

# Scan a specific subdirectory
ratchet scan ./packages/api

$ ratchet status

  Run ID:    run_k8s2x9m
  Status:    RUNNING  (Click 4/7)
  Started:   2 minutes ago
  Score:     71 → 79 (+8 pts)
  Guards:    active (refactor — 3 files / 60 lines)
  Scope:     branch
  Target:    full codebase

  Last click: ✓ Type Safety — added missing null checks in payment.ts
  Next:      (3 more clicks queued)

# Show log from the last run
ratchet log

# Show log for a specific run
ratchet log --run run_k8s2x9m

# Filter by target
ratchet log --target api

# Finalize without PR
ratchet tighten

# Finalize and create a pull request
ratchet tighten --pr

# Generate markdown report for last run
ratchet report > improvements.md

# Generate PDF for a specific run
ratchet report --run run_k8s2x9m --format pdf -o report.pdf

# Inline markdown to stdout
ratchet report --run run_k8s2x9m

# Interactive dependency graph
ratchet vision

# Focus on a specific module with 3 hops
ratchet vision --focus auth-service --focus-hops 3

# Static HTML for sharing
ratchet vision --static -o graph.html

# Export PDF
ratchet vision --export-pdf -o architecture.pdf

# Large codebase: limit nodes
ratchet vision --max-nodes 300

# Generate badge URL for current project
ratchet badge

# Generate badge for a subdirectory
ratchet badge ./packages/api

# Output:
# https://img.shields.io/badge/ratchet-B%20(79)-00d4ff?style=flat-square

![Ratchet Score](https://img.shields.io/badge/ratchet-B%20(79)-00d4ff?style=flat-square)

ratchet build

ratchet login your-api-key-here
ratchet logout

# =============================================================================
# Ratchet Configuration — Full Reference
# =============================================================================

# --- Agent & Model Settings ---
agent:
  # The AI model provider to use for improvement cycles.
  # Options: openai, anthropic, ollama, azure, google
  provider: anthropic

  # Model name. Must be available for the selected provider.
  model: claude-sonnet-4-6

  # Temperature for generation (0.0 = deterministic, 1.0 = creative)
  temperature: 0.3

  # Maximum tokens per response (affects context window usage)
  max_tokens: 8192

  # Base URL for self-hosted / proxy providers
  # base_url: https://api.openai.com/v1

# --- Global Defaults ---
defaults:
  # Default number of improvement clicks per torque/improve run
  clicks: 7

  # Shell command to run tests. Ratchet verifies this passes after each click.
  # Empty string disables test gating.
  test_command: "npm test"

  # Auto-commit changes after each click (default: false — manual review mode)
  auto_commit: false

  # Default guard profile for new runs
  guard_profile: refactor

  # Default scope mode
  scope: diff

  # Timeout per click in seconds (0 = no timeout)
  timeout: 300

  # Fail the run if tests fail after any click
  fail_on_test: true

  # Skip CI checks (for local runs)
  skip_ci: false

# --- Targets ---
targets:
  # Define multiple scopes within the same repository.
  # Each target can be scoped to a subdirectory or feature area.

  - name: api
    path: ./src/api
    description: "REST API layer — controllers, routes, middleware"
    guard_profile: tight
    scope: staged

  - name: core
    path: ./src/core
    description: "Core business logic and domain models"
    guard_profile: refactor

  - name: full
    path: ./
    description: "Full codebase improvement"
    guard_profile: broad
    scope: diff

# --- Boundaries ---
boundaries:
  # Hard constraints that Ratchet will never cross.

  - path: "./node_modules/**"
    rule: no-modify
    reason: "Third-party code — never modify"

  - path: "./dist/**"
    rule: no-modify
    reason: "Build output — generated files"

  - path: "./src/**/*.test.ts"
    rule: preserve-pattern
    reason: "Test files must retain their structure for IDE integration"

  - path: "./src/migrations/**"
    rule: no-delete
    reason: "Database migrations are immutable once merged"

  - path: "./config/secrets.*"
    rule: no-modify
    reason: "Secret files — never touch"

  - path: "./generated/**"
    rule: preserve-pattern
    reason: "Auto-generated code — modify source, not generated output"

# Valid rule types:
#   no-modify     — Ratchet will not edit files matching this path
#   preserve-pattern — Ratchet will not change file structure, only contents
#   no-delete     — Ratchet will not delete files matching this path

# --- Guard Profiles (inline overrides) ---
# Guard profiles control how many files/lines Ratchet can touch per click.
# You can reference named profiles or define them inline:

guards:
  # Named reference
  profile: refactor

  # Or inline definition:
  inline:
    max_files_per_click: 5
    max_lines_per_file: 80
    allow架构_refactors: true
    allow_new_files: true
    allow_delete: false

# --- Score Thresholds ---
thresholds:
  # Minimum score to consider a run "successful"
  target_score: 85

  # Fail categories below these scores
  fail_on_category:
    testing: 60
    security: 75
    error_handling: 50

# --- Notifications ---
notifications:
  # Post run summary to GitHub PR
  github_pr_comment: true

  # Post to Slack webhook
  slack_webhook: null   # set to your Slack webhook URL

  # Emit CI status checks
  ci_status: true

# --- Advanced ---
advanced:
  # Parallel clicks (experimental — default: 1)
  parallel_clicks: 1

  # Enable architect-level analysis (import graphs, coupling)
  architect_enabled: true

  # Cache analysis between runs (faster subsequent runs)
  cache_enabled: true

  # Custom file extensions to scan
  extensions:
    - .ts
    - .tsx
    - .js
    - .jsx
    - .py
    - .go
    - .rs

  # Files/folders to always exclude from analysis
  exclude:
    - "**/node_modules/**"
    - "**/dist/**"
    - "**/build/**"
    - "**/.git/**"
    - "**/*.test.*"
    - "**/*.spec.*"
    - "**/__tests__/**"

total_score = (
  (testing_score / 25) * 100 * 0.25 +
  (security_score / 15) * 100 * 0.15 +
  (type_safety_score / 15) * 100 * 0.15 +
  (error_handling_score / 20) * 100 * 0.20 +
  (performance_score / 10) * 100 * 0.10 +
  (code_quality_score / 15) * 100 * 0.15
)

# Final score: 0–100 (rounded to 1 decimal)

ratchet scan --output-json | jq '.score_history'

guards:
  profile: tight
# Equivalent inline:
# max_files_per_click: 3
# max_lines_per_file: 40
# allow_new_files: false
# allow_delete: false

guards:
  profile: refactor

guards:
  profile: broad

guards:
  profile: atomic

# Disable escalation — all clicks stay at tight limits
ratchet torque --guards tight --no-escalate

# Disable escalation via config
guards:
  profile: refactor
  auto_escalate: false

ratchet torque --scope diff

ratchet torque --scope branch

# Stage files you want improved
git add src/api/*.ts

# Run Ratchet on staged changes
ratchet torque --scope staged

# Only TypeScript files in src/
ratchet torque --scope "glob:src/**/*.ts"

# Only test files
ratchet torque --scope "glob:**/*.test.ts"

# Only files in the utils directory
ratchet torque --scope "glob:src/utils/**"

ratchet torque --scope "file:src/auth/login.ts,src/auth/logout.ts,src/auth/session.ts"

# Alias (no "file:" prefix also works)
ratchet torque --scope "src/auth/login.ts,src/auth/logout.ts"

targets:
  - name: api
    path: ./src/api
    scope: staged      # default scope for this target
    guard_profile: tight

  - name: full
    path: ./
    scope: diff        # default scope
    guard_profile: refactor

name: Ratchet Code Quality

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  ratchet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Ratchet
        run: npm install -g ratchet-run

      - name: Run Ratchet scan
        env:
          RATCHET_API_KEY: ${{ secrets.RATCHET_API_KEY }}
        run: |
          ratchet scan \
            --fail-on 80 \
            --fail-on-category "security=70" \
            --fail-on-category "testing=60" \
            --output-json | tee ratchet-report.json

      - name: Upload Ratchet Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ratchet-report
          path: ratchet-report.json

      - name: Add Ratchet Badge to PR
        if: github.event_name == 'pull_request'
        run: |
          BADGE_URL=$(ratchet badge --output-url)
          echo "::set-output name=badge::$BADGE_URL"
        id: badge

      - name: Post Ratchet Score Comment
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## Ratchet Score\n\n' +
                '🤖 Ratchet has analyzed this PR. View the full report in the artifacts.\n\n' +
                '![Ratchet](' + process.env.BADGE_URL + ')'
            })

name: Ratchet Torque

on:
  push:
    branches: [main]

jobs:
  torque:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Ratchet
        run: npm install -g ratchet-run

      - name: Run Torque
        env:
          RATCHET_API_KEY: ${{ secrets.RATCHET_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          ratchet torque \
            --guards refactor \
            --clicks 7 \
            --scope branch \
            --pr

      - name: Tighten & Finalize
        env:
          RATCHET_API_KEY: ${{ secrets.RATCHET_API_KEY }}
        run: ratchet tighten --pr

# Get the badge URL (returns JSON with url field)
ratchet badge --json

# Example output:
# {"url":"https://img.shields.io/badge/ratchet-B%20(82)-00d4ff?style=flat-square","grade":"B","score":82}

ratchet_scan:
  image: node:20-alpine
  variables:
    RATCHET_API_KEY: $RATCHET_API_KEY
  script:
    - npm install -g ratchet-run
    - ratchet scan --fail-on 80 --output-json | tee ratchet-report.json
  artifacts:
    reports:
      json: ratchet-report.json
    when: always
    paths:
      - ratchet-report.json

ratchet status
# Cycles used this month: 23 / 150 (Pro)
# Resets in 11 days

# Buy 10 extra cycles
ratchet buy --cycles 10

# Upgrade plan
ratchet upgrade --plan pro