git-a2a

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:

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

# Short npm-only profile
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.

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.

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

• CLI reference
• Manifest reference
• Authoring a component
• Consuming components
• Agents and external A2A clients
• Supported adapters
• Migrating from schema 1
• FAQ
• Release and installation maintenance

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.