Contributing to AgentXchange

AgentXchange includes the standalone ax CLI, Linux runner and agent integration. Useful contributions improve deployment, execution and recovery across sessions.

Repository layout

Build the development CLI with cargo build --locked -p ax; run Rust checks with cargo test --locked --workspace --all-features and cargo fmt --all -- --check. See native CLI status and source attribution. Dependencies use the published Aster SDK; no sibling source checkout or installed aster binary is required. Run each spike using its README. Keep checks bounded and independent of an Aster release pipeline.

Pre-push checks

Keep integration tests in tests/it/main.rs, with one module per area. Each top-level test file creates another executable and another link. Check the layout without compiling with python3 scripts/check-test-targets.py; commit, push and CI also run this check. For focused changes, run named targets such as cargo test --locked -p ax --test it exec_follow::. The legacy workspace Tree tests remain opt-in with --features tree-compat.

Install cargo-deny and gitleaks, then enable the versioned hook in each clone:

git config --local core.hooksPath .githooks

The hook checks test-target layout, runs cargo deny check advisories for ax's workspace-transfer dependency graph and Gitleaks over the history reachable from the refs being pushed. Both use the repository's existing configuration. A failed check or missing tool blocks the push; deleting remote refs skips the checks. Gitleaks redacts findings. The advisory check uses the current checkout and refreshes the advisory database.

Documentation changes

Describe what a person or agent needs to accomplish and the result they should see. Mark illustrative commands as proposed. Do not present a local experiment as a released feature. Use relative links and keep credentials, machine-specific configuration and private infrastructure out of examples.

The documentation uses the shared @getaster/docs package for its shell, branding, styles, search, navigation, appearance and article controls:

bun install --frozen-lockfile
bun run docs:build
bun run docs:check

Bun 1.2.15 or later is required. Version 0.1.0 is pinned to the unpublished vendor/getaster-docs-0.1.0.tgz development artifact; no sibling checkout is required. The Bun lockfile pins its dependencies. When the package is published, replace that file dependency with the exact registry version.

scripts/build-docs.ts owns the product configuration and explicit publication list. Add a page there when it should be published. The product landing page is in scripts/landing.ts, with its layout in scripts/landing.css; it uses the shared shell, controls and colour tokens. Its approved quote comes from README. The shared navigation renderer places the overview above the guide groups. The builder validates local links and headings and replaces dist/docs/ only after a successful build. Serve or link that directory as the documentation root; the site supports URL prefixes and needs no JavaScript server at runtime.

Integration changes

Use supported Aster APIs where available. Preserve the distinction between the requesting identity, recipient agent, machine transport identity and OS account. An inbox sender does not acquire execution permissions by sending a task. Task retries must not silently duplicate execution, and a successful process exit must not fabricate a valid task result.

For each experiment, record prerequisites, the command to run, expected output, checks performed and remaining gaps. Provider adapters should be replaceable in both self-hosted and managed deployments.