arbor
CLAUDE.md837 starsChanged 8 months agoMITView on GitHub
This file provides instructions for Claude Code when working in this repository. This project uses a pinned Rust nightly toolchain: nightly-2025-11-30. All commands go through just recipes which apply the correct toolchain automatically. Always run these checks before committing and fix any issues: If any check fails, fix the issue, then commit the fix. Never skip just format or just lint before a commit, even for small changes. Conventional commits: feat|fix|docs|style|refactor|test|chore(scope): description No Co-Authored-By trailers. Update README.md features list with…
In this repositoryOne other file it gives its agents.
- AGENTS.mdAGENTS.md
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
23 rules. About 0 are common, 7 are distinctive, and 16 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
16
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 7
Keep code simple, explicit, and maintainable.
- Very specific: line 23
Run HTTP daemon: just run-httpd
- Distinctive: line 27
Always run these checks before committing and fix any issues:
- Very specific: line 33
If any check fails, fix the issue, then commit the fix.
- Very specific: line 34
Never skip just format or just lint before a commit, even for small changes.
- Very specific: line 39
No
Co-Authored-Bytrailers: Update README.md features list with feat commits. - Very specific: line 43
Do not use unwrap() or expect() in non-test code.
- Very specific: line 44
Use clear error handling with typed errors (thiserror/anyhow where appropriate).
- Very specific: line 45
Use arbor_core::ResultExt and arbor_core::OptionExt for .context() on Result<T, E> and Option<T> — prefer these over ad-hoc .map_err() with …
- Very specific: line 46
Use SessionId and WorkspaceId newtypes from arbor_core::id instead of raw String for session/workspace identifiers.
- Distinctive: line 47
Keep modules focused and delete dead code instead of leaving it around.
- Very specific: line 54
Use pub(crate) visibility for items shared within a crate but not exported.
- Very specific: line 55
Use pub(crate) use module::* glob re-exports in parent modules to keep call sites clean after extraction.
- Very specific: line 56
When splitting impl blocks across files, the struct definition stays in types.rs and method impls go in the relevant domain file.
- Very specific: line 65
When adding a new optional dependency, use dep:crate_name syntax in the feature definition and mark the dependency as optional = true.
- Very specific: line 70
All third-party dependency versions are centralized in the root Cargo.toml under [workspace.dependencies].
- Distinctive: line 74
Treat git status / git diff as read-only context.
- Distinctive: line 75
Do not run destructive git commands.
- Distinctive: line 76
Do not amend commits unless explicitly asked.
- Distinctive: line 77
Only create commits when the user asks.
- Very specific: line 81
When working in a worktree linked to a pull request, check .arbor/pr-comments.md for review comments left by reviewers.
- Very specific: line 92
When adding or modifying UI, use screencapture -x /tmp/screenshot.png to take a screenshot and verify the result visually.
- Very specific: line 96
Use git-cliff for changelog generation (config: cliff.toml).
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides instructions for Claude Code when working in this repository.
Priorities
- Keep code simple, explicit, and maintainable.
- Fix root causes, avoid temporary band-aids.
- Preserve user changes, never revert unrelated edits.
Toolchain
This project uses a pinned Rust nightly toolchain: nightly-2025-11-30. All commands go through just recipes which apply the correct toolchain automatically.
Commands
- Format:
just format - Format check:
just format-check - Lint (clippy):
just lint - Test:
just test - Full CI suite:
just ci - Run app:
just run - Run HTTP daemon:
just run-httpd
Before Committing / Pushing
Always run these checks before committing and fix any issues:
just format— auto-fix formattingjust lint— must pass with zero warnings (-D warnings)just test— all tests must pass
If any check fails, fix the issue, then commit the fix.
Never skip just format or just lint before a commit, even for small changes.
Git Workflow
Conventional commits: feat|fix|docs|style|refactor|test|chore(scope): description
No Co-Authored-By trailers. Update README.md features list with feat commits.
Rust Rules
- Do not use
unwrap()orexpect()in non-test code. In test modules, use#[allow(clippy::unwrap_used, clippy::expect_used)]on the module. - Use clear error handling with typed errors (
thiserror/anyhowwhere appropriate). - Use
arbor_core::ResultExtandarbor_core::OptionExtfor.context()onResult<T, E>andOption<T>— prefer these over ad-hoc.map_err()with format strings. - Use
SessionIdandWorkspaceIdnewtypes fromarbor_core::idinstead of rawStringfor session/workspace identifiers. These are#[serde(transparent)]for wire compatibility. - Keep modules focused and delete dead code instead of leaving it around.
- Collapse nested
if/if letstatements when possible (clippycollapsible_if). - Never shell out to external CLIs (
gh,gitviaCommand::new, etc.) for GitHub API calls or operations that can be done with Rust crates. Useoctocrab,reqwest, or other Rust HTTP/API crates instead. The only acceptable use ofstd::process::Commandis where no Rust crate equivalent exists.
Module Organization
- Split large files by domain: types, constants, helpers, actions. Keep files under ~800 lines where practical.
- Use
pub(crate)visibility for items shared within a crate but not exported. Apply to struct fields, methods, and free functions in submodules. - Use
pub(crate) use module::*glob re-exports in parent modules to keep call sites clean after extraction. - When splitting
implblocks across files, the struct definition stays intypes.rsand method impls go in the relevant domain file.
Feature Flags
Optional functionality is gated behind Cargo features:
- arbor-gui:
ssh,mosh,mdns(all on by default). Use#[cfg(feature = "...")]on modules, functions, and imports that depend on optional crates. - arbor-httpd:
mdns(on by default). - arbor-core:
ssh,mosh(propagated from downstream crates). - When adding a new optional dependency, use
dep:crate_namesyntax in the feature definition and mark the dependency asoptional = true. - Feature flags should be hierarchical:
moshimpliesssh.
Workspace Dependencies
All third-party dependency versions are centralized in the root Cargo.toml under [workspace.dependencies]. Crate-level Cargo.toml files must use { workspace = true } (with optional extra keys like features or optional). Never hardcode a version in a subcrate — add it to the workspace root first.
Git Rules
- Treat
git status/git diffas read-only context. - Do not run destructive git commands.
- Do not amend commits unless explicitly asked.
- Only create commits when the user asks.
PR Review Comments
When working in a worktree linked to a pull request, check .arbor/pr-comments.md for
review comments left by reviewers. This file is auto-generated by the Arbor GUI and
contains all PR review threads grouped by file path. Address unresolved comments when
they relate to your current task. Delete .arbor/pr-comments.md before merging to main.
UI Development Order
The native GPUI desktop app (arbor-gui) is the primary UI. When adding or modifying UI features, implement in the native app first, then port to the web UI (arbor-web-ui). This ensures the native app stays the reference implementation and avoids drift between the two.
UI Verification
When adding or modifying UI, use screencapture -x /tmp/screenshot.png to take a screenshot and verify the result visually. Run the app with just run, capture, then inspect the image.
Changelog
- Use
git-clifffor changelog generation (config:cliff.toml). CHANGELOG.mdis generated for release artifacts instead of being tracked in git.just changelog/just changelog-file <path>/just changelog-unreleased/just changelog-release <version>
Project Structure
| Crate | Description |
arbor-cli | Command-line interface (arbor binary) for scripting and automation |
arbor-core | Worktree primitives, change detection, agent hooks, shared types (SessionId, WorkspaceId, ResultExt) |
arbor-daemon-client | HTTP client for talking to arbor-httpd |
arbor-gui | GPUI desktop app (Arbor binary) |
arbor-httpd | Remote HTTP daemon (arbor-httpd binary) |
arbor-mcp | MCP server for AI agent integration |
arbor-mosh | Mosh shell backend (optional) |
arbor-ssh | SSH shell backend (optional) |
arbor-terminal-emulator | Terminal emulation layer |
arbor-web-ui | TypeScript dashboard assets + helper crate |
Key files in arbor-gui
| File | Contents |
main.rs | App entry point, ArborWindow struct and its impl blocks, GPUI rendering |
actions.rs | actions!() macro definitions |
constants.rs | All const values, font registration |
types.rs | Struct/enum definitions (DTOs, UI state types) |
helpers.rs | Free functions, impl blocks for helper methods |
terminal_runtime.rs | Terminal backend traits and impls (SSH, Mosh, local) |
Key files in arbor-httpd
| File | Contents |
main.rs | Server startup, router setup |
types.rs | AppState, config types, API error types |
routes.rs | All route handler functions |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

