Homeboy
Changelog
All notable changes to Homeboy CLI are documented in this file. (This file is embedded into the CLI binary and...
Cleanup Retention Scope
homeboy cleanup --include terminal-runs is the lifecycle owner for terminal observation records, and since #10316 it is the only surface...
Homeboy Documentation
Homeboy documentation is organized by reader intent. If you are new, start with Start here. If you already know what...
Configuration Precedence Map
Investigation for Extra-Chill/homeboy#7519. This document maps configuration concepts that appear in two or more schemas and records the current runtime...
Start Here
Homeboy is a component-aware automation CLI. It gives local developers, CI jobs, scheduled automation, and coding agents one consistent way...
Cross-Compilation Guide
Homeboy can orchestrate releases for any platform, but building native binaries requires access to that platform's toolchain. What Works Anywhere...
Homeboy Core Kernel Investigation
Issue: #13126 Measured at investigate/13126-homeboy-core-kernel based on c56e9f889 plus this report. The investigation treats homeboy-core as the kernel. It does...
Runner contract
The contract between Homeboy core and runner scripts: what capabilities exist, what env vars flow in, what sidecar files scripts...
Release Pipeline System
Homeboy release automation is a local-first planner/executor for component releases. It turns component metadata, conventional commits, extension release actions, and...
Runner Connection Bootstrap
homeboy runner connect <runner-id> uses the first-class runner registry added for issue #2526. Registry Contract Runner configs are JSON files...
Preview Metadata
Homeboy preserves generic preview metadata and can either consume caller-supplied public access or own a native preview tunnel lifecycle for...
Browser Evidence Schemas
Homeboy core owns the product-neutral browser, profile, and trace evidence schema vocabulary. Extensions can normalize product-specific data into these shapes,...
Test Tiers
The commands in this section are the local edit-loop tiers. CI does not run any of them: the CI gate...
Internals
Internals docs are for people maintaining Homeboy itself: architecture, implementation contracts, developer guidance, and docs-maintenance rules. Developer Guide Architecture overview...
PathRoots injection contract
homeboy_core::paths::PathRoots names one Homeboy home: a config root, a data root, and an artifact root resolved together. Its own doc...
Command argument provenance contract
CLI compilation produces a typed command together with a source map for every resolved Clap argument. The public Rust surface...
Verification phase contract
Homeboy's verification surface is deliberately split into isolated primitive commands that can be composed by higher-level workflows. Primitive phases The...
Compiler Warning Extension Contract Gap
Issue #2242 asks Homeboy core to move compiler-warning collection and compiler-warning fix generation behind extension-owned contracts. Validation and formatting already...
Architecture Cleanup Map
This map tracks lower-risk source-boundary cleanup. It is intentionally scoped to developer guidance and ratchets; command implementation refactors should happen...
Error Handling Patterns
Homeboy uses a centralized error system for consistent error reporting across all commands. Error Categories Errors are categorized by type...
Architecture Overview
Homeboy is headless automation for agentic software engineering workflows. It is built in Rust with a config-driven, extension-oriented architecture that...
Config Directory Structure
Important: Portable component configuration can live in a repo-level homeboy.json. Reusable machine-local configuration, state, installed extensions, projects, servers, fleets, rigs,...
Documentation Generation
Instructions for creating comprehensive user-facing documentation from scratch by analyzing the codebase. Purpose Generate structured documentation in the /docs directory...
Documentation Management
Homeboy provides AI agents with consistent instructions for documentation generation and maintenance. These docs serve as the single source of...
Documentation Structure
Standard patterns for organizing documentation files and directories. Directory Conventions /docs Directory User-facing documentation lives in /docs at the project...
Documentation Alignment
Instructions for keeping existing .md documentation synchronized with current codebase implementation. Scope Alignment covers documentation that describes current implementation only....
Controller to runner reverse-runner setup
This guide is the operator runbook for using any Homeboy-managed controller machine as a broker while any configured runner machine...
Required CI Gates
main is protected by the versioned ruleset payload in ../../.github/required-gates-ruleset.json. Every listed context must be emitted by .github/workflows/ci.yml on every...
Operations
Operations docs are runbooks for people operating Homeboy workflows, runners, and evidence paths. They are more specific than workflows and...
Release-gate proof: the canonical non-local command path
This is the one documented command path agents should use to produce release-gate proof from a worktree. It uses normal...
Artifact Loop For Runner And Matrix Workflows
Use this loop when a runner, matrix job, or CI workflow produces output that a reviewer should inspect later: Run...
Configuration Reference
This page is a field-level reference for Homeboy configuration structures. For the higher-level system model and core/extension boundary, see Architecture...
Release Set Manifest
A release set is a caller-supplied, product-agnostic source-membership contract. It is versioned by schema and has a deterministic SHA-256 identity...
Reference
Reference docs describe exact command behavior, configuration fields, schemas, templates, and output contracts. Use workflows first when you need a...
Template Variables
Homeboy supports template variables in several contexts. Both single-brace ({var}) and double-brace ({{var}}) syntaxes are supported everywhere for backward compatibility....
`homeboy` root command
Synopsis homeboy [OPTIONS] <COMMAND> Description homeboy is headless automation for agentic software engineering workflows. It keeps local developers, CI, scheduled...
`homeboy runs` command reference
Generated from the clap command tree. This page is the complete synopsis, argument, flag, and subcommand surface for this command...
Homeboy CLI reference (generated)
homeboy exposes 562 visible commands across 40 top-level command families. Every page below is generated from the clap command tree...
`homeboy runner` command reference
Generated from the clap command tree. This page is the complete synopsis, argument, flag, and subcommand surface for this command...
`homeboy daemon` command reference
Generated from the clap command tree. This page is the complete synopsis, argument, flag, and subcommand surface for this command...
`homeboy agent-task` command reference
Generated from the clap command tree. This page is the complete synopsis, argument, flag, and subcommand surface for this command...
`homeboy trace` command reference
Generated from the clap command tree. This page is the complete synopsis, argument, flag, and subcommand surface for this command...
Server Schema
Server configuration defines SSH server connections stored in servers/<id>.json. Schema { "id": "string", "name": "string", "host": "string", "port": number, "user":...
Component Schema
Component configuration defines buildable and deployable units stored in components/<id>.json. Schema { "id": "string", "name": "string", "local_path": "string", "remote_path": "string",...
Extension Manifest Schema
Extension manifests define extension metadata, runtime behavior, platform behaviors, and integration points. Stored as <extension_id>/<extension_id>.json in the extension directory. Extension...
Project Schema
Project configuration defines environment-specific context stored in projects/<id>.json: server bindings, domains, local paths, remote paths, project-scoped CLI settings, API settings,...
Portable Component Config (`homeboy.json`)
A homeboy.json file in a repo root defines portable component configuration that travels with the code. Clone a repo, run...
Configuration Schemas
Schemas document Homeboy configuration structures. For overlapping configuration concepts and runtime precedence, see Configuration precedence map. Component schema Project schema...
Runs Command
Inspect and maintain persisted observation-store runs and artifacts. Synopsis homeboy runs list [--runner <runner-id>] [--kind bench|rig|trace] [--component <id>] [--rig <id>]...
`homeboy upgrade`
Synopsis homeboy upgrade [OPTIONS] Description Upgrades Homeboy to the latest version. The command auto-detects the installation method (Homebrew, Cargo, source...
`homeboy runner`
Synopsis homeboy runner <COMMAND> runner manages durable execution backends. SSH runners are a capability on a homeboy server record, so...
`homeboy daemon`
Run and inspect the local-only Homeboy HTTP API daemon. Synopsis homeboy daemon <COMMAND> Subcommands start — start the local daemon...
`homeboy release`
Synopsis homeboy release [OPTIONS] [COMPONENTS]... homeboy release version show [<component_id>] [--path <path>] homeboy release changes [<component_id>] [--path <path>] [--since <tag>]...
Commands index
activity agent-task api bench cargo cleanup component config contract daemon db deferred-workload deploy deps extension file fleet fuzz git harvest...
Deploy And Operate Fleets
Use project, deploy, fleet, and status commands when Homeboy is operating configured environments instead of only local quality gates. This...
Run Agent Task Loops
Use agent-task loops when work needs durable orchestration across multiple agent runs, retries, gates, artifacts, external events, and human handoffs....
Release A Component
Homeboy release workflows turn conventional commits and component metadata into version bumps, changelogs, tags, artifacts, and optional publish/deploy steps. Use...
Use Runners
Runners let Homeboy route hot or remote-capable work away from the controller machine while preserving the same command contract and...
Set Up Lab Runners
Use Lab runners when Homeboy should execute hot or remote-capable work somewhere other than the controller machine. A runner gives...
Capture Evidence
Homeboy commands should leave durable evidence that humans, CI, scheduled jobs, and agents can inspect later. Prefer structured output and...
Audit Baseline Ratchet
homeboy.json carries a permanent suppression list for homeboy audit at baselines.audit.known_fingerprints. This document explains what is in it, why it...
Policy-flow detector
The policy-flow detector reports an aggregate transformation that drops declared policy state before downstream code independently branches over the same...
Dead Guard Detection
Homeboy audit flags function_exists('…'), class_exists('…'), and defined('…') guards whose checked symbol is guaranteed to exist at runtime. Such guards are...
Repeated literal-shape detector
Detects inline associative array literals that appear many times with the same shape (ordered keys + value kinds) across a...
Shared scaffolding detector
Finds groups of classes in the same directory subtree that share the same overall method-shape (same method names, visibilities, and...
Audit Deprecation Age
Homeboy audit flags @deprecated X.Y.Z docblock tags that are significantly older than the component's current version. This surfaces ancient deprecations...
Headless Agent Orchestration
Homeboy is useful for agents because it turns engineering work into durable, inspectable command contracts. Agents can run the same...
Homeboy Model
Homeboy starts with a component and keeps the command model consistent across where that component runs. Component A component is...
Code Factory
The code factory is homeboy's model for automated code maintenance: humans write features, the system maintains quality. It combines lint,...
Concepts
Concept docs explain Homeboy's mental model and vocabulary. Use these when you need to understand how commands fit together before...
Structured Evidence
Homeboy treats evidence as a first-class output, not as terminal text someone has to copy into a comment. Human Output...