Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Agent Squad HQ

An AI software team that runs in your GitHub organisation. Open an issue in plain language. A squad of agents shapes it, designs it, threat-models it, builds it, reviews it and runs the security gates. Humans approve at the gates they choose. No agent can merge or deploy.

Hub CI License: Apache-2.0 OpenSSF Scorecard

Status: alpha (0.1.0, unreleased). The Actions-mode pipeline, the configuration CLI and the SSDLC gates are the most exercised parts. Server mode, the non-Anthropic executors, the non-GitHub trackers and the dashboard and mobile apps are newer and less proven. See Project status before you rely on any of it.

How it works

One hub repository holds the prompts, the configuration and the reusable workflows. Each project repository carries only its code, its memory files (CLAUDE.md, docs/adr/, docs/lessons.md) and a short agents.yml stub that forwards GitHub events to the hub.

flowchart LR
    I[Issue opened<br/>by a trusted author] --> PO[Product Owner<br/>shapes or proposes]
    PO -->|size L / architectural| D[Architect<br/>design PR + ADR]
    PO -->|shaped| Q[Dispatcher<br/>WIP limit]
    D -->|design merged| Q
    Q --> E[Engineer<br/>agent/* branch + PR]
    E --> G{CI + SSDLC gates<br/>secrets, SAST, SCA,<br/>licences, IaC}
    E --> R[Reviewer<br/>verdict + risk]
    R -->|changes requested,<br/>max 2 rounds| E
    G --> CG[hub / ci-gate]
    R --> CG
    CG --> H{{Human approver}}
    H -->|approves| M[Deterministic merge job]
  • Agents run inside GitHub Actions, through anthropics/claude-code-action, with a per-job, least-privilege GitHub App token and a tool allowlist.
  • A deterministic job, not a model, decides whether a PR may merge. The default is approvers: an organisation owner or member must approve every PR.
  • Risk is max(model risk, path-based floor). A model can raise risk but can never lower it below what the changed files imply.
  • Text from issues, PRs, comments, diffs and the web is treated as untrusted data and fenced before it reaches a model.

Quickstart (Actions mode, about 15 minutes)

Requirements: Python 3.11+, the gh CLI logged in as an organisation owner, a GitHub organisation, and an Anthropic API key. See docs/getting-started/requirements.md.

# 1. Make this repository your hub (any name; agent-squad-hq is the default)
git clone https://github.com/bera-software/agent-squad-hq acme-squad-hub && cd acme-squad-hub
gh repo create acme/agent-squad-hq --private --source . --push

# 2. Install the CLI (PyPI publishing starts with v0.1.0; until then install from source)
python -m pip install -e .            # later: pipx install agent-squad-hq

# 3. Write squadhq.yml, create the GitHub App, set variables, labels and rulesets
squadhq init                          # interactive; prints a dry run
squadhq init --create-app --apply     # does it

# 4. Model credential (never put it in squadhq.yml)
gh secret set ANTHROPIC_API_KEY --org acme --visibility all

# 5. Generate the runtime files, commit, onboard a project, check everything
squadhq render && git add -A && git commit -m "chore: squad config" && git push
squadhq onboard acme/storefront --apply
squadhq doctor
squadhq drill --repo acme/storefront --apply

# Hosted / token-broker installs: only the admin repo settings (no squadhq.yml); dry run unless --apply
squadhq repo-settings --hub acme/agent-squad-hq --project acme/storefront --apply

Then open an issue in acme/storefront describing what you want. The full walkthrough is docs/getting-started/quickstart-actions-mode.md.

Features

Pipeline

  • Product Owner intake, team-thread assessment for unclear asks, Architect design PRs with ADRs, Engineer implementation on agent/* branches, Reviewer verdicts with a bounded fix loop (2 rounds by default), and a mention handler for @squad (and @claude) in issues and PRs.
  • A label-driven state machine defined in config/flows.yml, with a deterministic stuck-ticket sweeper, ticket transitions on merge, a hub janitor and optional GitHub Projects board sync.
  • Scheduled jobs: Chief of Staff, Daily Brief, Weekly Rollup, debt scans, a quarterly architecture review, and Growth, SEO, Legal and Finance department agents (each can be switched off).
  • A catalogue of more than 80 skills (threat modelling, security review, release management, incident response and more) with manifests, prompts and evals. See docs/skills/CATALOGUE.md.
  • 17 stack packs (Java/Spring, Node, Next.js, React, Python/FastAPI and Django, Go, .NET, Rust, PHP/Laravel, Rails, Flutter, React Native, Swift, Kotlin/Android, Terraform, Docker/Kubernetes) that add build commands, review rules, debt rules and risk paths.

SSDLC gates on every PR (each one configurable)

  • Secrets (gitleaks), SAST (Semgrep, new findings only), SCA (OSV-Scanner, newly introduced vulnerabilities), dependency licences (deny list or allow list) and IaC (Trivy config) on pull requests, plus a CycloneDX SBOM attached to each published release of a project.
  • One required check, hub / ci-gate, that works out which checks applied to the PR and whether they passed. Fork PRs still get CI and gates, but no agent job.

Models and executors

  • Hub loops call models through provider adapters: Anthropic, OpenAI, Azure OpenAI, Google Gemini, AWS Bedrock and OpenAI-compatible servers (Ollama, vLLM, LM Studio, OpenRouter, Together), with retry and cross-model fallback.
  • Coding agents in Actions mode run on Claude Code. Output normalisers and tool-profile translations exist for Codex CLI, Gemini CLI and aider, but those executors are not wired into Actions mode yet.

Trackers and code hosts

  • GitHub Issues in Actions mode. Adapters for Jira Cloud, Linear, Trello and GitLab Issues, with status maps, are used by server mode.

Server mode (self-host)

  • A FastAPI service with signed webhook intake (GitHub, Jira, Linear, Trello, GitLab), a leader-elected timezone-aware scheduler, a queue worker, SQLite or Postgres state, a hash-chained audit log, bearer-token roles, Prometheus metrics and optional OpenTelemetry. Docker Compose, a Helm chart and Terraform examples for AWS, GCP and Azure. See docs/deploy/.

Dashboard and mobile (preview)

Project status

Area Status
squadhq CLI: init, validate, render, doctor, onboard, drill Implemented and unit-tested; render --check, pack, skill and eval validation run in hub CI
Actions-mode router, gates, merge policy, sweeper Implemented; inherited from an earlier private deployment and since hardened. Workflow lint (actionlint, zizmor) runs in CI
Provider adapters (hub loops) Implemented and tested against recorded fixtures; live use beyond Anthropic is not yet proven
Executors other than Claude Code Normalisers and tool profiles only; not runnable in Actions mode
Server mode Implemented and tested in-process; deployment examples are validated (helm lint, terraform validate) but not applied to real accounts
Non-GitHub trackers Adapters tested against fixtures; reachable through server mode only
Dashboard, mobile app Preview; mobile builds have not been run
Cloud and Enterprise editions Planned, not built. See docs/editions.md

Some squadhq.yml keys are validated and rendered but not yet enforced by the runtime (for example per-run budgets). The configuration reference marks each one.

Documentation

Contributing and security

Contributions are welcome under the Developer Certificate of Origin. Please read CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities, including prompt-injection bypasses, privately as described in SECURITY.md. Do not open a public issue.

Licence

Apache License 2.0. See LICENSE and NOTICE. Maintained by Bera Software & Consultancy Ltd.

Metadata

Release files for agent-squad-hq 0.1.0.dev2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-squad-hq 0.1.0.dev2
File Size Uploaded Provenance Actions
agent_squad_hq-0.1.0.dev2.tar.gz 1.6 MB With provenance Details for agent_squad_hq-0.1.0.dev2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-squad-hq 0.1.0.dev2
File Interpreter ABI Platform Actions
agent_squad_hq-0.1.0.dev2-py3-none-any.whl Python 3 none any Details for agent_squad_hq-0.1.0.dev2-py3-none-any.whl

Total release size: 2.8 MB

Release files / agent_squad_hq-0.1.0.dev2.tar.gz

Download URL agent_squad_hq-0.1.0.dev2.tar.gz
Size 1.6 MB
Tags Source
SHA-256 checksum
How to use checksums
f6a5d2d0fee96abc46b5dc2b08b6aa8006e4fc1ecb6488adce1fcce5d37a075b
BLAKE2b-256 checksum
How to use checksums
ce1b20a7ed421858f33bdea7905e8a25c41e944659f877231b5e36e255ebbf0f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / agent_squad_hq-0.1.0.dev2-py3-none-any.whl

Download URL agent_squad_hq-0.1.0.dev2-py3-none-any.whl
Size 1.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a1725dde57a70bbe3d77bdcd7dc186bc2d96f3461a2a07dc26c752baab7316f1
BLAKE2b-256 checksum
How to use checksums
702b20c5440c4f3f0d54256cc4dc06e682db00b179bae1589a7abba5caa482ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for agent-squad-hq 0.1.0.dev2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_squad_hq-0.1.0.dev2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page