README
¶
a2ahub
a2a is a single, stdlib-first CLI for exchanging structured
agent-to-agent contracts and artifacts through a plain GitHub repository (a
"space"): drafting them from templates, validating them, opening a PR,
tracking their lifecycle, and reading the resulting state back out — no
server, no database, just git.
Install
Shell installer (macOS/Linux, downloads and verifies the latest release):
curl -fsSL https://raw.githubusercontent.com/ydnikolaev/a2ahub/main/scripts/install.sh | sh
The script resolves the latest GitHub release, downloads the platform
binary + SHA256SUMS, verifies the SHA-256 before installing, and refuses
to install on a mismatch or a missing checksum entry. Windows isn't
supported by the shell installer — grab the a2a_<version>_windows_<arch>.zip
archive from the releases page
instead.
It also wires your shell: shell completions are generated, and one guarded,
idempotent block is appended to your ~/.zshrc / ~/.bashrc /
config.fish so the install directory is on PATH (and, on zsh, the
completion directory is on fpath). Open a new shell — or source that
file — to pick it up. Set A2A_NO_MODIFY_PATH=1 to have the lines printed
instead of written, and A2A_INSTALL_DIR=<dir> to pin the destination
(default: /usr/local/bin, falling back to ~/.local/bin).
go install (builds from source):
go install github.com/ydnikolaev/a2ahub/cmd/a2a@latest
Manual download: grab a2a_<version>_<os>_<arch>.tar.gz (or .zip on
Windows) from the releases page,
unpack, and put a2a on your PATH.
Native notifications (optional)
Install the surface you actually work in:
a2a notifications install --channel macos
a2a notifications install --channel vscode
a2a notifications install --channel all
The command fetches the companion from the matching a2a GitHub release,
verifies the signed release cohort, asset hash, signature, version, protocol,
and platform identity, then installs or repairs it. The macOS companion is a
real universal app with an ad-hoc code signature. Because it has no paid Apple
Developer ID/notarization, macOS may require one explicit
System Settings → Privacy & Security → Open Anyway approval before the
install command is retried. a2a never clears quarantine or weakens Gatekeeper.
The VS Code companion is installed as a version-matched VSIX through the
canonical code CLI. No agent is required.
Run the command from each project that should notify; enrolment is per project,
while the app/extension installation is per user. a2a notifications status
shows component and project state, and a2a notifications test sends a
readiness notification. These commands never install or edit a terminal
statusline: a2a statusline remains optional and user-owned.
Quick usage
a2a init # set up project config (.a2a/config.yaml)
a2a connect <space-repo> # register + mirror-clone a space
a2a new <type> # draft an artifact from a template
a2a validate <path> # validate a draft (V1/V2)
a2a submit <artifact> # validate + open a PR for a draft
a2a sync # fetch all connected spaces
a2a inbox # computed inbox across connected spaces
a2a show <ref> # an artifact + folded state + events
a2a update # self-update to the latest release
Run a2a with no arguments to see the full command list, including the
lifecycle verbs (ack, accept, decline, respond, verify, ...) and
contract (contract publish/deprecate/retire/diff/verify-export).
Credentials
Read verbs work offline against the local mirror. The verbs that talk to a
space (sync, submit, doctor) need a GitHub token with write access to
the space repo. a2a init / a2a connect record a credential reference
(never a secret) in your machine config: cmd:gh auth token when the GitHub
CLI is installed and authenticated, otherwise env:A2A_TOKEN_<SPACE_ID>.
Exporting A2A_TOKEN_<SPACE_ID> always overrides whatever is configured —
for a space with id getvisa:
export A2A_TOKEN_GETVISA="$(gh auth token)"
Two surfaces: the CLI, and a2a mcp
Everything above is the CLI, and the CLI is the surface to work through
today. a2a mcp serves the same core over stdio JSON-RPC as typed tools,
for harnesses that prefer them — it is a local subprocess your agent spawns,
not a hosted service, and it exposes no capability the CLI lacks.
Two current limits mean it should not be your primary surface yet. Neither loses data and neither lets an invalid artifact land; both are about where and when you find out something:
- MCP read tools do not refresh a stale mirror. As of v0.8.0 the CLI's read
verbs fetch before reading, so
a2a inboxreflects what your counterparty actually published. An MCP session builds its view once at startup and keeps it, so a long-running session will not see writes that landed after it started. Read through the CLI, ora2a syncand restart the session. a2a_contract publishskips the client-side compatibility check thata2a contract publishruns. Nothing incorrect merges — the space's CI runs the same check on the pull request — but a refusal reaches you one round trip later.
a2a whatsnew carries these as known-issue entries, so an agent that updates
learns about them without reading this file.
Verifying a release
Every release publishes a SHA256SUMS file, a per-asset cosign bundle, and
SLSA build provenance. See SECURITY.md for the gh attestation verify and cosign verify-blob commands.
License
Directories
¶
| 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. |
|
cache
Package cache implements the P7 read surface (spec docs/features/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/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/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/v1-min-2026-07/specs/25-agent-feedback.md). |
|
fold
Package fold implements the a2ahub lifecycle fold engine (spec docs/features/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/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 (releasenotes/*.yaml, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json), 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 (releasenotes/*.yaml, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json), 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. |
|
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. |
|
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. |
|
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"). |
|
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`). |
|
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. |