Thanks for your interest in agentx. This guide covers how to report a problem, propose a change and get a pull request merged.
agentx is in early development, so commands, output and file formats still change. Open an issue before you start on anything larger than a small fix, so we can agree on the approach first.
Everyone taking part is expected to follow the Code of Conduct.
You need:
- Go
1.27or later – the exact version is thegoline inapps/cli/go.mod git2.40 or latermake- macOS or Linux
For the desktop app, you also need:
- Node
26or later –.node-versionnames it for version managers - pnpm
12– the exact version ispackageManagerin the rootpackage.json - Rust, and on Linux the WebKitGTK development packages; see the desktop app's README
Clone the repository:
git clone https://github.com/grundmanise/agentx.git
cd agentxFor the desktop app, install its dependencies from the repository root, then Playwright's Chromium once for its end-to-end tests:
pnpm install
pnpm --dir apps/desktop exec playwright install chromium| Path | What it holds |
|---|---|
apps/cli |
The Go module of the agentx command-line tool |
apps/desktop |
The desktop app (Tauri and React); see its README |
GLOSSARY.md |
The vocabulary: the terms to use in code, docs, issues and PRs |
docs/adr |
Architecture decisions |
docs/spec |
Contracts and specs, such as the CLI's output contract |
docs/help-center |
The user documentation, built with Mintlify |
scripts/install.sh, packaging |
The install script and the templates of the Homebrew cask and formula |
Read the ADRs and specs that touch the area you're changing before you start.
Run these from the repository root. Targets are named <action>-<app>. The CLI targets run against the
Go module in apps/cli:
| Target | What it does | Command |
|---|---|---|
make fmt-cli |
Formats every Go file in place | gofmt -w . |
make fmt-check-cli |
Checks that every Go file is formatted, without changing any | gofmt -l ., fails when any file is listed |
make lint-cli |
Runs the linters, including go vet, with the project's configuration |
golangci-lint run ./... with apps/cli/.golangci.yml |
make tidy-check-cli |
Checks that go.mod and go.sum list exactly the dependencies the code uses |
go mod tidy, fails when go.mod or go.sum change |
make build-cli |
Compiles every package | go build ./..., CGO_ENABLED=0 on Linux and 1 on macOS |
make test-cli |
Runs every test with the race detector, never from cache | go test -race -count=1 ./... |
make check-cli |
Runs all the CLI checks CI runs, in the same order | fmt-check-cli lint-cli tidy-check-cli build-cli test-cli |
make check-desktop |
Runs all the desktop app checks CI runs: the frontend, then the Tauri shell | pnpm install --frozen-lockfile, pnpm check, pnpm test, pnpm build, then cargo fmt --check and cargo clippy --locked -- -D warnings |
make check |
Runs every check CI runs | check-cli check-desktop |
To run the tests without the race detector, as CI does on macOS, use make test-cli RACE=.
golangci-lint needs no install: its version is pinned in apps/cli/.golangci-lint-version, and
make lint-cli builds that release into the build cache on first use through go run, locally and in
CI alike. The build uses the Go version apps/cli/go.mod specifies.
make check-desktop needs the desktop tools listed in Set up your machine,
including Playwright's Chromium. The desktop app's own commands, such as pnpm fix, are in its
README.
- Use the vocabulary. Name concepts as
GLOSSARY.mddefines them, and avoid the synonyms it lists. If a concept you need is missing, raise it in your issue or PR. - Respect the ADRs. If your change contradicts an architecture decision, say so in the PR and explain why the decision should be reopened.
- Test it. Commands are cobra commands, built in
apps/cli/internal/cli/run.go. Tests drivecli.Runagainst a temporary home, so they never touch your real agent configurations. Add or update tests with every change in behavior. - Update the Help Center. When you add a feature or change how one works, update the matching page
in
docs/help-center. Keep it clear, structured and concise, in an imperative tone. - Run
make check. It runs what CI runs: the CLI checks and the desktop app checks. A greenmake checkmeans a green pull request. It needs the tools of both apps, so to check only the side you changed, runmake check-cliormake check-desktop. Runmake fmt-clito fix Go formatting, andpnpm fixinapps/desktopto fix the desktop app's formatting and lint.
- Branch name: name the branch after the change in product terms, such as
feat/source-removed-drift. - Title: use the Conventional Commits format, such as
feat(skill): check managed skills for upstream updates. Pull requests are squash merged, so the title becomes the commit onmain, and its type decides where the change appears in the release notes. - Description: in an imperative style, summarize what changed for users and why. Describe the implementation only where it's needed to understand the change. For how to write a good commit message, read How to Write a Git Commit Message; where its rules for the subject line differ, the Conventional Commits title above wins.
- Evidence: if the change affects functionality or behavior, show it before and after with screenshots, a recording or, for an execution-based change, the console output. Otherwise, it's optional.
- Writing style: don't use em dashes (
—) anywhere; use en dashes (–), hyphens (-) or another suitable punctuation.
Keep each pull request to one change. A maintainer reviews it once CI is green.
The release notes list the commits that change apps/cli or apps/desktop, by the type of their title:
| Type | Section |
|---|---|
feat: a new command, flag or capability |
New |
change: a change to how an existing feature behaves or reads |
Changes |
perf, revert |
Changes |
fix |
Fixes |
docs, test, refactor, style, chore, ci |
Left out |
A breaking change, marked ! after the type or with a BREAKING CHANGE: footer, is marked
Breaking: in its section, and listed under Changes if its type is one that is left out, such as
refactor!. The title's description becomes the entry, so write it for someone who uses agentx. Preview the notes with git-cliff:
git cliff v0.1.0..main.
Search the existing issues first, then open one with a form:
- Bug report: asks what you
ran, what you expected, what happened instead, the output of
agentx versionandagentx doctor, your operating system and the agent clients involved. - Feature request: asks for the problem you want solved and the change you propose.
- Something else: for a question, feedback, a documentation fix or anything else constructive.
New issues are labelled needs-triage until a maintainer looks at them.
Don't report a security vulnerability in a public issue. Report it privately instead, as the security policy describes.
agentx has two kinds of release:
- Nightly: a prerelease of
main, published once a day when the CLI or the desktop app changed and CI passed. - Stable: a maintainer starts it by hand, once a nightly has proved good enough. It promotes that
nightly to a version such as
v0.3.0.
Your merged change reaches users first in a nightly, then in the next stable release. To publish a
release, see RELEASING.md.
agentx is licensed under the Apache License 2.0. By submitting a contribution, you agree that it's licensed under the same terms, as set out in section 5 of the license.