Thanks for helping. This guide covers gitagent 3, the Rust binary.
- Fork the repository and clone your fork:
git clone https://github.com/<your-username>/gitagent.git cd gitagent
- Install Rust. The toolchain is pinned in
rust-toolchain.toml, sorustuppicks the right version on its own. - Build and test:
cargo build cargo test --workspace
The tests need no network and no API keys. A scripted provider replays model replies from YAML (--model scripted:<file>), and the provider adapters are tested against local mock servers. To try a change by hand:
cargo run -p gitagent-cli -- -d path/to/agent -m scripted:path/to/script.yamlRun all four; CI runs the same:
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
bash scripts/integrity-audit.sh- The benchmark guard must pass.
bench_prompt_and_tools_match_the_published_runfails if the system prompt or the tool list sent to the model in--benchmode changes at all. Features for agent folders, the console or the SDKs must never reach benchmark mode. If a change to the benchmark setup is intended, say so in the pull request; it needs a measured run before it is merged. - Behaviour that changes results is a profile switch. Add it to
profiles/*.yaml, off by default, and describe it indocs/HOW-IT-WORKS.md. - Agents written for the TypeScript gitagent must keep working. Tool names, hook scripts,
agent.yamlfields and SDK options from 1.x and 2.x are accepted; if you change how one is read, keep the old form working and cover it with a test.
The workspace is split into crates under crates/:
| Crate | What it does |
|---|---|
cli |
The gitagent binary: flags, the console, the IPC protocol, subcommands (init, validate, install, plugin, schedule, learn) |
core |
The agent loop, sub-agents, the plan tool, workflows, approvals and the audit log |
loader |
Reads agent folders and configuration into one spec: agent.yaml, identity files, skills, tools, hooks, memory, knowledge, workflows, schedules, plugins, environments, compliance |
provider |
Model adapters: Anthropic, OpenAI, Google, OpenAI-compatible, and the scripted provider for tests |
tools |
Built-in tools: shell, files, edits, memory, skills |
terminal |
Persistent shells on a pseudo-terminal |
shaper |
Shapes command output before the model sees it |
context |
Masking and compaction of the conversation |
guards |
The stop check, the time budget and the loop detector |
hooks |
Hook scripts and their protocol |
mcp |
The Model Context Protocol client |
record |
Trajectories, counters and events |
repo |
Repo mode: clones, branches, commits, pushes |
sandbox |
Landlock and seccomp for the agent's shell; sandbox-exec on macOS |
learn |
Offline learning of lessons from finished runs |
sdk |
The Rust library interface |
The Python and TypeScript clients live under clients/ and talk to the binary over the IPC protocol (gitagent --ipc).
- No unsafe code. The workspace forbids it.
- Small dependencies. Prefer a few lines of code to a new crate.
- Test what you change. Unit tests next to the code, end-to-end tests in
crates/cli/tests/. - One concern per pull request. Keep it focused and reviewable.
- Write docs in plain language. Short sentences, one idea each.
A short subject saying what changed, then a body saying why when it is not obvious:
Parallel tasks: the plan tool and a live task boardHooks that crash are a warning, as in 1.xRepo mode reuses an earlier clone of the same repository
Search the existing issues first. Include what you ran, what you expected, what happened, gitagent --version, and your operating system. A trajectory (trajectory.json from the run's output folder) helps most.
By contributing, you agree that your contributions are licensed under the MIT License.