+ Contributing

Issues and pull requests are welcome. Please read the code of conduct. The same guide is in CONTRIBUTING.md.

Do not paste session transcripts, titles from private work, tokens, or credentials into an issue, a pull request, or a test fixture.

Build and test

go test ./...
make build
gofmt -w .

The required checks run on Ubuntu: gofmt and go test -count=1 ./... for Go 1.25 and for the current stable Go, plus govulncheck and a scan of tracked files. golangci-lint also runs on Ubuntu, and macOS and Windows run go test. Those extra jobs are not required status checks. cmd/integration_test.go builds the binary and runs it against temporary fixtures. Those fixtures override every agent home, so the test does not read your sessions, and Jules is not contacted.

Layout

• main.go and cmd/ — CLI, prompts, and the integration test
• internal/discover — one scanner per agent
• internal/store — SQLite index
• internal/query — filter language
• internal/index — rebuild
• internal/act — resume and delete
• internal/tui — list, views, manual, icons
• site — this website, published by GitHub Pages
• examples/plugins — opt-in plugins. Copy a script and its yaml into the config plugins/ directory

Adding an agent

1. Add a scanner that returns discover.Batch. Register it in Scanners().
2. Point the test homes at temporary directories in scan_test.go, index_test.go, and the CLI integration environment. A missing override must not scan the developer's real store, and it must not call the network.
3. Teach act.Plan the resume command. Add a yolo flag only when that CLI documents one. Do not guess.
4. Enable delete only when the removal is one file, one directory inside that agent's session root, a careful rewrite, or one CLI command. Otherwise set CanDelete false and say why.
5. Add a unique two-letter mark in tui.Icon. Letters only, two columns wide. An unknown agent stays ??.
6. Update the agents table in the README and on this website.

Pull requests

Every feature change lands through a pull request. Merge it only after the checks on that pull request have passed. Run gofmt and go test ./... before you push. Update the docs when a command, path, or delete rule changes. Commit subjects in this repository are sentence case and end with a period. A release tag is pushed after its pull requests merge.

Report vulnerabilities privately. See SECURITY.md.

Releases

From a clean main that matches origin:

make release

make release opens a pull request for the changelog when ## Unreleased has notes, waits for the checks, squash-merges it, and then pushes the annotated tag. GoReleaser builds the GitHub Release from that tag. From that tag onward, Cosign signs the checksum file. The version is a link-time value, not a constant in the source. The Homebrew formula is a second pull request, after the tag archive exists. If a check fails, or GitHub reports none, the command does not create the tag. make release VERSION=1.2.3 chooses the version. PART=minor or PART=major bumps that component. DRY=1 prints the plan. INSTALL=1 reinstalls the formula after the formula pull request merges.