> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ghuntley/loom/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

## Installation

<Steps>
  <Step title="Build the CLI">
    Choose your preferred build method:

    <Tabs>
      <Tab title="Nix (Recommended)">
        ```bash theme={null}
        nix build .#loom-cli-c2n
        ```

        The binary will be available at `./result/bin/loom`
      </Tab>

      <Tab title="Cargo">
        ```bash theme={null}
        cargo build --release -p loom-cli
        ```

        The binary will be at `./target/release/loom`
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Server URL">
    Set your Loom server URL:

    ```bash theme={null}
    export LOOM_SERVER_URL=https://loom.ghuntley.com
    ```

    Or pass it as a flag:

    ```bash theme={null}
    loom --server-url https://loom.ghuntley.com
    ```
  </Step>

  <Step title="Authenticate">
    Log in to the Loom server:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Start a REPL Session">
    Launch your first interactive session:

    ```bash theme={null}
    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.

    >
    ```
  </Step>
</Steps>

## Your First Conversation

Let's try a simple interaction:

<CodeGroup>
  ```bash User Input theme={null}
  > Read the README.md file and summarize its contents
  ```

  ```bash Agent Response theme={null}
  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.
  ```
</CodeGroup>

## Available Commands

### Session Management

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# Use Anthropic (Claude) - default
loom --provider anthropic

# Use OpenAI (GPT)
loom --provider openai

# Or set via environment variable
export LOOM_LLM_PROVIDER=anthropic
loom
```

<Note>
  Provider models are configured server-side. The `--provider` flag only selects which proxy endpoint to use.
</Note>

## Remote Execution with Weavers

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

<Steps>
  <Step title="Create a Weaver">
    ```bash theme={null}
    loom new --image ghcr.io/ghuntley/loom/weaver:latest \
      --repo https://github.com/user/repo \
      --branch main \
      --ttl 4
    ```
  </Step>

  <Step title="List Running Weavers">
    ```bash theme={null}
    loom weaver ps
    ```
  </Step>

  <Step title="Attach to a Weaver">
    ```bash theme={null}
    loom attach <weaver-id>
    ```
  </Step>

  <Step title="Delete a Weaver">
    ```bash theme={null}
    loom weaver delete <weaver-id>
    ```
  </Step>
</Steps>

## 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

```toml ~/.config/loom/config.toml theme={null}
[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:

```bash theme={null}
# 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

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

  * Not in a git repo
  * No changes detected
  * Diff exceeds 32KB
</Warning>

## Logging

Control log output:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Installation Details" icon="wrench" href="/installation">
    Learn about Nix builds, cargo2nix, and development workflows
  </Card>

  <Card title="Tool System" icon="toolbox" href="/features/tools">
    Explore the available tools and how to implement custom tools
  </Card>

  <Card title="Thread System" icon="database" href="/features/thread-system">
    Understand conversation persistence and FTS5 search
  </Card>

  <Card title="Architecture Overview" icon="book" href="/architecture/overview">
    Read about Loom's architecture and design principles
  </Card>
</CardGroup>

## 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`