Quick Start Guide

Get started with Loom in minutes - from installation to your first REPL session

Prerequisites

Before starting, ensure you have:

• Nix (preferred) or Rust toolchain (cargo, rustc)
• A Loom server running (default: http://localhost:8080)
• API keys configured server-side for your chosen LLM provider

Loom uses a server-side proxy architecture. You don’t need API keys on your local machine - they’re stored securely on the server.

Installation

1. Build the CLI

   Choose your preferred build method:

   Nix (Recommended)

   nix build .#loom-cli-c2n
   

   The binary will be available at ./result/bin/loom

   Cargo

   cargo build --release -p loom-cli
   

   The binary will be at ./target/release/loom

2. Configure Server URL

   Set your Loom server URL:

   export LOOM_SERVER_URL=https://loom.ghuntley.com
   

   Or pass it as a flag:

   loom --server-url https://loom.ghuntley.com
   
3. Authenticate

   Log in to the Loom server:

   loom --server-url https://loom.ghuntley.com login
   

   This will open your browser to complete OAuth authentication and store your token securely in the system keyring.

4. Start a REPL Session

   Launch your first interactive session:

   loom
   

   You’ll see output like:

   Welcome to Loom! Type your message and press Enter.
   Thread ID: 01JK8M3N2P4Q5R6S7T8V9W0X1Y
   Type 'exit' or press Ctrl+C to quit.
   
   >
   

Your First Conversation

Let’s try a simple interaction:

User Input

> Read the README.md file and summarize its contents

I'll read the README file for you.

[Tool: read_file]
{"file_path": "README.md"}

Based on the README, this project is Loom - an AI-powered coding 
agent built in Rust. It provides:

1. A REPL interface for LLM interactions
2. Server-side proxy architecture for API keys
3. 30+ specialized Rust crates
4. Support for Anthropic and OpenAI providers
5. Tools for file operations and web search

The project is experimental and under active development.

Available Commands

Session Management

# Start a new session (default)
loom

# List all threads
loom list

# Resume the most recent thread
loom resume

# Resume a specific thread
loom resume 01JK8M3N2P4Q5R6S7T8V9W0X1Y

# Start a private local-only session (never syncs)
loom private

Thread Search

# Search threads by content, branch, repo, or commit SHA
loom search "authentication"
loom search "feature-branch"
loom search "a3f2c1b"  # commit SHA prefix

# Limit results
loom search "bug fix" --limit 5

# Output as JSON
loom search "refactor" --json

Thread Sharing

# Share thread with support team
loom share --support

# Change visibility
loom share --visibility organization
loom share --visibility private
loom share --visibility public

# Share specific thread
loom share 01JK8M3N2P4Q5R6S7T8V9W0X1Y --support

Provider Selection

Choose your LLM provider:

# Use Anthropic (Claude) - default
loom --provider anthropic

# Use OpenAI (GPT)
loom --provider openai

# Or set via environment variable
export LOOM_LLM_PROVIDER=anthropic
loom

Provider models are configured server-side. The --provider flag only selects which proxy endpoint to use.

Remote Execution with Weavers

Weavers are ephemeral Kubernetes pods for running Loom sessions in isolated environments:

1. Create a Weaver

   loom new --image ghcr.io/ghuntley/loom/weaver:latest \
     --repo https://github.com/user/repo \
     --branch main \
     --ttl 4
   
2. List Running Weavers

   loom weaver ps
   
3. Attach to a Weaver

   loom attach <weaver-id>
   
4. Delete a Weaver

   loom weaver delete <weaver-id>
   

Configuration

Loom uses a layered configuration system:

1. Default values - Built-in defaults
2. Config file - ~/.config/loom/config.toml
3. Environment variables - LOOM_* prefixed
4. CLI arguments - Highest priority

Example Config File

~/.config/loom/config.toml

[global]
default_provider = "anthropic"
workspace_root = "/home/user/projects"

[logging]
level = "info"
format = "pretty"  # or "json", "compact"

[tools.workspace]
root = "/home/user/workspace"

Auto-Commit Feature

Loom automatically creates git commits when file-modifying tools are executed:

# Auto-commit is enabled by default
loom

# Disable auto-commit
LOOM_AUTO_COMMIT_DISABLE=1 loom

When enabled, Loom uses Claude Haiku to generate commit messages based on:

• File changes detected
• Tools executed (edit_file, bash)
• Conversation context

Auto-commit only works in git repositories. It will skip commits if:

• Not in a git repo
• No changes detected
• Diff exceeds 32KB

Logging

Control log output:

# Set log level
loom --log-level debug
loom --log-level info
loom --log-level warn

# JSON logs for structured parsing
loom --json-logs

# Or via environment
export RUST_LOG=loom=debug
loom

Next Steps

Installation Details

Learn about Nix builds, cargo2nix, and development workflows

Tool System

Explore the available tools and how to implement custom tools

Thread System

Understand conversation persistence and FTS5 search

Architecture Overview

Read about Loom’s architecture and design principles

Troubleshooting

Connection Refused

If you see Connection refused errors:

1. Verify the server is running: curl http://localhost:8080/health
2. Check your --server-url matches the actual server
3. Ensure you’re authenticated: loom login

Authentication Errors

401 Unauthorized responses mean:

• You’re not logged in: Run loom login
• Your token expired: Run loom logout then loom login
• Server authentication is misconfigured

Tool Execution Failures

If tools fail:

• Check workspace permissions: ls -la $(pwd)
• Verify you’re in the correct directory
• Check logs with --log-level debug