Contributing

Development setup, the test tiers, and what a PR needs.

Flow

1. Open an issue first and get it approved.
2. Fork, branch, make the change.
3. Open a PR with the proof described below.

Setup

git clone https://github.com/spotta85/anyagent-rs && cd anyagent-rs
cargo install just        # the dev front door; `just` lists every command
just check                # fmt, clippy, offline tests

Rust 1.88 or newer. For live tests, the agent you are touching must be installed and logged in.

Code

Write the smallest amount of code that does the job. No AI slop.

Comments:

• Every function gets a 1-2 line doc comment: what it does, what flows in and out.
• Non-trivial chunks inside a function can get a short comment.
• Nothing else.

Main functions hold the high-level flow and read top to bottom; helpers sit below them. Adapters never decide turn rules; see Architecture.

Platforms

macOS, Linux, and Windows all build and test in CI. When something differs per OS, pick the first row that fits. Never put #[cfg] inside a function body.

Situation	Do this	Example
std has a cross-platform API	Use it, no cfg	std::env::split_paths, home_dir in discovery.rs
One value differs	One #[cfg(unix)] / #[cfg(windows)] const pair	EXE_SUFFIXES in discovery.rs
Whole behaviour differs	Two same-signature functions, one per OS; callers see no cfg	request_exit in process.rs
Early return on one OS	if cfg!(windows) { return ... }, so both branches still type-check	capture_login_shell_path
Needs an OS API	A crate that owns both halves	command-group (process group on unix, Job Object on Windows)
A test needs a script on disk	Write it per OS in tests/common/mod.rs	shim, stub

Check the other OS without leaving your machine:

rustup target add x86_64-pc-windows-msvc
cargo clippy --all-targets --target x86_64-pc-windows-msvc -- -D warnings

Test tiers

Tier	Command	What it proves	Needs
Offline	just check	Engine contract (conformance.rs), each adapter against recorded fixtures	nothing
Live, one feature	just live claude cancel	The feature against the real agent	the agent installed and logged in
Live, all	just live all	The full matrix in tests/live.rs	every agent

just features lists the live feature names. just live always runs with one test thread; parallel runs open many real sessions at once.

Live rules:

• Never touch real auth: no deleting or moving ~/.claude, ~/.hermes, ~/.local/share/opencode, no logouts.
• SKIP lines are passes. Capability gates and missing keys skip with a reason.
• A failure on model output only (wrong word, empty text) with correct structure: rerun once. Two identical failures are a finding. A structural failure (missing event, wrong error type, hung) is a finding immediately.

What a PR needs

Change	Proof to include
Any	just check passes
Touches a wire or adapter	just live <harness> <feature> output for every harness it touches
Adds or changes a feature	Its test in tests/live.rs added or updated
Changes the public interface	Say so in the description, with what and why. Docs updated in the same PR
Fixes a wire bug	A record_wire capture or fixture showing the bug, and the test that now passes

A PR that changes the interface without updating the docs will not be merged.

Recording a wire

When an agent misbehaves, capture exactly what crossed the wire:

SessionOptions::in_dir(".").record_wire("/tmp/claude.jsonl")

Recordings are unredacted. Strip anything sensitive before turning one into a fixture under tests/fixtures/<agent>/.

Docs

The docs are Mintlify pages under docs/. Keep each page to one job:

Page	Job
Core API	The interface. One row per method or variant, no feature prose
Features	What each feature does, a few sentences and one snippet
Agents	Catalog, capability matrix, per-agent quirks
Building an app	Glue code for a real app
Architecture	Internals

If a fact belongs on another page, link to it rather than repeating it.