Homeboy is a component-aware automation CLI. It gives local developers, CI jobs, scheduled automation, and coding agents one consistent way to run checks, capture evidence, and operate projects.

If you only remember one thing: Homeboy turns common engineering workflows into repeatable commands with structured evidence. Start with review, then add CI profiles, persisted run artifacts, runners, and releases as your workflow needs them.

1. Run A Local Review Gate

From a repository with Homeboy configuration, run:

homeboy review --changed-since origin/main

review is the PR-shaped umbrella for scoped audit, lint, and test checks. Use individual commands when you need to focus on one stage:

homeboy review audit
homeboy review lint
homeboy review test
homeboy review build

2. Add Portable Repo Config

The smallest useful homeboy.json identifies the component and the extension that knows how to operate it:

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

Homeboy core stays generic. Extensions provide ecosystem behavior such as Cargo, WP-CLI, Node.js, GitHub releases, package managers, and platform-specific test/lint commands.

3. Produce Structured Evidence

Most commands can write JSON evidence while still printing human output:

homeboy review --changed-since origin/main --output homeboy-results/review.json
homeboy bench my-project --output homeboy-results/bench.json
homeboy runs show <run-id> --output homeboy-results/run.json

That JSON is the handoff point for CI, scheduled automation, and coding agents.

4. Pick Your Next Path

• I want to review a branch: Review a branch
• I want to reproduce CI: Reproduce CI
• I want benchmark, trace, fuzz, or run artifacts: Capture evidence
• I need runner/offload behavior: Use runners or Set up Lab runners
• I need extension behavior: Set up extensions
• I need durable multi-agent orchestration: Run agent task loops
• I need local multi-component environments: Manage local environments
• I need release automation: Release a component
• I need deployment or fleet operations: Deploy and operate fleets
• I need the mental model: Concepts
• I need exact CLI or config details: Reference
• I maintain Homeboy: Internals
• I am following an operator runbook: Operations

5. Use Embedded Docs

The same docs are embedded in the binary:

homeboy self docs list
homeboy self docs index
homeboy self docs commands/commands-index

What To Read Next

Read by task, not by command name:

• Start with Review a branch for the core quality gate.
• Add Reproduce CI when the component declares CI profiles.
• Add Capture evidence when a result must be consumed by a reviewer, CI job, or agent.
• Add Use runners when the command should run off the controller machine.
• Add Set up Lab runners when the runner itself needs to be configured or proven ready.
• Add Set up extensions when a repo needs platform behavior beyond Homeboy core.
• Add Run agent task loops when work needs durable controller state, retries, events, or human handoffs.
• Add Manage local environments when work spans rigs, stacks, or task worktrees.
• Add Release a component only after the review/evidence loop is clear.
• Add Deploy and operate fleets when you are operating configured targets.