Build the CLI, make one focused change, run the checks for what you changed, and open a pull request.
You need Git, Go (version in go.mod), and Make. Add Go's tool directory to PATH first: export PATH="$(go env GOPATH)/bin:$PATH".
git clone https://github.com/Chemaclass/agnostic-ai.git
cd agnostic-ai
make tools # pinned development tools, once
make build
./agnostic-ai sync # this repository's own tool config
make doctor-dev # each tool, the version found and the version wantedmake doctor-dev exits non-zero when a tool is missing or has the wrong version. Run it before a long check such as make ci-local. On a machine without Java, run make doctor-dev SKIP_JETBRAINS=1.
mise is optional. If you use it, mise trust && mise install installs the Go, Node.js, Java and Zola versions CI uses, from mise.toml. Then run make tools as above. Run the full gate as mise exec -- make ci-local, or with mise activate in your shell. Do not rely on mise shims for it: one test changes HOME, and a shim then cannot find its config.
make test-shell and make ci-local need bashunit on PATH, at the BASHUNIT_VERSION in .github/workflows/ci.yml. Download that release's bashunit file into a folder on PATH and make it executable.
The web interface is embedded from tracked assets, so Go-only builds need no Node.js. After changing ui/src/, its build inputs, or dependencies, use Node.js 22 and run make ui-build, then commit the updated ui/embedded/ files. make build checks that those assets match their sources. make ci-local needs Node.js 22 with npm, for the site script tests and the VS Code extension.
The JetBrains plugin under editors/jetbrains/ needs JDK 21 on PATH, or JAVA_HOME set to it. mise install gets it. make ci-local runs the plugin tests only when that folder changed. Without Java, pass SKIP_JETBRAINS=1 and wait for the plugin's CI job instead. See its README.
After building and syncing, run ./agnostic-ai or go run ./cmd/agnostic-ai to use your checkout. Project instructions live in .agnostic-ai/. Most generated files are ignored; .openhands/setup.sh is tracked to set up new checkouts. Edit the specs, then sync.
Create a branch, keep the change to one outcome, and add tests for behavior you change. When working with a coding agent, give it the expected result and the checks from the guide below. Have it read AGENTS.md before editing and review its diff before submitting.
| Area | Start here |
|---|---|
| Commands, config, or spec loading | Architecture |
| Code that writes a tool's configuration (an adapter) | Adding an adapter |
| Starter specs | Contributing a preset |
| Docs site | Docs site |
| Browser playground | Playground development |
| Editor extensions | Editors |
Choose local checks and remote CI from checks by change type. Record their results in the PR. make hooks installs quick formatting and commit-message checks.
- Commit with a Conventional Commits prefix:
feat:,fix:,docs:,ref:,test:, orchore:. Keep the subject under 72 characters and explain why in the body. - For a user-visible change, add one line under
[Unreleased]in CHANGELOG.md and update the docs it affects (checklist). - In the pull request, say what changed and how you checked it, and link the issue. Push new commits to update it.
Open an issue for a bug or feature; a short description is enough. Ask questions in Discussions. Report security problems through a private advisory.