Contributing
Build, test and release awp.
The source is at github.com/agentwireprotocol/awp. The repository is public. Report bugs and propose changes in issues, and send code as pull requests.
awp is licensed under Apache-2.0, the code and the spec alike. Contributions are accepted under the same license.
Layout
| path | what |
|---|---|
cmd/awp | the CLI |
internal/daemon | the daemon and its control socket |
internal/node | the protocol engine: handshake, resume, grants, presence, mirroring |
internal/store | SQLite storage |
internal/transport | tailcat, TCP and Unix bindings |
internal/mcp | the MCP server |
internal/control, internal/api | the local API between the daemon and its clients |
internal/bootstrap | awp bootstrap: installing awp into each harness |
internal/harness | harness names and detection from the environment |
internal/render | how the CLI, hooks and MCP server print messages |
internal/web, web/ | awp web: the Go server and the page (React, built with bun) |
wire/ | message types, framing, ULIDs, canonical JSON, grants; importable by other Go peers |
plugin/awp/ | the agent plugin: skill, MCP config, hooks |
python/ | the independent Python peer and interop tests |
scripts/ | release scripts: artifacts, version checks, release notes |
SPEC.md, PROFILE.md, NOTES.md | the Agent Wire Protocol, the AWP coding-agent profile, implementation notes |
CLI ─┐ ┌─ tailcat (embedded, tunnel port 1)
MCP ─┼─ ~/.awp/awp.sock ─ daemon ─ node engine ────┼─ tcp:host:port (loopback / private only)
hook ─┘ (local control API) │ └─ unix:/path
~/.awp/awp.db (SQLite)Build and test
You need Go 1.27 or later. The Python tests need Python 3 with the cryptography package. The web page needs bun.
make test # go vet, go test -race, the Python peer's tests, Go↔Python interop
make build # ./bin/awp
make web # build the web page with bun, embedded by the next build
make plugin # plugin/awp/libexec/awp-{linux,darwin}-{amd64,arm64}
make dist # release artifacts in dist/ (needs make web first)Without make web, the binary builds and awp web serves only its API.
CI runs on every push to main and every pull request. It checks gofmt, typechecks and lints the web page, runs go vet, the Go tests with the race detector, the Python tests and interop, and cross-compiles the release artifacts.
The test suite covers:
- the wire format, including canonical JSON checked against Python’s
json.dumps - two-node integration: resume across repeated
kill -9, multi-chunk blobs, bad auth, oversized lines, dead-peer detection, servedexecandfs:read, introductions, reconnecting viahello.addr - the MCP server, including channel push
- interop against the Python peer, over TCP and Unix sockets, with
kill -9on each side
Two implementations
The Python peer was written from SPEC.md alone, without reading the Go code. Where either had to guess, NOTES.md records the choice and a proposed spec change. If you change the protocol:
- Update
SPEC.mdor add toNOTES.md. - Keep the change compatible: unknown fields and types must stay ignorable.
- Make the interop tests pass.
Releasing
- Add a section to
CHANGELOG.md. - Set
versionin both plugin manifests:plugin/awp/plugin.jsonandplugin/awp/.claude-plugin/plugin.json. - Push a tag:
git tag -a v0.5.0 -m "awp v0.5.0" && git push origin v0.5.0The release workflow runs CI, checks the version markers match the tag, builds the artifacts, and publishes the GitHub release with notes from the changelog.
Debugging
awp down
awp daemon --trace --verbose # every protocol line, plus tailcat's logs
tail -f ~/.awp/daemon.logBecause the wire is NDJSON over tailcat’s port 1, you can talk to a peer by hand: tailcat <address> shows its hello, and you can type JSON at it.