Skip to content

CLAUDE.md

Latest commit

 

History

History
112 lines (86 loc) · 4.09 KB

CLAUDE.md

File metadata and controls

112 lines (86 loc) · 4.09 KB

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Repository Overview

Orbit Rust Backend is a Rust implementation of an AI agent SDK, being converted from the TypeScript OpenCode project. The original TypeScript source is in OpenCode-reference/ for reference.

Project Structure

agentsdk/
├── crates/                 # Rust workspace crates (main code)
├── Conversion/             # Conversion planning & progress docs
├── OpenCode-reference/     # Original TypeScript source (read-only reference)
├── Cargo.toml              # Workspace manifest
└── README.md

Common Commands

# Check compilation
cargo check --workspace

# Run all tests
cargo test --workspace

# Run specific crate tests
cargo test -p orbit-core

# Watch mode (install: cargo install cargo-watch)
cargo watch -x test

# Clippy lint
cargo clippy --workspace -- -D warnings

# Format
cargo fmt

# Build release
cargo build --release

Crate Architecture

Crate Purpose Dependencies
orbit-core Foundation utilities (id, log, lock, filesystem) None (internal)
orbit-bus Event pub/sub system orbit-core
orbit-storage JSON file storage orbit-core
orbit-project Project detection, instance context orbit-core, orbit-storage, orbit-bus
orbit-config Configuration loading orbit-core, orbit-storage, orbit-project, orbit-bus
orbit-permission Permission rules orbit-core, orbit-bus, orbit-config, orbit-project, orbit-storage
orbit-provider AI provider adapters orbit-core, orbit-config
orbit-session Session state management orbit-core, orbit-storage, orbit-bus, orbit-project, orbit-provider, orbit-permission, orbit-config
orbit-tools Agent tools (bash, read, write, etc.) orbit-core, orbit-session, orbit-project, orbit-permission, orbit-bus, orbit-config
orbit-lsp LSP client orbit-core, orbit-project, orbit-bus, orbit-config
orbit-mcp MCP client orbit-core, orbit-project, orbit-config, orbit-bus, orbit-storage
orbit-server HTTP API server (Axum) All crates

Conversion Workflow

  1. Read planning docs in Conversion/ folder (start with CLAUDE.md there)
  2. Reference TypeScript in OpenCode-reference/packages/opencode/src/
  3. Implement in Rust in crates/orbit-*/src/
  4. Port tests from OpenCode-reference/packages/opencode/test/
  5. Update progress in Conversion/04-Progress-Tracking/

Code Style (Rust)

  • Use thiserror for error types
  • Use async-trait for async traits
  • Use serde with derive macros for serialization
  • Prefer tokio for async runtime
  • Use tracing for logging
  • No unwrap() in library code (use ? or expect() with message)
  • Run cargo fmt before committing
  • Run cargo clippy and fix all warnings

Key TypeScript → Rust Mappings

TypeScript Rust
AsyncLocalStorage tokio::task_local!
Zod schemas serde + runtime validation
namespace Module pub mod module
Promise<T> async fn -> Result<T>
Record<K, V> HashMap<K, V>
Bun.file() tokio::fs
Bun.spawn() tokio::process::Command
Hono server axum

Reference TypeScript Code

When implementing a Rust module, reference the corresponding TypeScript:

TypeScript                              Rust
─────────────────────────────────────────────────────────────
OpenCode-reference/packages/opencode/
  src/id/id.ts                    →   crates/orbit-core/src/id.rs
  src/util/lock.ts                →   crates/orbit-core/src/lock.rs
  src/tool/bash.ts                →   crates/orbit-tools/src/tools/bash.rs
  src/session/prompt.ts           →   crates/orbit-session/src/processor.rs
  test/util/lock.test.ts          →   crates/orbit-core/src/lock.rs (#[cfg(test)])

Do Not Modify

  • OpenCode-reference/ - Read-only reference, do not edit
  • Files generated by cargo in target/