git-a2a
Connect a Git component together with the agent responsible for it.
git-a2a is a cross-platform component dependency manager. A component repository publishes
code, one A2A Agent Card reference for its owner, and optionally a readable surface such as API
documentation, examples, or source. A consumer connects the code through its own platform's
adapter and records the exact commit, adapter, and package-manager variant.
git-a2a does not send messages, manage tasks, run agents, or host Agent Cards. Use the usable Agent Card reference
shown by git a2a whose NAME with an external A2A client: an HTTPS URL or a local copy of a
repository-relative card from the applied commit.
Quick start
Run the binary directly as git-a2a, or install it on PATH and use Git's equivalent
git a2a form:
git a2a init
git a2a add https://github.com/acme/lib-utils.git --name lib-utils
git a2a list
git a2a whose lib-utils
git a2a pull lib-utils
git a2a remove lib-utils
Version 2.1.0 introduces whose NAME and removes the positional argument from list.
Scripts using list NAME --json must use list --json and select the alias from the array.
There are exactly six domain commands:
| Command | Result |
|---|
init | Creates a minimal schema 2 a2amodule.yml without overwriting an existing manifest. |
add SOURCE | Resolves one commit, chooses applicable adapters, connects the component, and records its owner and surface. |
pull [NAME] | Updates one or every dependency through the adapters and variants chosen by add; with no dependencies it reports No dependencies. and succeeds without mutation. |
remove NAME | Removes only the selected dependency's owned integration and local materialization. |
list | Reports every direct dependency, commit, adapter, Agent Card, surface, and local problem; --json returns the existing array format. |
whose NAME | Reports one dependency's responsible agent, usable Agent Card reference, optional local surface, and recoverable metadata problems; --json returns one object. |
pull is adapter lifecycle, not a wrapper around git pull. All bindings of a polyglot
component use the same resolved commit. Adapter and manager selection is durable: a later change
to PATH or consumer marker files cannot silently switch it.
End-to-end demo
The ACME app walkthrough demonstrates
the complete loop: connect a component, discover its responsible agent, send a request through
A2A, let the owner change the library, run git-a2a pull, and observe the new result. The
app repository and
library repository must be cloned next to each
other. Docker with Compose is the only runtime requirement:
git clone https://github.com/neprel/git-a2a-demo-acme-lib.git
git clone https://github.com/neprel/git-a2a-demo-acme-app.git
cd git-a2a-demo-acme-app
./demo/run.sh
DEMO_PROFILE=npm ./demo/run.sh
The demo uses deterministic agents without LLM API keys, real A2A transport, the published
git-a2a 2.0.0, and temporary local Git remotes. The separate demo client performs A2A
communication; git-a2a manages dependency code and metadata. The agents exist only for the local
run and are not permanently available public services. See the
verified transcript
for the recorded full-profile result.
Component contract
a2amodule.yml uses schema 2:
schema: 2
component:
id: lib-utils
description: Shared parsing and validation utilities.
repository: https://github.com/acme/lib-utils.git
exports:
- adapter: npm
name: "@acme/lib-utils"
- adapter: pypi
name: acme-lib-utils
surface: docs/public
agent:
name: lib-utils-owner
card: https://agents.acme.example/lib-utils/.well-known/agent-card.json
The Agent Card remains the authority for the agent's interfaces, skills, and authentication.
The manifest deliberately does not duplicate them. init may create an incomplete local
manifest without agent; a repository consumed by add or pull must declare agent.card.
The optional component.surface is published data from the same applied commit and is
materialized under .git-a2a/surfaces/NAME. If no surface is declared, no repository content is
implicitly published. Surface is not an installation mechanism and is not a submodule.
See the manifest reference, authoring guide,
consumer guide, and schema 1 migration guide.
Adapter matrix
Every existing platform integration is retained. Native adapters apply dependencies through the platform's own
manager, updating declarations, native locks, and installed or resolved state; build-system adapters compose with one submodule checkout rather than copying
source into a second tree.
| Mode | Adapters |
|---|
| Native Git dependency | npm (npm, Yarn, pnpm, Bun), Python (uv, Poetry, PDM, PEP 621/pip), Go, Cargo, SwiftPM, Pub, Bundler, Composer, Mix, Cabal/Stack, Zig, Clojure, Nix |
| Submodule + build integration | CMake, Gradle, MSBuild, Maven, Meson |
| Submodule only | Fallback when no integration applies or the native manager cannot represent the source |
Git submodule is an ordinary adapter with the same add/pull/remove/inspect lifecycle. Native
lockfiles remain owned by their package managers. See Works with for the
detailed matrix and boundaries.
Installation
These existing installation channels are preserved. Commands track the latest stable release;
pin a version in CI.
| Channel | Command |
|---|
| Go | go install github.com/neprel/git-a2a/v2/cmd/git-a2a@latest |
| Go zero-install | go run github.com/neprel/git-a2a/v2/cmd/git-a2a@latest --version |
| macOS/Linux installer | curl -fsSL https://git-a2a.com/install.sh | bash |
| Windows installer | irm https://git-a2a.com/install.ps1 | iex |
| Homebrew | brew install neprel/tap/git-a2a |
| Scoop | scoop bucket add git-a2a https://github.com/neprel/scoop-bucket; scoop install git-a2a |
| npm | npx git-a2a@latest --version |
| PyPI with uv | uvx git-a2a --version |
| PyPI with pipx | pipx run git-a2a --version |
| Container | docker run --pull=always --rm ghcr.io/neprel/git-a2a:latest --version |
| Nix flake | nix run github:neprel/git-a2a -- --version |
Linux .deb, .rpm, and .apk packages are attached to GitHub Releases. Release archives
cover Darwin, Linux, and Windows on amd64/arm64 and include checksums and SBOMs. The standalone
installers verify checksums and support version pinning, destination selection, and dry-run.
Package-manager installs are updated with that package manager; the binary has no self-updater.
Maintainer and provenance details are in the release guide.
Documentation
The portable Agent Skill teaches a coding agent this six-command
workflow. It does not configure an MCP server or agent harness.
Specification as source
Repository decisions and invariants live in .hint files beside the artifacts they govern.
hint <path> returns the knowledge governing a path, and hint check <path...> validates the
linked research records. The repository and CI use HINT 2.0.1. See
HINT for the tool and format.
License: MIT.