Goobers

Goobers is an open, self-hosted platform for running an AI workforce against your repositories and backlog. Instead of giving one agent an open-ended prompt, you define a team of roles (a gaggle) and the workflow, permissions, checks, retry limits, and human handoffs that govern its work.

Contents

• What is Goobers?
• How it works
• Install
• Quick start
• Documentation
• Shell completion
• Development and contributing

What is Goobers?

Goobers is for a solo builder who wants dependable issue-to-PR automation, a team that wants agents to work within its existing review and CI policy, or an organization that wants the same workforce definitions to remain useful as its execution infrastructure grows.

The shipped runner is one Go binary that runs on one machine. Cloud-scale orchestration is an explicit design goal, not a current product claim. The configuration and run contract are designed to stay constant as execution scales, so the workforce does not need to be redefined for a different runtime.

The core concepts are:

• A goober is a role-specialized AI worker with declared instructions, skills, tools, and capabilities.
• A workflow is a validated state machine of deterministic and agentic stages, gates, retries, budgets, and human handoffs.
• A gaggle is an isolated workforce and its workflows, connected to one project and backlog.
• An instance hosts one or more gaggles and owns their shared runtime state, claims, journals, workspaces, and telemetry.

See How Goobers works for the complete trust and configuration model.

How it works

A Goobers workflow declares what may happen next instead of asking an agent to control the run. Deterministic stages query backlogs, claim work, run checks, poll CI, and create pull requests. Agentic stages invoke a named goober under explicitly granted capabilities. Gates can approve a transition, send work through a bounded repair loop, pause for a human, or escalate.

This keeps the model useful without making it the control plane:

• a lease-based claim ledger prevents two runs from silently taking the same backlog item;
• each run pins its workflow definition and records an append-only, content-digested journal; and
• isolated worktrees, deterministic checks, review gates, and repository policy control whether an agent-authored change can advance.

The shipped implementation workflow shows the complete path: claim one approved issue, implement in an isolated worktree, route review and local-CI failures through bounded repasses, then push the branch and open a pull request.

Configuration is GitOps

Goobers treats workforce definitions as desired state. Keep manifest.yaml, gaggles, goobers, instructions, and workflows in a protected configuration repository. An instance tracks a configured branch, validates new revisions, and atomically reloads valid definitions. Invalid revisions are rejected while the last-known-good configuration continues running.

Agents can propose configuration changes, but normal repository governance decides whether those changes become active. See the architecture of record for the full design and current deployment boundaries.

To reuse repository-hosted gaggle defaults while keeping local customizations, see Tracked gaggle templates. The opt-in tracking files preserve template ancestry, notify about updates, and support conflict-safe updates and backprop into your own configuration repository.

Install

Install the latest stable release on Linux or macOS:

VERSION="$(curl -fsSL https://api.github.com/repos/Agent-Clubhouse/Goobers/releases/latest |
  awk -F '"' '/tag_name/ { print $4; exit }')"
/bin/sh -c "$(curl -fsSL "https://github.com/Agent-Clubhouse/Goobers/releases/download/${VERSION}/install.sh")" \
  -- "$VERSION"

The installer verifies the downloaded archive against the release checksum and places goobers in $HOME/.local/bin. See Release installation and verification for prerequisites, version pinning, install-directory overrides, pre-releases, and the Windows path.

Confirm the installed release before initializing an instance:

goobers version

Quick start

Tour the full workflow locally without credentials or network writes:

goobers init --demo ./demo-instance
goobers run demo ./demo-instance

When you are ready to configure an existing GitHub or Azure DevOps repository, start the guided browser setup:

goobers init --guided

The guided flow inspects the repository, derives what it can, adapts the canonical workflows, prepares required repository metadata, and validates the resulting instance. It does not execute a workflow.

Follow Learn Goobers for the complete progressive path from first success through authoring and operations. For manual or agent-assisted setup, use Onboard an arbitrary repository or the release-matched Getting Started skill.

Documentation

Goal	Start here
Understand the product model	Concepts
Learn Goobers from first run through production operations	Learn Goobers
Run the extended disposable GitHub lab	Quickstart lab
Learn to author, test, and debug workflow YAML	Workflow authoring tutorial
Operate, harden, and extend an instance	Operations tutorial
Configure a real repository	Arbitrary repository onboarding
Install on a specific host	Linux, macOS, or Windows
Operate an instance	Daemon supervision, worktree and local-branch retention
Author workflows and configuration	Workflow primitive reference, Agent toolkit, and DSL authoring
Look up commands	CLI reference
Understand implementation and deployment boundaries	Architecture
Explore the website and animated introduction	goobers.dev

The historical product vision and some design documents describe future direction. The overview above describes behavior shipped in this tree.

Shell completion

source <(goobers completion bash)  # bash
source <(goobers completion zsh)   # zsh
goobers completion fish | source  # fish
goobers completion powershell | Out-String | Invoke-Expression  # PowerShell

Development and contributing

See DEVELOPMENT.md for the repository layout, build and validation commands, binaries, and portal development notes.

Contributions are welcome. See CONTRIBUTING.md for the workflow, SECURITY.md for vulnerability disclosure, and the Code of Conduct.

Licensed under the MIT License.