Component-aware automation for developers, CI, and coding agents.

Homeboy gives every repo and multi-component project the same operational surface: check it, review it, test it, benchmark it, trace it, release it, and produce structured evidence that humans and AI agents can act on without scraping terminal logs.

It is built for the way modern software work actually happens: many branches, many worktrees, many agents, and many projects moving at once.

Homeboy is most useful when you want repeatable commands across local development, CI, and agent-driven work:

• Local and CI quality gates — Run audit, lint, test, build, and review through the same component-aware interface.
• AI-ready evidence — Write stable JSON artifacts with --output so coding agents can inspect results without parsing human logs.
• Parallel development loops — Keep worktrees, changed-file checks, baselines, ratchets, PR comments, and review artifacts consistent while many fixes are cooking at once.
• Benchmarks and behavioral traces — Capture performance and black-box behavior with persisted runs, baselines, comparisons, and regression gates.
• Multi-component dev environments — Use rigs and stacks to reproduce local environments and combined-fixes branches.
• Release and deploy workflows — Plan versions, changelogs, tags, publish steps, and deploys from component metadata and commit history.
• Remote and fleet operations — For configured environments, operate projects and server fleets over SSH. This supports server updates and remote inspection, but it is an advanced workflow rather than the core local loop.

Homeboy starts with a component and keeps the command model consistent across where that component runs.

                          ┌─────────────────────────────┐
                          │        homeboy.json          │
                          │ component id + extensions   │
                          └──────────────┬──────────────┘
                                         │
         ┌───────────────────────────────┼───────────────────────────────┐
         │                               │                               │
         v                               v                               v
┌────────────────┐              ┌────────────────┐              ┌────────────────┐
│ Local terminal │              │ GitHub Actions │              │ Coding agents  │
│ audit/test/run │              │ checks/release │              │ JSON evidence  │
└───────┬────────┘              └───────┬────────┘              └───────┬────────┘
        │                               │                               │
        v                               v                               v
┌────────────────┐              ┌────────────────┐              ┌────────────────┐
│ Dev substrate  │              │ Release/deploy │              │ Attention loop │
│ rig/stack/bench│              │ tag/changelog  │              │ triage/report  │
└────────────────┘              └────────────────┘              └────────────────┘

The portable repo-level homeboy.json is enough for local checks and CI. Global config in ~/.config/homeboy/ adds reusable components, projects, servers, fleets, rigs, stacks, and extensions.

For exhaustive command docs, see docs/commands/commands-index.md or run homeboy docs list.

Put a portable component config at the repo root:

{
  "id": "my-project",
  "extensions": {
    "rust": {}
  }
}

Use the extension that matches the repo. For example, Rust projects can use rust, and WordPress projects can use wordpress.

Start locally before wiring CI:

homeboy audit
homeboy lint
homeboy test
homeboy review

The same commands can target a registered component or a specific checkout:

homeboy review my-project --changed-since origin/main
homeboy lint my-project --path /path/to/worktree

Most commands can write command-specific JSON with --output <path> while still printing human output to stdout:

homeboy review --changed-since origin/main --output homeboy-ci-results/review.json
homeboy bench my-project --output homeboy-ci-results/bench.json
homeboy triage workspace --output homeboy-ci-results/triage.json

That contract is the handoff point for automation. A person can read the terminal output; a CI job, scheduled task, or coding agent can read the JSON.

Extra-Chill/homeboy-action@v2 installs Homeboy in GitHub Actions, sets up extensions, runs commands, posts PR comments, and can apply safe autofixes.

name: Homeboy
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Extra-Chill/homeboy-action@v2
        with:
          extension: rust
          commands: audit,lint,test,review

homeboy audit detects convention drift, duplication, dead code, test coverage gaps, stale docs, and structural risk. Baselines let existing debt stay visible while preventing new regressions.

homeboy lint delegates formatting and static analysis to the configured extension. homeboy test runs the component's test suite. homeboy review is the PR-shaped umbrella that runs scoped audit, lint, and test checks and can render a PR-comment report.

homeboy audit --changed-since origin/main
homeboy lint --changed-only
homeboy test
homeboy review --changed-since origin/main --report pr-comment

homeboy refactor handles structural mechanical edits such as naming changes. Safe rewrites can be applied automatically; higher-risk plans stay explicit.

Homeboy is intentionally useful in a crowded workspace: human branches, agent branches, stacked fixes, and CI all need comparable signals.

┌──────────────┐     ┌──────────────┐     ┌────────────────────┐
│ worktree A   │     │ worktree B   │     │ CI / scheduled job │
│ agent fix    │     │ human fix    │     │ review + bench     │
└──────┬───────┘     └──────┬───────┘     └─────────┬──────────┘
       │                    │                       │
       v                    v                       v
  homeboy review       homeboy test            homeboy bench
  --changed-since      --changed-since         --output results.json
       │                    │                       │
       └────────────────────┴───────────┬───────────┘
                                        v
                             structured evidence + PR comments

Useful commands for parallel work:

homeboy status --all
homeboy git status
homeboy review --changed-since origin/main --report pr-comment
homeboy report review.json
homeboy runs list

The goal is not to hide complexity. It is to make every branch and agent return evidence in the same shape.

homeboy bench makes benchmarks a first-class quality gate. Extensions provide the benchmark runner; Homeboy owns baseline storage, regression policies, ratchets, and rig-scoped comparisons.

homeboy bench my-project --baseline
homeboy bench my-project --ratchet
homeboy bench my-project --rig app

homeboy trace captures black-box behavioral traces for declared scenarios. Traces can compare spans against baselines, render Markdown reports, and apply a temporary overlay patch for a run.

homeboy trace my-project checkout-flow --baseline
homeboy trace my-project checkout-flow --report markdown
homeboy trace my-project checkout-flow --overlay experiment.patch

homeboy runs inspects persisted observation runs and artifacts:

homeboy runs list
homeboy runs show <run-id>
homeboy runs artifacts <run-id>

homeboy rig manages reproducible local environments: components, background services, symlinks, checks, git operations, builds, and patch steps. A rig can bring up a multi-repo setup, check its health, sync stacks, and tear it down.

homeboy rig install https://github.com/your-org/rigs.git//packages/app
homeboy rig up app
homeboy rig check app
homeboy rig sync app
homeboy rig down app

homeboy stack manages combined-fixes branches built from a base branch plus declared PRs. It can inspect, apply, rebase, sync, diff, and push the target branch.

homeboy stack status app-combined
homeboy stack sync app-combined
homeboy stack push app-combined

Homeboy's release path is driven by conventional commits:

• fix: commits produce patch releases.
• feat: commits produce minor releases.
• BREAKING CHANGE produces major releases.
• docs:, test:, ci:, and chore: commits do not require a release by default.

The release family keeps version targets, changelogs, tags, and release artifacts tied to the same plan:

homeboy changes
homeboy version show
homeboy changelog show
homeboy release --dry-run

Release automation can be manual, scheduled, or CI-driven. Use the same action when you want release jobs to run in GitHub Actions:

name: Release
on:
  workflow_dispatch:

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: Extra-Chill/homeboy-action@v2
        with:
          extension: rust
          component: my-project
          commands: release

homeboy deps inspects and updates component dependencies. homeboy triage gathers read-only attention reports across components, projects, fleets, rigs, or the whole workspace.

homeboy deps status my-project
homeboy deps update vendor/package my-project --to '^1.2'
homeboy status my-project
homeboy triage workspace --mine --failing-checks

homeboy issues reconciles findings against an issue tracker, and homeboy report renders structured output artifacts such as review results.

Homeboy can also model deployed work as components attached to projects, projects attached to servers, and projects grouped into fleets.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ component   │────>│ project     │────>│ server      │
│ plugin/CLI  │     │ site/app    │     │ VPS/host    │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                           v
                    ┌─────────────┐
                    │ fleet       │
                    │ group       │
                    └─────────────┘

That model backs SSH-driven operations:

homeboy deploy my-project
homeboy ssh production
homeboy logs show production --follow
homeboy db query production "select 1"
homeboy file read production /path/to/file
homeboy file copy production:/path/to/file staging:/path/to/file

These commands are valuable for configured projects and server fleets. They are not required for the local/CI/agent quality loop.

Extensions add platform-specific behavior while keeping the Homeboy command model consistent.

homeboy extension install https://github.com/Extra-Chill/homeboy-extensions --id rust
homeboy extension list

Installed extensions can expose their own top-level verbs, such as homeboy wp and homeboy cargo.

Global config lives in ~/.config/homeboy/. Portable component config lives in homeboy.json at the repository root.

~/.config/homeboy/
├── homeboy.json       # global defaults
├── components/        # registered component definitions
├── projects/          # project definitions and server bindings
├── servers/           # server connections
├── fleets/            # project groups
├── rigs/              # local dev rig specs
├── stacks/            # stack specs
├── extensions/        # installed extensions
└── keys/              # SSH keys

The portable repo-level homeboy.json is enough for local commands and CI. Global component/project/server/fleet config is for reusable local and ops workflows.

# Homebrew (macOS/Linux)
brew tap Extra-Chill/homebrew-tap
brew install homeboy

# Cargo
cargo install homeboy

# From source
git clone https://github.com/Extra-Chill/homeboy.git
cd homeboy && cargo install --path .

Command reference and deeper docs are checked into this repo and embedded in the binary.

homeboy docs list
homeboy docs commands/commands-index
homeboy docs code-factory
homeboy docs schemas/component-schema

Start with docs/commands/commands-index.md for the command index.

MIT License — Created by Chris Huber