Skip to main content
Loom is organized as a Cargo workspace with 80+ specialized crates. This modular architecture enables parallel compilation, clean dependency boundaries, and reusable components across CLI, server, and TUI applications.

​
Workspace Configuration

The root Cargo.toml defines workspace members and shared dependencies: 
[workspace]
resolver = "2"
members = [
    "crates/loom-cli-acp",
    "crates/loom-server-auth",
    "crates/loom-server-auth-devicecode",
    "crates/loom-server-auth-github",
    # ... 80+ total crates
]

[workspace.package]
version = "0.1.0"
authors = ["Geoffrey Huntley"]
edition = "2021"
license = "LicenseRef-Proprietary"
repository = "https://github.com/ghuntley/loom"

​
Crate Categories

​
Common Layer (loom-common-*)

Foundation crates providing shared functionality across all applications.
Core abstractions and types
  • LlmClient trait for LLM provider abstraction
  • Agent state machine for conversation flow
  • LlmRequest, LlmResponse, LlmStream types
  • Message, Role, ToolCall message types
  • AgentState, AgentEvent, AgentAction enums
  • ToolDefinition, ToolContext for tool system
Key Files:
  • agent.rs - Agent state machine implementation
  • llm.rs - LLM client trait and types
  • state.rs - State machine types
  • message.rs - Message types
  • tool.rs - Tool abstractions
  • error.rs - Error types
Shared HTTP utilities
  • new_client() - Creates HTTP client with standard User-Agent
  • builder() - Returns ClientBuilder with User-Agent
  • RetryConfig - Configurable retry parameters
  • RetryableError trait - Determines retry eligibility
  • retry() function - Exponential backoff wrapper
User-Agent format: loom/{platform}/{git_sha}
Configuration management
  • Layered config: CLI args → env vars → config file → defaults
  • XDG Base Directory compliance
  • TOML configuration format
  • Environment variable overrides
Secret handling
  • Secret<T> wrapper for sensitive values
  • SecretString type alias
  • Auto-redaction in Debug/Display/Serialize
  • expose() method for controlled access
  • Integration with tracing (auto-skip in logs)
Conversation persistence
  • SQLite-based thread storage
  • FTS5 full-text search
  • Git metadata tracking
  • Cross-device sync
  • Message history management
Webhook handling
  • Webhook signature verification
  • Event payload parsing
  • Retry logic for failed webhooks
Internationalization
  • GNU gettext-based translation
  • 17 supported locales
  • .po files compiled to .mo at build time
  • t() and t_fmt() translation functions
  • RTL language support
Locales: en, es, ar, fr, de, ja, zh, ko, pt, ru, hi, it, nl, pl, tr, vi, th
Version control integration
  • jj (Jujutsu) VCS integration
  • Tapestry naming (stitch, pin, tangle)
  • Conflict-free replicated data types
Version management
  • Semantic versioning
  • Git commit tracking
  • Build metadata

​
Server Layer (loom-server-*)

Server-side components for HTTP API, authentication, and LLM integration.
Main HTTP API server
  • Axum-based HTTP server
  • OpenAPI documentation with Swagger UI
  • Health check endpoint (/health)
  • WebSocket support for real-time updates
  • Graceful shutdown
  • Database migrations
Migrations: crates/loom-server/migrations/NNN_description.sql
API route handlers
  • Thread management routes
  • Weaver provisioning routes
  • Analytics routes
  • Feature flag routes
  • SCIM routes
  • SCM routes
Database access layer
  • SQLite with sqlx
  • Connection pooling
  • Migration management
  • Query builders
LLM provider abstraction
  • LlmService - Multi-provider support
  • Provider availability checks: has_anthropic(), has_openai(), etc.
  • Provider-specific methods: complete_anthropic(), complete_openai(), etc.
  • Owns all API keys server-side
Dependencies:
  • loom-server-llm-anthropic
  • loom-server-llm-openai
  • loom-server-llm-vertex
  • loom-server-llm-zai
Client-side LLM proxy
  • ProxyLlmClient - Implements LlmClient via HTTP
  • Provider-specific constructors: anthropic(), openai(), vertex(), zai()
  • SSE stream parsing
  • Bearer token authentication
Anthropic Claude client
  • Claude API integration
  • SSE streaming support
  • Tool calling
  • System message handling
  • OAuth 2.0 PKCE for Claude Pro/Max subscriptions
OpenAI GPT client
  • OpenAI API integration
  • Streaming completions
  • Function calling
  • Organization support
Google Vertex AI client
  • Vertex AI API integration
  • Gemini Pro, Gemini Flash models
  • Service account authentication
Z.ai client (智谱AI)
  • Z.ai API integration (OpenAI-compatible)
  • GLM-4 models: glm-4.7, glm-4.6, glm-4.5, etc.
  • Streaming support
Authentication providers
  • loom-server-auth - Auth abstraction layer
  • loom-server-auth-devicecode - Device code flow (OAuth 2.0)
  • loom-server-auth-github - GitHub OAuth
  • loom-server-auth-google - Google OAuth
  • loom-server-auth-magiclink - Email magic links
  • loom-server-auth-okta - Okta OIDC
ABAC: Attribute-based access control
Kubernetes integration
  • Pod provisioning
  • Service discovery
  • Resource management
  • Health checks
Remote execution pods
  • Weaver provisioning
  • Lifecycle management
  • Resource limits
  • Audit logging
Git hosting
  • Repository management
  • Branch protection
  • Webhooks
  • Mirroring
  • Access control
  • loom-server-session - Session management
  • loom-server-geoip - IP geolocation
  • loom-server-jobs - Background job scheduler
  • loom-server-smtp - Email sending
  • loom-server-email - Email templates and i18n
  • loom-server-github-app - GitHub App integration
  • loom-server-search-serper - Serper API search
  • loom-server-search-google-cse - Google Custom Search
  • loom-server-provisioning - User/org provisioning
  • loom-server-scim - SCIM 2.0 for IdP integration
  • loom-server-audit - Audit logging with SIEM
  • loom-server-config - Server configuration
  • loom-server-logs - Log aggregation
  • loom-server-clips - Code snippet sharing (gists)
  • loom-server-secrets - Secret management for weavers
  • loom-server-wgtunnel - WireGuard tunnel server
  • loom-server-docs - Documentation API

​
CLI Layer (loom-cli-*)

Command-line interface and related utilities.
Main CLI binary
  • Command-line argument parsing (clap)
  • REPL loop
  • Tool execution orchestration
  • ProxyLlmClient integration
  • Thread management
  • Weaver management
CLI configuration
  • CLI-specific settings
  • Server URL configuration
  • Default model selection
Credential management
  • OAuth token storage
  • Keychain integration
  • Token refresh
Agent tool implementations
  • ReadFileTool - Read file contents
  • ListFilesTool - List directory contents
  • EditFileTool - Edit file with search/replace
  • BashTool - Execute bash commands
  • GrepTool - Search file contents
  • GlobTool - Find files by pattern
  • Tool registry
Git operations
  • Repository detection
  • File staging
  • Commit creation
  • Git metadata tracking
Auto-commit orchestration
  • Post-tool hook integration
  • LLM-powered commit message generation
  • Automatic staging and committing
Agent Client Protocol
  • Editor integration protocol
  • JSON-RPC communication
  • Event streaming
Spool (jj) integration
  • Jujutsu VCS operations
  • Tapestry workflow support
WireGuard tunnel client
  • WireGuard tunnel management for weaver access
  • DERP relay support

​
Observability Suite

Integrated observability platform inspired by Sentry/PostHog.
PostHog-style product analytics
  • loom-analytics-core - Core types and traits
  • loom-analytics - Client library
  • loom-server-analytics - Server ingestion and storage
Features:
  • Event tracking
  • User identification
  • Identity resolution (merge users across devices)
  • Funnel analysis
  • Cohort analysis
Crash analytics with symbolication
  • loom-crash-core - Core crash types
  • loom-crash - Client crash reporter
  • loom-crash-symbolicate - Source map symbolication
  • loom-server-crash - Crash ingestion and deduplication
Features:
  • Stack trace capture
  • Regression detection
  • Crash grouping
  • Source map upload and symbolication
Scheduled job monitoring
  • loom-crons-core - Cron core types
  • loom-crons - Client check-in library
  • loom-server-crons - Cron monitoring server
Features:
  • Ping URL check-ins
  • SDK check-ins with duration tracking
  • Miss detection
  • Alert integration
Session health tracking
  • loom-sessions-core - Session core types
  • loom-server-sessions - Session analytics server
Features:
  • Release health tracking
  • Crash-free session rate
  • Session replay
  • Adoption tracking
Runtime feature toggles
  • loom-flags-core - Flag core types
  • loom-flags - Client flag evaluation
  • loom-server-flags - Flag management server
Features:
  • Boolean flags
  • Multivariate flags
  • Percentage rollouts
  • User/org targeting
  • Kill switches
  • SSE updates for real-time changes

​
TUI Layer (loom-tui-*)

Terminal user interface components based on Ratatui 0.30.
Main TUI application
  • Event loop
  • Screen management
  • Keyboard handling
  • Component composition
Core TUI abstractions
  • Component trait
  • Event system
  • State management
Component system
  • Composable components
  • Props pattern
  • Event propagation
Theming support
  • Color schemes
  • Style definitions
  • Theme switching
Reusable widgets
  • loom-tui-widget-message-list - Chat message display
  • loom-tui-widget-input-box - Text input
  • loom-tui-widget-markdown - Markdown rendering
  • loom-tui-widget-thread-list - Thread/conversation list
  • loom-tui-widget-tool-panel - Tool execution status
  • loom-tui-widget-status-bar - Status information
  • loom-tui-widget-header - Application header
  • loom-tui-widget-modal - Modal dialogs
  • loom-tui-widget-spinner - Loading spinner
  • loom-tui-widget-scrollable - Scrollable containers
Visual snapshot testing
  • Component storybook
  • Visual regression tests
  • Screenshot comparison
TUI testing utilities
  • Mock terminal
  • Event simulation
  • Snapshot assertions

​
Weaver (Remote Execution)

Kubernetes-based remote execution environment.
SPIFFE-style identity and secrets
  • SPIFFE Verifiable Identity Document (SVID)
  • Secret injection into pods
  • Rotation support
eBPF syscall auditing
  • eBPF program loader
  • Syscall event capture
  • Audit log streaming
WireGuard tunnel for weaver access
  • WireGuard client for weaver pods
  • Tunnel setup and teardown
eBPF programs
  • Syscall tracing programs
  • Network monitoring
  • File access tracking
WireGuard tunnel with DERP relay
  • loom-wgtunnel-common - Shared types
  • loom-wgtunnel-conn - Connection management
  • loom-wgtunnel-derp - DERP relay protocol
  • loom-wgtunnel-engine - Tunnel engine
Enables SSH and TCP access to weavers behind NAT.

​
Utility Crates

Secret detection
  • Gitleaks pattern-based detection
  • Automatic redaction
  • Secret scanning
SCIM 2.0 types
  • RFC 7643/7644 compliance
  • User/Group resources
  • Patch operations
Background job system
  • Job queue
  • Worker pool
  • Retry logic
WhatsApp Business API
  • Message sending
  • Webhook handling
  • Media support

​
Dependency Graph

The workspace follows strict layering: 
loom-common-core (bottom layer)
    ↑
loom-common-http
    ↑
loom-server-llm-* (provider implementations, server-only)
    ↑
loom-server-llm-service (provider abstraction)
    ↑
loom-server (HTTP server)
    ↑
loom-server-llm-proxy (client-side proxy client)
    ↑
loom-cli-tools (depends only on loom-common-core)
    ↑
loom-cli (top layer)
Key constraint: Lower-layer crates never depend on higher-layer crates. This ensures:
  • Core types are reusable
  • Provider implementations are isolated to server-side
  • Clear compilation order

​
Build Optimization

​
Profile Settings

The workspace uses custom build profiles for faster development: 
[profile.dev]
debug = 1                    # Reduced debug info
split-debuginfo = "unpacked" # Faster linking
incremental = true

[profile.dev.package.loom-server]
codegen-units = 256          # More parallelism for large crates

[profile.dev-fast]
inherits = "dev"
debug = 0                    # No debug info for fastest builds
codegen-units = 512

[profile.release]
lto = false
opt-level = 0                # Zero optimization for fast compile
codegen-units = 256
strip = "debuginfo"

​
cargo2nix Integration

The workspace uses cargo2nix for reproducible builds: 
# Update Cargo.nix after modifying Cargo.lock
cargo2nix-update

# Build any crate
nix build .#loom-common-core-c2n
cargo2nix provides per-crate caching, making incremental builds much faster than cargo alone.

​
Database Migrations

All database migrations must go in crates/loom-server/migrations/ as numbered SQL files.Convention: NNN_description.sql (e.g., 020_scm_repos.sql)DO NOT put inline SQL migrations in other crates.
Migrations run automatically on server startup. After adding/modifying migrations:
  1. Run cargo2nix-update (cargo2nix doesn’t track include_str! file changes)
  2. Commit Cargo.nix along with migration changes
  3. Without this step, deployed binary won’t include the new migration!

​
Testing Strategy

​
Unit Tests

Most crates include unit tests in src/ files or tests/ directory.

​
Integration Tests

Integration tests live in crate-specific tests/ directories.

​
Property-Based Tests

Critical crates use proptest for property-based testing: 
use proptest::prelude::*;

proptest! {
    #[test]
    fn agent_always_starts_in_waiting(
        config in any::<AgentConfig>()
    ) {
        let agent = Agent::new(config);
        assert!(matches!(agent.state(), AgentState::WaitingForUserInput { .. }));
    }
}

​
Next Steps

Architecture Overview

High-level system design

LLM Proxy

Server-side LLM proxy details

State Machine

Agent state machine design

Specifications

Browse all technical specs

Build docs developers (and LLMs) love

Get started for freeTalk to us