agentleFS
pensopenso/arbor/CLAUDE.md

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.

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
  1. Distinctive:

    Keep code simple, explicit, and maintainable.

    line 7
  2. Very specific:

    Run HTTP daemon: just run-httpd

    line 23
  3. Distinctive:

    Always run these checks before committing and fix any issues:

    line 27
  4. Very specific:

    If any check fails, fix the issue, then commit the fix.

    line 33
  5. Very specific:

    Never skip just format or just lint before a commit, even for small changes.

    line 34
  6. Very specific:

    No Co-Authored-By trailers: Update README.md features list with feat commits.

    line 39
  7. Very specific:

    Do not use unwrap() or expect() in non-test code.

    line 43
  8. Very specific:

    Use clear error handling with typed errors (thiserror/anyhow where appropriate).

    line 44
  9. Very specific:

    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 …

    line 45
  10. Very specific:

    Use SessionId and WorkspaceId newtypes from arbor_core::id instead of raw String for session/workspace identifiers.

    line 46
  11. Distinctive:

    Keep modules focused and delete dead code instead of leaving it around.

    line 47
  12. Very specific:

    Use pub(crate) visibility for items shared within a crate but not exported.

    line 54
  13. Very specific:

    Use pub(crate) use module::* glob re-exports in parent modules to keep call sites clean after extraction.

    line 55
  14. Very specific:

    When splitting impl blocks across files, the struct definition stays in types.rs and method impls go in the relevant domain file.

    line 56
  15. Very specific:

    When adding a new optional dependency, use dep:crate_name syntax in the feature definition and mark the dependency as optional = true.

    line 65
  16. Very specific:

    All third-party dependency versions are centralized in the root Cargo.toml under [workspace.dependencies].

    line 70
  17. Distinctive:

    Treat git status / git diff as read-only context.

    line 74
  18. Distinctive:

    Do not run destructive git commands.

    line 75
  19. Distinctive:

    Do not amend commits unless explicitly asked.

    line 76
  20. Distinctive:

    Only create commits when the user asks.

    line 77
  21. Very specific:

    When working in a worktree linked to a pull request, check .arbor/pr-comments.md for review comments left by reviewers.

    line 81
  22. Very specific:

    When adding or modifying UI, use screencapture -x /tmp/screenshot.png to take a screenshot and verify the result visually.

    line 92
  23. Very specific:

    Use git-cliff for changelog generation (config: cliff.toml).

    line 96

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides instructions for Claude Code when working in this repository.

Priorities

  1. Keep code simple, explicit, and maintainable.
  2. Fix root causes, avoid temporary band-aids.
  3. 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:

  1. just format — auto-fix formatting
  2. just lint — must pass with zero warnings (-D warnings)
  3. 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() or expect() 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/anyhow where appropriate).
  • 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 format strings.
  • Use SessionId and WorkspaceId newtypes from arbor_core::id instead of raw String for 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 let statements when possible (clippy collapsible_if).
  • Never shell out to external CLIs (gh, git via Command::new, etc.) for GitHub API calls or operations that can be done with Rust crates. Use octocrab, reqwest, or other Rust HTTP/API crates instead. The only acceptable use of std::process::Command is 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 impl blocks across files, the struct definition stays in types.rs and 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_name syntax in the feature definition and mark the dependency as optional = true.
  • Feature flags should be hierarchical: mosh implies ssh.

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 diff as 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-cliff for changelog generation (config: cliff.toml).
  • CHANGELOG.md is 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

CrateDescription
arbor-cliCommand-line interface (arbor binary) for scripting and automation
arbor-coreWorktree primitives, change detection, agent hooks, shared types (SessionId, WorkspaceId, ResultExt)
arbor-daemon-clientHTTP client for talking to arbor-httpd
arbor-guiGPUI desktop app (Arbor binary)
arbor-httpdRemote HTTP daemon (arbor-httpd binary)
arbor-mcpMCP server for AI agent integration
arbor-moshMosh shell backend (optional)
arbor-sshSSH shell backend (optional)
arbor-terminal-emulatorTerminal emulation layer
arbor-web-uiTypeScript dashboard assets + helper crate

Key files in arbor-gui

FileContents
main.rsApp entry point, ArborWindow struct and its impl blocks, GPUI rendering
actions.rsactions!() macro definitions
constants.rsAll const values, font registration
types.rsStruct/enum definitions (DTOs, UI state types)
helpers.rsFree functions, impl blocks for helper methods
terminal_runtime.rsTerminal backend traits and impls (SSH, Mosh, local)

Key files in arbor-httpd

FileContents
main.rsServer startup, router setup
types.rsAppState, config types, API error types
routes.rsAll route handler functions

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.