a2ahub

module

v0.18.2 Latest Latest Go to latest Published: Aug 1, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ydnikolaev/a2ahub

Links

Open Source Insights

README ¶

a2ahub

Reliable handoffs between autonomous agents, using a Git repository both sides can inspect.

Two agents can exchange work in chat, but chat is a poor system of record. Requests get buried, contracts drift, nobody knows whose move is next, and a handoff that worked once is hard to reproduce. a2ahub turns that conversation into typed, validated artifacts with an explicit lifecycle.

Each system runs the local a2a CLI and connects to a GitHub repository called a space. Changes go through pull requests and the space's validation gate. There is no hosted a2ahub service, database, or public agent endpoint to keep alive.

What it gives you

Structured requests instead of loose messages. Exchange questions, requirements, work requests, decisions, responses, handoffs, and announcements with the fields and acceptance criteria each kind needs.
One readable work chain. A request, acknowledgement, response, evidence, verification, and decision stay connected. a2a thread reconstructs the ordered transcript for either side.
A computed inbox. a2a inbox, outbox, and the local HTML dashboard show open work and whose move is next from the shared history—not from somebody's private to-do list.
Versioned data contracts. Publish schemas with valid and invalid fixtures, compare versions, register consumers, announce deprecations, and prevent retirement until the right consumers acknowledge it.
A safe write funnel. Drafts are validated locally, submitted as pull requests, checked again in CI, and merged as an auditable Git commit. Inbound artifact text is treated as data, never as instructions.
Useful local surfaces. Work through the CLI or the local stdio MCP tools; open a self-contained graph/inbox/contracts dashboard with a2a html; enable macOS or VS Code notifications; or embed a2a statusline in a terminal prompt.

Both machines can be offline at different times. Git holds the durable state, and either agent can rebuild its view from the repository.

How it works

One agent drafts and submits a typed request or contract.
The space validates ownership, schema, lifecycle, and contract rules.
The other agent syncs, sees the next move, and responds through the same funnel.
Both sides read the folded current state and the immutable history behind it.

Install

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/ydnikolaev/a2ahub/main/scripts/install.sh | sh

The installer downloads the latest release and verifies its checksum. Windows archives and manual downloads are on the releases page.

Start a project

a2a init
a2a connect <owner/space-repo>
a2a new question
a2a submit <artifact>
a2a inbox

Run a2a for the current command list. Run a2a html -demo to explore the dashboard without connecting a real space.

Release confidence

Release candidates are tested against a protected public GitHub space using two independent identities. The latest full gate, for v0.16.3, passed all 50 of 50 declared live cells across CLI, MCP, lifecycle, contracts, authorization boundaries, and failure recovery. This is coverage of the declared release matrix—not a claim that every possible state has been tested.

Documentation

Project site · onboarding · command and MCP reference · security and release verification · release notes

Apache-2.0 licensed. See LICENSE and NOTICE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
a2a command Command a2a is the single a2ahub binary: CLI + (later) local MCP server + validator + statusline provider + local HTML generator (§7.1, D-005, R-004).	Command a2a is the single a2ahub binary: CLI + (later) local MCP server + validator + statusline provider + local HTML generator (§7.1, D-005, R-004).
internal
artifact Package artifact implements the artifact model shared by every a2ahub surface: the two §3.3 ID classes (standing, exchange/broadcast), ULID lifecycle-event IDs, structural frontmatter parse/serialize, and digests.	Package artifact implements the artifact model shared by every a2ahub surface: the two §3.3 ID classes (standing, exchange/broadcast), ULID lifecycle-event IDs, structural frontmatter parse/serialize, and digests.
avatar Package avatar owns the disposable, machine-local GitHub avatar cache.	Package avatar owns the disposable, machine-local GitHub avatar cache.
cache Package cache implements the P7 read surface (spec docs/features/archive/v1-min-2026-07/specs/07-read-surface-statusline.md): it composes internal/fold over the committed history of every connected space's local mirror clone (internal/space) into the inbox/outbox query sets §4.2/§7.2 defines, plus per-system read cursors, the pending-merge overlay, and mirror staleness/sync-age.	Package cache implements the P7 read surface (spec docs/features/archive/v1-min-2026-07/specs/07-read-surface-statusline.md): it composes internal/fold over the committed history of every connected space's local mirror clone (internal/space) into the inbox/outbox query sets §4.2/§7.2 defines, plus per-system read cursors, the pending-merge overlay, and mirror staleness/sync-age.
cli Real internal/cache-backed PendingMarker/CacheRemover (plan 07 Placement decision, binding): internal/cli's own P6-defined seams (adapters.go) filled with the P7 primitives that back them.	Real internal/cache-backed PendingMarker/CacheRemover (plan 07 Placement decision, binding): internal/cli's own P6-defined seams (adapters.go) filled with the P7 primitives that back them.
coveragepolicy Package coveragepolicy is the SINGLE SOURCE OF TRUTH for a2ahub's test- coverage thresholds — one global floor plus per-package minimums — shared by two consumers: the coverage gate that runs under `go test` (policy_test.go) and the CI/local checker (covercheck.go, run by `make coverage`).	Package coveragepolicy is the SINGLE SOURCE OF TRUTH for a2ahub's test- coverage thresholds — one global floor plus per-package minimums — shared by two consumers: the coverage gate that runs under `go test` (policy_test.go) and the CI/local checker (covercheck.go, run by `make coverage`).
e2e Package e2e — coverage.go implements the P26 coverage manifest (spec 26 §1/§11): a table mapping every catalog CLI verb to real evidence — a verb-invoking txtar scenario OR a direct-construction Go test — or an explicit, justified skip.	Package e2e — coverage.go implements the P26 coverage manifest (spec 26 §1/§11): a table mapping every catalog CLI verb to real evidence — a verb-invoking txtar scenario OR a direct-construction Go test — or an explicit, justified skip.
feedback Package feedback is the P25 agent-feedback core: draft/validate/ledger/ triage/submit for the consumer-agent -> product-repo feedback channel (docs/features/archive/v1-min-2026-07/specs/25-agent-feedback.md).	Package feedback is the P25 agent-feedback core: draft/validate/ledger/ triage/submit for the consumer-agent -> product-repo feedback channel (docs/features/archive/v1-min-2026-07/specs/25-agent-feedback.md).
fold Package fold implements the a2ahub lifecycle fold engine (spec docs/features/archive/v1-min-2026-07/specs/04-fold-engine.md, plan docs/the-plan/plan/03-domain.md §3.4-3.5).	Package fold implements the a2ahub lifecycle fold engine (spec docs/features/archive/v1-min-2026-07/specs/04-fold-engine.md, plan docs/the-plan/plan/03-domain.md §3.4-3.5).
host Package host implements the §T1 5-primitive host adapter interface plus its v1 GitHub implementation: push an ephemeral branch, open a PR with auto-merge always enabled, read the required-check and review-approval state, and locate an already-open/merged PR by its deterministic head branch (the idempotent-retry read path).	Package host implements the §T1 5-primitive host adapter interface plus its v1 GitHub implementation: push an ephemeral branch, open a PR with auto-merge always enabled, read the required-check and review-approval state, and locate an already-open/merged PR by its deterministic head branch (the idempotent-retry read path).
html Package html assembles the `a2a html` / `a2a dashboard` local view's data model (Data) from the shipped read surface (internal/cache Store + space manifests + consumes.yaml) and renders it into a self-contained static HTML page by injecting the model as JSON into an embedded, designed template.	Package html assembles the `a2a html` / `a2a dashboard` local view's data model (Data) from the shipped read surface (internal/cache Store + space manifests + consumes.yaml) and renders it into a self-contained static HTML page by injecting the model as JSON into an embedded, designed template.
livee2e Package livee2e is the LIVE-GitHub e2e tier (spec 36): it drives the real binary against a real, throwaway GitHub space and reports, per scenario, what works.	Package livee2e is the LIVE-GitHub e2e tier (spec 36): it drives the real binary against a real, throwaway GitHub space and reports, per scenario, what works.
mcp Package mcp implements P14 (`a2a mcp`, OP-216): a stdio JSON-RPC 2.0 MCP server whose tool registry maps 1:1 to the §7.7-enumerated OP subset.	Package mcp implements P14 (`a2a mcp`, OP-216): a stdio JSON-RPC 2.0 MCP server whose tool registry maps 1:1 to the §7.7-enumerated OP subset.
notes Package notes parses and range-queries the P31 release-notes corpus: an authored, version-keyed YAML file per shipped a2a version plus one standing current-known-issues document (releasenotes/*.yaml and releasenotes/current/known-issues.yaml), embedded by the releasenotes package.	Package notes parses and range-queries the P31 release-notes corpus: an authored, version-keyed YAML file per shipped a2a version plus one standing current-known-issues document (releasenotes/*.yaml and releasenotes/current/known-issues.yaml), embedded by the releasenotes package.
notification Package notification owns the canonical local notification projection, personal project registry, independent delivery leases, and trusted route ledger.	Package notification owns the canonical local notification projection, personal project registry, independent delivery leases, and trusted route ledger.
operation Package operation derives stable, private idempotency keys from semantic write intent.	Package operation derives stable, private idempotency keys from semantic write intent.
release Package release implements the P19 (OP-217) self-update primitives: fetching the latest product-repo release (Source), verifying a downloaded asset (Verifier — an unconditional ChecksumVerifier plus a T2-interim UNVERIFIED signature slot, checksum-only per the 2026-07-22 amendment), downloading the platform asset triplet (Download), the post-download version self-check (SelfCheckVersion), the atomic same-filesystem binary swap (Swap), version-floor resolution (Resolve), and the TTL'd machine-level "latest known release" cache (CheckState/ReadCheck/ WriteCheck/ReadLatest) plus its background checker (NewChecker).	Package release implements the P19 (OP-217) self-update primitives: fetching the latest product-repo release (Source), verifying a downloaded asset (Verifier — an unconditional ChecksumVerifier plus a T2-interim UNVERIFIED signature slot, checksum-only per the 2026-07-22 amendment), downloading the platform asset triplet (Download), the post-download version self-check (SelfCheckVersion), the atomic same-filesystem binary swap (Swap), version-floor resolution (Resolve), and the TTL'd machine-level "latest known release" cache (CheckState/ReadCheck/ WriteCheck/ReadLatest) plus its background checker (NewChecker).
schema Package schema loads and compiles the embedded product schema corpus (schemas.FS: envelope/v1 base + 8 type extensions, event/v1, manifest/v1, consumes/v1) with santhosh-tekuri/jsonschema/v6, and loads the error-code registry (schemas/errors/v1/registry.yaml).	Package schema loads and compiles the embedded product schema corpus (schemas.FS: envelope/v1 base + 8 type extensions, event/v1, manifest/v1, consumes/v1) with santhosh-tekuri/jsonschema/v6, and loads the error-code registry (schemas/errors/v1/registry.yaml).
space Package space implements the §4.2 space layout model, space.yaml manifest load, project/machine configuration (§7.4), credential resolution (§7.4/§10.5), mirror clones, and the D-002/D-026 write funnel.	Package space implements the §4.2 space layout model, space.yaml manifest load, project/machine configuration (§7.4), credential resolution (§7.4/§10.5), mirror clones, and the D-002/D-026 write funnel.
surface Package surface holds the provider-surface registry: the verified facts about where each AI coding agent looks for a skill (its "skills home") and where it reads always-on context (CLAUDE.md, AGENTS.md, …), plus the detection and link logic that use those facts.	Package surface holds the provider-surface registry: the verified facts about where each AI coding agent looks for a skill (its "skills home") and where it reads always-on context (CLAUDE.md, AGENTS.md, …), plus the detection and link logic that use those facts.
template P37 wave C2 (spec 37 §2 T1, decision D-D): `a2a contract new` scaffolds a starter JSON Schema + matching valid fixture alongside a freshly-drafted contract.md, so a JSON-Schema contract is publishable (validate.	P37 wave C2 (spec 37 §2 T1, decision D-D): `a2a contract new` scaffolds a starter JSON Schema + matching valid fixture alongside a freshly-drafted contract.md, so a JSON-Schema contract is publishable (validate.
validate This file adds the §5.4b computed-compatibility check (D-010, CC-080): for a declared minor/patch bump, every fixture that validated under the PRIOR contract version's schema must still validate under the NEW version's schema.	This file adds the §5.4b computed-compatibility check (D-010, CC-080): for a declared minor/patch bump, every fixture that validated under the PRIOR contract version's schema must still validate under the NEW version's schema.
version Package version is the SSOT for reasoning about bare dotted major.minor.patch versions: parsing, strict-older comparison, canonicalisation, major extraction, and baseline selection.	Package version is the SSOT for reasoning about bare dotted major.minor.patch versions: parsing, strict-older comparison, canonicalisation, major extraction, and baseline selection.
releasenotes Package releasenotes embeds the authored, version-keyed release-notes corpus (P31: one file per shipped a2a version, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json) so it ships inside the `a2a` binary and is surfaced by `a2a whatsnew` without a network call — the same "schema and payload travel as one artifact" rationale schemas/embed.go documents for the product schema corpus.	Package releasenotes embeds the authored, version-keyed release-notes corpus (P31: one file per shipped a2a version, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json) so it ships inside the `a2a` binary and is surfaced by `a2a whatsnew` without a network call — the same "schema and payload travel as one artifact" rationale schemas/embed.go documents for the product schema corpus.
schemas Package schemas embeds the product schema corpus — envelope, event, manifest, consumes JSON schemas, the error-code registry, and the per-type templates — so it ships inside the `a2a` binary (§5.1, D-009: "schemas and validator travel as one artifact").	Package schemas embeds the product schema corpus — envelope, event, manifest, consumes JSON schemas, the error-code registry, and the per-type templates — so it ships inside the `a2a` binary (§5.1, D-009: "schemas and validator travel as one artifact").
scripts
releasebody command Command releasebody renders one releasenotes/<version>.yaml document as the GitHub Release body consumed by GoReleaser.	Command releasebody renders one releasenotes/<version>.yaml document as the GitHub Release body consumed by GoReleaser.
skill Package skill embeds the a2ahub expert-skill tree so the `a2a` binary can install it into a consumer repo (`a2a skill install`).	Package skill embeds the a2ahub expert-skill tree so the `a2a` binary can install it into a consumer repo (`a2a skill install`).
space-template Package spacetemplate embeds the space-template/ tree so `a2a space init` (internal/cli's SpaceCommand, spec 33 §12) can scaffold a new space repo from it directly, without an operator hand-copy step.	Package spacetemplate embeds the space-template/ tree so `a2a space init` (internal/cli's SpaceCommand, spec 33 §12) can scaffold a new space repo from it directly, without an operator hand-copy step.
testkit
fakegithub Package fakegithub is an in-process stand-in for the GitHub REST/GraphQL surface internal/host talks to, backed by REAL local git repositories.	Package fakegithub is an in-process stand-in for the GitHub REST/GraphQL surface internal/host talks to, backed by REAL local git repositories.
gitfixture Package gitfixture is the SSOT for making every git process a test spawns die with the test that spawned it.	Package gitfixture is the SSOT for making every git process a test spawns die with the test that spawned it.
spacefixture Package spacefixture builds throwaway git space fixtures for tests: a bare "origin" repo (the space's remote, simulating a git host with zero network) plus one working clone per simulated system, seeded with the §4.2 tree.	Package spacefixture builds throwaway git space fixtures for tests: a bare "origin" repo (the space's remote, simulating a git host with zero network) plus one working clone per simulated system, seeded with the §4.2 tree.