Skip to content

CLAUDE.md

Latest commit

 

History

History
132 lines (94 loc) · 6.35 KB

CLAUDE.md

File metadata and controls

132 lines (94 loc) · 6.35 KB

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

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