Skip to main content

​
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:
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: 
> Read the README.md file and summarize its contents

​
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

# 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

Build docs developers (and LLMs) love

Get started for freeTalk to us