awa
awa is a local worktree checkpoint, comparison, supervised-command, and run
evidence tool for humans and coding agents. It is a single Go binary with no
daemon, server, telemetry, or runtime dependency. Project-local state lives
under .awa/.
This repository is the complete source for awa. It builds the binary, its user
documentation, the release artifacts, and the small public documentation site.
Requirements
- Go 1.26 or newer;
go.mod owns the exact toolchain floor.
- Git for repository workflows and release tooling.
- Just 1.57 or newer for the repository task surface; every individual operation
also runs as a plain Go command, so Just is a convenience, never a dependency of
building, testing, or using
awa.
- Lefthook 2.1 is optional, for local commit-message feedback only. It is not
installed automatically and nothing in the build, test, review, or release path
depends on it.
- No runtime dependency for a released
awa binary.
Pinned analysis tools run through go run; a separate system installation is
not required.
Install
On macOS and Linux, install the maintained Homebrew formula. The formula is named
awarer; the command it installs is awa.
brew install one-man-wolf-pack/tap/awarer
awa version
Homebrew builds awa from the released source, installing Go itself as a build
dependency — you do not install Go, and the finished binary does not depend on it
at runtime. Compiling takes longer than downloading an archive; in exchange the
binary is built on your machine rather than downloaded, so there is nothing for
macOS to mark as quarantined and no xattr step applies to this path. Because
Homebrew supplies that Go, this path follows the macOS versions Homebrew
supports.
Every supported platform is covered by the release archives, which are the
authority for what a release contains. The macOS archives are built with Go 1.27
and require macOS 13 Ventura or later. They and their SHA-256 checksum file are
published on the
GitHub Releases page.
Download the archive for your platform, verify it against
awa_<version>_checksums.txt — <version> is the release tag without its leading
v — extract the binary, and place it on PATH.
sha256sum --check --ignore-missing awa_1.2.3_checksums.txt # Linux
shasum -a 256 --check --ignore-missing awa_1.2.3_checksums.txt # macOS
awa version
The complete installation, verification, and upgrade guide is at
awarer.one-man-wolf-pack.com/docs/install/.
Once awa is installed, awa help install shows the same guide offline.
To build from source:
go build -o awa ./cmd/awa
./awa version
First Use
awa init
awa status
awa checkpoint -m "before the change"
# edit the worktree
awa changes
awa diff
awa run -- go test ./...
Recovering From an Unwanted Rewrite
When a build, generator, or formatter rewrites files it should not have, restore
just those paths from the checkpoint you were working against. Preview is the
default and changes nothing; --apply is the only mutating form:
awa restore <checkpoint-id> -- generated/client # preview
awa restore --apply <checkpoint-id> -- generated/client # perform it
Restore only writes what one stored state proves, and only where the current path
still matches what the preview described: nothing outside the selection is
touched, incomplete evidence refuses with a named reason instead of overwriting,
and there is no force option. Ignored paths are outside awa's evidence and are
never restored or deleted. Every apply first records the state it overwrote and
prints a restore:<id>:before reference to undo it, retained under
[gc].keep_restores_for. See awa help restore for the full boundary.
Start with awa help agents when using the tool from an agent workflow. For the
commands, configuration, safety boundaries, JSON shapes, and exit behavior of the
version you installed, ask it directly:
awa help agents
awa help topics
awa help quickstart
awa help config
awa help restore
awa docs export --output <directory>
Development
Recurring workflows run through just 1.57 or newer:
just # list the public task surface
just check # the fast gate: format, vet, test, race, lint, reference, licences
just test # Go test suite
just stress # stress-tagged acceptance scenarios
just site # build the public site into site/dist from a fresh export
just release-gate # complete pre-release gate
just --list is exhaustive for the public task facade, not for everything this
repository can do. Focused one-step work keeps its native owner and is better run
directly:
go build ./... # build
gofmt -w . # format
go test -run '^$' -bench . -benchmem ./... # benchmarks
go run ./internal/tools/refgen # emit the CLI reference
awa docs export --output <directory> # export the documentation bundle
A focused check selects a package and, when needed, a test or subtest by -run:
go test ./internal/app/run # one package
go test ./internal/app/run -run '^TestCommandMatches$' # one test
go test ./internal/app/run -run '^TestCommandMatches$/^empty_argv$' # one subtest
go test -race ./internal/app/run # race, same boundary
go vet ./internal/app/run # vet, same boundary
Select the package, never a list of .go files: that silently drops the
package's supporting files and tests. A selection that runs no test proves
nothing; -v shows what ran. just check and just release-gate stay the
aggregates for full qualification, not a prerequisite of every change.
The generated CLI reference is checked against
internal/cli/testdata/reference.json; run
just reference-update after an intended surface change.
CI invokes the same recipes, so a locally green gate is green for the same reason.
Agent workflow instructions are in AGENTS.md. To report a defect
or propose a change, see CONTRIBUTING.md.
Commit messages
A commit that declares no co-author passes. Once it declares one, Git's final
trailer block must hold exactly these two lines, once each and in any order:
Co-authored-by: Codex <[email protected]>
Co-authored-by: Claude <[email protected]>
Enforcement is the Validate workflow, which applies the check to every commit a
push or pull request introduces. It runs once, in the check lane.
./scripts/check-co-authors.sh <file> # try it against a message
lefthook install # opt in to local feedback
lefthook uninstall # opt back out
The optional commit-msg hook runs the same check and only makes the answer
arrive sooner; skipping it or never installing it cannot change what the remote
check decides. Use the script directly rather than lefthook run to test a
message: run synchronizes the hook into .git/hooks as a side effect.
Repository Map
cmd/awa — binary entry point.internal/cli — command routing and human/machine projection.internal/app — application use cases.internal/domain — domain values and invariants.internal/infra — filesystem, process, storage, SQLite, and
Git adapters.test/acceptance — built-binary acceptance scenarios.site — static-site generator, local server, and site documentation.internal/tools — repository-local generators, audits, and
release tools.scripts — repository shell checks the hook and CI call directly..github/workflows — CI, release, and site orchestration.
Runtime entry points other than cmd/awa are repository tools, not additional
product commands: site/sitegen, site/siteserve, and the programs under
internal/tools are invoked through the justfile or directly with
go run.
Focused Documentation
License
awa is licensed under the Apache License 2.0.
