{"id":50996425,"url":"https://github.com/kanywst/a2claude","last_synced_at":"2026-06-20T10:01:26.504Z","repository":{"id":364735108,"uuid":"1268424025","full_name":"kanywst/a2claude","owner":"kanywst","description":"Run Claude Code as an A2A protocol agent server — tool progress, file diffs, and permission prompts mapped onto the A2A protocol.","archived":false,"fork":false,"pushed_at":"2026-06-14T08:16:45.000Z","size":489,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T10:08:36.189Z","etag":null,"topics":["a2a","agent-protocol","agent2agent","ai-agents","anthropic","claude","claude-code","llm-agents","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanywst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T14:14:50.000Z","updated_at":"2026-06-14T08:16:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kanywst/a2claude","commit_stats":null,"previous_names":["kanywst/a2claude"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kanywst/a2claude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanywst%2Fa2claude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanywst%2Fa2claude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanywst%2Fa2claude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanywst%2Fa2claude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanywst","download_url":"https://codeload.github.com/kanywst/a2claude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanywst%2Fa2claude/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34565244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent-protocol","agent2agent","ai-agents","anthropic","claude","claude-code","llm-agents","python"],"created_at":"2026-06-20T10:01:26.044Z","updated_at":"2026-06-20T10:01:26.497Z","avatar_url":"https://github.com/kanywst.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/mascot.png\" alt=\"a2claude\" width=\"150\" align=\"right\"\u003e\n\n# a2claude\n\nRun Claude Code as an [A2A](https://a2aprotocol.ai/) agent server. Other agents call it over the protocol; it drives a real Claude Code session in your project and streams the work back as it happens.\n\n[![CI](https://github.com/kanywst/a2claude/actions/workflows/ci.yml/badge.svg)](https://github.com/kanywst/a2claude/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)\n[![Protocol: A2A 1.0](https://img.shields.io/badge/protocol-A2A%201.0-D97757.svg)](https://a2aprotocol.ai/)\n\n![a2claude streaming a task, then pausing on a permission prompt](assets/demo.gif)\n\nMost adapters that put a coding agent behind A2A flatten everything to text in, text out. a2claude keeps the structure Claude Code produces: the tools it runs, the files it changes, what it costs, and how to continue on the next turn.\n\n## How it maps to A2A\n\n| Claude Code produces     | A2A surface it lands on                            |\n| ------------------------ | -------------------------------------------------- |\n| Assistant text           | A streamed artifact (`append` / `last_chunk`)      |\n| A tool call (Bash, Edit) | A `working` status update for the action           |\n| A file edit              | A named artifact carrying the diff                 |\n| Run result               | Cost, turns, and usage on the completion message   |\n| Session id               | Mapped to the A2A `contextId` so follow-ups resume |\n\nThe mapping is all in `executor.py`. Backends only emit normalized events; they never touch the protocol.\n\n## Where this fits\n\nAnthropic now ships its own ways to run Claude Code beyond the terminal: Claude Code on the web, background agents, cloud-hosted Routines, and the Managed Agents API. These are the right choices when you want Anthropic to host the run and you live in their ecosystem, and they are typically tied to Anthropic infrastructure and a GitHub-centric flow.\n\na2claude solves a different problem: making Claude Code a first-class peer on a vendor-neutral [A2A](https://a2aprotocol.ai/) mesh. An orchestrator built on any framework discovers it through its agent card and delegates coding work to it the same way it would to any other A2A agent. The run happens on infrastructure you control, in a workspace you point it at. Reach for a2claude when:\n\n- another agent (not a human at a prompt) is the caller, and it speaks A2A;\n- you want the run on your own infrastructure and data boundary, not a vendor VM;\n- you are wiring Claude Code into a multi-vendor agent system rather than standardizing on one vendor's hosted stack.\n\nThe practical user is the platform team building that mesh, not the individual developer; the developer reaches it through whatever orchestrator the team puts in front of them.\n\n## Requirements\n\n- Python 3.13+\n- [uv](https://docs.astral.sh/uv/)\n- Claude Code CLI on `PATH` (only for the `claude` backend)\n\n## Quick start\n\nInstall:\n\n```bash\nuv sync\n```\n\nThe `echo` backend needs no API key and no Claude install, so you can exercise the whole path offline first:\n\n```bash\nuv run a2claude serve --backend echo \u0026\n# once the \"Uvicorn running\" line appears:\nuv run a2claude call \"fix the failing test\"\n```\n\n```text\ntask 189b1c63-1a7b-4908-87c4-c8f3bba8f6b5\ncontext 0b2a901e-2b6f-4c56-bba2-d0da546936e9\n\n  · Echo\nfix the failing test\n[completed] $0.0 · 1 turns\n```\n\nThen point it at a real project:\n\n```bash\nuv run a2claude serve --backend claude --cwd /path/to/project\nuv run a2claude call \"add a /health endpoint\" --url http://localhost:9100/\n```\n\nContinue the same conversation by passing the `context` from a previous turn:\n\n```bash\nuv run a2claude call \"now add a test for it\" --context \u003ccontext-id\u003e\n```\n\n## Commands\n\n| Command              | Description                                  |\n| -------------------- | -------------------------------------------- |\n| `a2claude serve`     | Start the A2A server                         |\n| `a2claude call TEXT` | Send a message and print the streamed events |\n| `a2claude card`      | Fetch and print the agent card               |\n\nThe agent card is served at `/.well-known/agent-card.json` and advertises Claude Code's abilities as discrete skills (generation, refactor, debug, review, test, explain).\n\n## Backends\n\nA backend turns a prompt into a stream of normalized events. Two ship today:\n\n- `echo`: no dependencies, mirrors the input. For wiring checks and tests.\n- `claude`: drives Claude Code through the Claude Agent SDK.\n\nThe split keeps the A2A layer independent of how Claude Code is invoked, so a raw-CLI backend can be added later without touching the server or the protocol mapping.\n\n## Authentication\n\nThe `claude` backend uses whatever the Claude CLI is configured with. When the server answers on behalf of other agents, that has to be an Anthropic API key (or Bedrock / Vertex). Anthropic does not permit subscription credentials for third-party serving. Set a per-run cost ceiling with `--max-budget-usd`.\n\n## Signed agent cards\n\nA caller that discovers this server only has the agent card to go on. Sign it so the caller can confirm the card came from you and was not swapped in transit:\n\n```bash\nuv run a2claude serve --sign-key card-signing.pem --sign-kid my-key-1 --sign-alg ES256\n```\n\nThe card is then served with a JWS signature over its canonical form. `--sign-key` is a path to a file holding the key: a PEM private key for asymmetric algorithms (`ES256`, `RS256`), or a shared secret for `HS256`. `--sign-kid` is the key id a verifier uses to look up the matching public key. Unsigned is still the default.\n\n## Caller authentication\n\nA signed card proves who the server is; this proves the caller is allowed in. Require a bearer token and the server rejects any task request that does not carry it:\n\n```bash\nuv run a2claude serve --auth-token-file caller-token.txt\n```\n\nWhen `--auth-token-file` is set, callers must send `Authorization: Bearer \u003ctoken\u003e`; a request without a valid token gets `401 Unauthorized`. The agent card stays public so a caller can still fetch it to discover the requirement, and the card advertises the bearer scheme in `securitySchemes`. Without the flag the server stays open, as before.\n\nA2A keeps the credential at the HTTP layer, so this composes with whatever your gateway already does: terminate TLS, validate OAuth, or rate-limit in front, and let the server enforce the token behind it.\n\n## Permissions\n\nA tool that needs approval pauses the task in the A2A `input-required` state instead of being skipped. The caller answers with a follow-up message on the same task:\n\n```bash\nuv run a2claude call \"sudo reboot\"\n# ... [input-required] Permission requested for Bash: $ sudo reboot\n#       reply: a2claude call \"allow\" --task \u003cid\u003e --context \u003cid\u003e\nuv run a2claude call \"allow\" --task \u003cid\u003e --context \u003cid\u003e\n```\n\n`allow` (or `yes`, `approve`, `ok`) approves; anything else denies. The Claude session stays alive across the pause, so it resumes exactly where it stopped.\n\nThe server does not inherit your personal Claude settings, so it has no pre-approved tool allowlist; every tool that needs approval routes through the caller. Read-only actions Claude already treats as safe still run without a prompt.\n\n## Long-running tasks\n\nThe agent card advertises push notifications. A caller can register a webhook for a task and receive status and artifact updates by HTTP POST instead of holding a stream open, which helps when a run takes minutes. Streaming and polling (`tasks/get`) both work too.\n\n## Observability\n\nDebugging one agent is hard; debugging a chain of them without traces is worse. Because A2A runs over HTTP, it drops straight into OpenTelemetry: install the extra and the A2A SDK's instrumentation plus a per-task `a2claude.execute` span light up, with W3C trace context propagating across the call so client and server spans share one trace.\n\n```bash\nuv sync --extra telemetry\n```\n\nTracing is off unless OpenTelemetry is installed, and you configure the exporter the standard way (e.g. `OTEL_EXPORTER_OTLP_ENDPOINT`, or run under `opentelemetry-instrument`). It works against an on-prem or air-gapped collector, so traces never have to leave your network.\n\n## Development\n\n```bash\nuv sync --dev\nuv run ruff check src tests\nuv run ruff format src tests\nuv run mypy\nuv run pytest\n```\n\nCI runs these on Python 3.13 and 3.14, plus a Markdown lint, on every push and pull request.\n\n## Releasing\n\nPushing a `v*` tag builds the package, creates a GitHub release with the artifacts, and publishes to PyPI via trusted publishing:\n\n```bash\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\n## Status\n\nThe mapping is complete end to end and verified against real Claude: text round trip, tool-progress updates, streaming artifacts, file diffs as artifacts, run metadata, session continuity, the permission-to-`input-required` round trip, and push notifications. The offline `echo` backend covers every path including permissions, so it can all be exercised without an API key.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanywst%2Fa2claude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanywst%2Fa2claude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanywst%2Fa2claude/lists"}