awm

awm is Agent Workspace Manager, a lightweight CLI for creating agent-ready workspaces and managing dependency or reference repositories.

It works for both common layouts:

• Single-repo mode: add .agents/ assets to one normal project.
• Multi-repo mode: manage related repositories under .agents/workspace/ with git submodules.

Install the latest published version:

go install github.com/pbk-b/awm/cmd/awm@latest

Make sure your Go binary directory is in PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Verify the installation:

awm version

Package documentation:

https://pkg.go.dev/github.com/pbk-b/awm

Install from a local source checkout during development:

go install ./cmd/awm

Initialize a workspace in an existing git repository:

awm init --name my-project

If the current directory is not a git repository, awm asks before running git init. The default is N, so pressing Enter aborts.

For non-interactive initialization:

awm init --name my-project --yes

Open the workspace with a coding tool:

awm open codex

Add an upstream or reference repository:

awm add https://github.com/org/project-spec.git --role upstream --purpose "schema source"

Restore dependencies after cloning a workspace:

awm install

Check workspace consistency:

awm status

awm init creates a small workspace layer without taking over your business code:

.awm-metadata.json
.awm-metadata.lock.json
.agents/
├── skills/
├── patches/
│   └── README.md
├── workspace/
├── arrange/
└── tmp/
README.md
AGENTS.md
.gitignore

awm uses three metadata files:

.awm-metadata.local.json is added to .gitignore by awm init.

Add a dependency:

awm add https://github.com/org/project-spec.git --role upstream --purpose "schema source"

List dependencies:

awm list
awm list --role upstream
awm list --json

Restore dependencies after cloning:

awm install

Update all dependencies, or one dependency:

awm update
awm update project-spec

Remove a dependency:

awm remove project-spec

Check consistency:

awm status

awm add uses git submodule add and passes git output through unchanged. If git fails, awm adds a final error line that identifies the failing upstream command.

Open the current workspace:

awm open
awm open codex

Pass arguments through to the selected tool:

awm open codex -- --full-auto

Add or override environment variables for one launch:

awm open opencode --env OPENAI_API_KEY=xxx -- .

Environment from the current shell is inherited automatically. Arguments after -- are passed through to the selected editor. If no pass-through args are provided, awm defaults to opening the workspace root with ..

Editor resolution order:

1. awm open <editor>
2. AWM_EDITOR
3. EDITOR
4. VISUAL
5. .awm-metadata.local.json tools.editor.default
6. .awm-metadata.json tools.editor.default
7. local/project candidates
8. opencode, codex, cursor, code, vim, nano

Set local editor preference:

awm config editor codex

Set project default editor:

awm config editor opencode --project

awm init [--name <name>] [--open] [--editor <editor>] [--yes]
awm add <url> [name] [--role <role>] [--branch <branch>] [--purpose <text>]
awm remove <name>
awm list [--role <role>] [--json]
awm info
awm install
awm restore
awm status
awm update [name]
awm open [editor] [--env KEY=VALUE] [-- args...]
awm config editor [value] [--project]
awm version

Build the binary:

make build

Run tests:

make test

Install the local binary to /usr/local/bin/awm:

make install

Project structure:

cmd/awm/              # binary entrypoint only
internal/cli/         # command parsing and command handlers
internal/workspace/   # metadata, lock file, paths, dependency model
internal/gitutil/     # git command wrapper and git state helpers
internal/editor/      # editor detection and launch
internal/output/      # user-facing output and passthrough error format
internal/templates/   # generated README, AGENTS, gitignore templates
internal/version/     # version generation and formatting
tools/genversion/     # go generate helper for development builds

The project intentionally uses internal/ for implementation packages so awm can evolve without exposing a public Go API. cmd/awm stays thin and only delegates to internal/cli.

Releases are built by GitHub Actions when a v* tag is pushed:

git tag v0.0.1
git push origin v0.0.1

The release workflow uses GoReleaser to build archives for Linux, macOS, Windows, and BSD variants across common architectures including amd64, arm64, arm, 386, riscv64, ppc64le, and s390x where supported by Go.

GitHub Releases are created as drafts. The draft changelog is generated from commits between the previous tag and the current tag, grouped by conventional commit style prefixes such as feat:, fix:, perf:, and refactor:.

Validate the release configuration locally if GoReleaser is installed:

goreleaser check
make release-snapshot

awm version prints a SemVer-compatible version with a v prefix.

Development builds use the current git commit and a dev prerelease marker:

v0.0.1-dev.<commit8>
v0.0.1-dev.<commit8>.dirty

Release builds inject the git tag, commit, and dirty state through ldflags, then use an rc prerelease marker:

v1.2.3-rc.<commit8>
v1.2.3-rc.<commit8>.dirty

Build a release binary from an exact git tag:

make release