Documentation

Building & Development

Task Runner Commands

Arbor uses just as its task runner. All commands apply the pinned Rust nightly toolchain (nightly-2025-11-30) automatically.

Command	Description
just setup-macos	Install macOS dependencies (one-time)
just setup-linux	Install Linux dependencies (one-time)
just format	Auto-fix formatting
just format-check	Check formatting without modifying files
just lint	Run clippy with `-D warnings`
just test	Run all tests
just ci	Full CI suite (format-check + lint + test)
just run	Build and run the desktop app
just run-mcp	Run the daemon and MCP server together
just docs-build	Build the mdBook docs from `docs/src`
just changelog	Preview the full changelog in stdout
just changelog-file <path>	Write a generated changelog file with git-cliff
just run-httpd	Build and run the HTTP daemon

Crate Architecture

Arbor is a workspace of focused crates rather than one monolith. The most important ones are:

Crate	Description
arbor-cli	CLI for Arbor's daemon API (`arbor-cli`)
arbor-daemon-client	Typed client and DTO layer shared by CLI and MCP
arbor-core	Worktree primitives, config parsing, process and task types, agent hooks
arbor-gui	GPUI desktop app (`arbor` binary)
arbor-httpd	Remote HTTP daemon (`arbor-httpd` binary)
arbor-mcp	MCP server backed by the daemon (`arbor-mcp`)
arbor-terminal-emulator	Embedded terminal engine glue and Ghostty integration
arbor-ssh / arbor-mosh	Remote outpost transports
arbor-symphony	Optional workflow orchestration runtime
arbor-web-ui	TypeScript dashboard assets served by the daemon

CI

GitHub Actions runs format, lint, and test checks on pushes to main and pull requests.

Workflow: CI

On pushes to main, CI also runs a cross-platform build matrix:

Linux (x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu)
macOS (aarch64-apple-darwin, x86_64-apple-darwin)
Windows (x86_64-pc-windows-msvc)

Releases

Push a tag in YYYYMMDD.NN format (example: 20260314.01) to trigger an automated release.

The release workflow generates CHANGELOG.md from git history at release time and bundles it into the shipped archives.

Workflow: Release

Artifacts

macOS .app bundle (zipped, universal2, with Info.plist and app icon)
Linux tar.gz bundles (x86_64 and aarch64)
Windows .zip bundle (x86_64)

Changelog

This project uses git-cliff for changelog generation. Config lives in cliff.toml.

The current config matches Arbor's real release tags and commit style: it groups both conventional and sentence-case commits, filters merge commits, skips noise such as docs-only and dependency bumps, and deduplicates repeated merge-history messages.

Command	Description
just changelog	Preview the full changelog in stdout
just changelog-file <path>	Write a generated changelog file to a chosen path
just changelog-unreleased	Preview unreleased entries in stdout
just changelog-release <version>	Preview a release section tagged as `YYYYMMDD.NN`