Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (96 loc) · 9.5 KB

CONTRIBUTING.md

File metadata and controls

145 lines (96 loc) · 9.5 KB
Raw

Contributing to agent-desktop

agent-desktop is a native Rust CLI and FFI library that gives AI agents structured access to desktop applications through OS accessibility trees. Contributions that sharpen that core mission are welcome.

Kinds of contributions that fit this project

  • Bug fixes — wrong JSON output, incorrect ref resolution, STALE_REF on a stable target, etc.
  • New commands — additions to the 60-command surface (56 operational, four held-input names fail closed); see the steps in AGENTS.md
  • Platform adapters — fixes and features for the macOS, Windows and Linux adapters, each implementing PlatformAdapter
  • App-specific quirks — documented edge cases for specific apps (Electron, game engines, etc.) under skills/
  • Docs and skill files — keeping skills/agent-desktop*/ accurate when behaviour changes

Out of scope: embedding LLMs, GUI/TUI interfaces, browser automation, macro recording.

Code of Conduct

This project follows the guidelines in CODE_OF_CONDUCT.md. All contributors are expected to uphold them.

Prerequisites

Requirement Notes
Rust toolchain Pinned to 1.89.0 via rust-toolchain.toml (rust-version 1.89 is the MSRV). rustup picks the correct channel automatically.
macOS 13+ Required to build and run the macOS adapter (crates/macos/), with the Xcode command-line tools.
Windows The Windows adapter (crates/windows/) builds on Windows only, with the MSVC build tools.
Linux The Linux adapter (crates/linux/) builds on Linux only. Its live tests need an AT-SPI session; see tests/e2e-linux/README.md.
Python 3 scripts/check-rust-file-size.sh runs a Python helper and fails when no Python 3 is on PATH.
Accessibility permission Required on macOS for integration and E2E tests against real apps. Grant it in System Settings > Privacy & Security > Accessibility by adding the terminal you run tests from.
Screen Recording permission Required on macOS only for screenshot tests. Same path in System Settings.

Getting started

git clone https://github.com/vercel-labs/agent-desktop
cd agent-desktop

# Wire up the pre-commit hook (one time per clone)
git config core.hooksPath .githooks

# Every platform adapter compiles on its own OS only, so unscoped workspace
# commands fail on every host. Scope cargo to the host package set.
# macOS:
HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
# Windows: swap agent-desktop-macos for agent-desktop-windows.
# Linux:   swap agent-desktop-macos for agent-desktop-linux.

# Debug build
cargo build "${HOST_PKGS[@]}"

# Release build (optimised, < 15 MB)
cargo build --release -p agent-desktop

# Run the binary
./target/release/agent-desktop snapshot --app Finder -i

HOST_PKGS is an array so that it expands to separate arguments in both bash and zsh, the macOS default shell.

Dev workflow and quality gates

All of these must pass before a PR is merged. Set HOST_PKGS as shown in Getting started.

# Format check
cargo fmt --all -- --check

# Lint — zero warnings required
cargo clippy "${HOST_PKGS[@]}" --all-targets -- -D warnings

# Library unit tests (adapter stubs, golden fixtures); skips the agent-desktop binary crate
cargo test "${HOST_PKGS[@]}" --lib

# Binary-level command tests (CLI contract, dispatch, batch, policy)
cargo test -p agent-desktop

# FFI integration tests (C-ABI, enum fuzzing, out-param zeroing)
cargo test -p agent-desktop-ffi --tests

# Core isolation — output must contain no platform crate names
cargo tree -p agent-desktop-core

# macOS only: E2E harness against the SwiftUI fixture app (needs an exclusive desktop and AX permission)
AGENT_DESKTOP_E2E_EXCLUSIVE=1 bash tests/e2e/run.sh

CI and the pre-commit hook run cargo test through scripts/cargo-test-isolated-home.sh test ..., which gives cargo a throwaway HOME so tests never touch ~/.agent-desktop. Use it the same way locally when you want that isolation.

tests/e2e/run.sh builds the release CLI, macOS helper and FFI library itself and refuses to run without AGENT_DESKTOP_E2E_EXCLUSIVE=1, because headed cases move the real cursor. tests/e2e/README.md covers what it asserts and how to add a scenario.

CI also enforces what a local run can miss: the 15 MB limit on each shipped executable, the Rust 1.89 MSRV check, drift of the committed C header crates/ffi/include/agent_desktop.h from the Rust ABI declarations (regenerate it with scripts/update-ffi-header.sh, which needs cbindgen 0.29.4), the cargo-deny dependency policy in deny.toml, secret scanning, CodeQL, and workflow linting.

Pre-commit hook

.githooks/pre-commit is the local mirror of the CI gates, and the script is the authoritative list. On a commit that stages .rs or .toml files it runs, over the package set for the host OS, the source-rule scripts in scripts/ (check-rust-file-size.sh, check-no-phase-references.sh, check-stale-ref-constructor-misuse.sh), cargo fmt --all -- --check, clippy with -D warnings, and the --lib tests. When the commit touches crates/ffi/ it also runs the stub-adapter passthrough test and the cbindgen header-drift check (skipped when cbindgen 0.29.4 is not installed; CI still runs it). A commit that only touches scripts/, .githooks/, .github/workflows/ or tests/e2e-linux/ runs the Bash 3 compatibility and no-phase-reference checks.

To bypass in a genuine emergency:

git commit --no-verify
# or
SKIP_PRECOMMIT=1 git commit -m "..."

Engineering rules

AGENTS.md holds the engineering rules, and they bind people and coding agents alike: Conventional Commits, the 400-line cap per Rust file, no inline comments, no delivery-plan references in shipped source, one domain type per file, error handling, core isolation, and the steps for adding a command. The pre-commit hook and CI enforce most of them.

Skills stay in sync. Every new command or changed CLI flag must be reflected in the matching skill. Cross-platform behavior goes in the core skill, skills/agent-desktop/ (its references/ hold the per-command detail). Platform behavior goes in skills/agent-desktop-macos/, skills/agent-desktop-windows/ or skills/agent-desktop-linux/, and C ABI changes in skills/agent-desktop-ffi/. The binary embeds these skills and AI agents read them, so they must match the implementation.

Submitting a pull request

  1. Pick the right base branch. Branch from main and open the PR into main for every platform, core and FFI work, Linux included.
  2. Keep PRs focused. One logical change per PR; separate refactors from features.
  3. Make sure all quality gates pass locally before pushing (see Dev workflow above).
  4. Use a Conventional Commit title for the PR title. It becomes the squash-merge commit message.
  5. Link related issues with Fixes #N or Refs #N in the PR description.
  6. Check that cargo tree -p agent-desktop-core is clean if you touched any crate dependency.
  7. CI runs automatically on every push. A red CI is a blocker.

Publishing source and diagnostic evidence

Use a reviewed Git revision or the release workflow to assemble public source and packages. Do not upload the working directory or local internal-document archives: ignored files can contain agent settings, transcripts, screenshots and personal filesystem paths. Browser automation captures and local demo recordings also need review before they are added to Git. Ignore rules prevent accidental staging; they do not sanitize files or prevent force-adds.

Run the repository's secret/privacy scan and its scanner regression check before publishing. Credentials must remain detectable in lockfiles, fixtures and lines that also contain safe example values. Review media visually; a text scanner cannot establish that a video, screenshot or audio track is safe.

The supply-chain scan records two exact historical findings for machine SIDs in an old Windows E2E plan. They are absent from the current tree and are not credentials. The exceptions acknowledge their presence in published history; they do not erase it or exempt new SIDs, other commits or credentials. Do not replace these fingerprints with broad path or rule exclusions.

Git commits retain author and committer names and email addresses. Use your account's verified GitHub noreply address for future commits if you do not want a personal address published. Existing public attribution is not a credential leak; changing local Git configuration does not rewrite history. Do not rewrite shared history merely to remove an audit warning.

Reporting bugs and security issues

Bugs and feature requests: use the issue templates; SUPPORT.md says what to include.

Security vulnerabilities: do not open a public issue. Follow SECURITY.md.

Writing with AI coding agents

If an AI coding agent writes any of your contribution's prose, it must use the technical-writer skill. That covers docs pages, READMEs, skills, changelog entries, commit messages, PR descriptions, and issues. The skill sets the voice and editorial standards for this repo and asks agents to check technical claims against the source. Agents that read this repo's AGENTS.md pick up the requirement automatically.

License

By contributing, you agree that your contributions are licensed under the Apache-2.0 License that covers this project.