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.
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)
- A Next.js dashboard and an Expo app for approvals, runs, costs and briefs, both clients of the server API. Neither has been released. See docs/apps/dashboard.md and docs/apps/mobile.md.
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
- Documentation home (build the site with
mkdocs serve) - Architecture · Security model · Threat model
- squadhq.yml reference · Variables and secrets
- Roadmap · Changelog
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.dev4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_squad_hq-0.1.0.dev4.tar.gz | 1.6 MB | With provenance | Details for agent_squad_hq-0.1.0.dev4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_squad_hq-0.1.0.dev4-py3-none-any.whl | Python 3 | none | any | Details for agent_squad_hq-0.1.0.dev4-py3-none-any.whl |
Total release size: 2.8 MB
Release files / agent_squad_hq-0.1.0.dev4.tar.gz
| Download URL | agent_squad_hq-0.1.0.dev4.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd7b9b6d3a7d71f816f13e3f125b03c35a3f6c78e98807102f5315b0ded2e48f
|
|
BLAKE2b-256 checksum How to use checksums |
d0f9db56d5fbef0d64b06738beb5afb6fa6296dc0bb4acbd843dd2387600aa2a
|
| 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 logRelease files / agent_squad_hq-0.1.0.dev4-py3-none-any.whl
| Download URL | agent_squad_hq-0.1.0.dev4-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a148f4a3c4d77a2ff13d7e45a7d5a050f02bed39abf2a3192b3671c29e882d7
|
|
BLAKE2b-256 checksum How to use checksums |
557391d0eb8c06bdd86193453c98700a054553611e2aee366cfd3d5d7f91c710
|
| 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 logSecurity for agent-squad-hq 0.1.0.dev4
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.
Attestation for agent_squad_hq-0.1.0.dev4.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 logA 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.