REPL Commands

Interactive AI coding assistant REPL with tool-calling capabilities

Overview

The Loom REPL (Read-Eval-Print Loop) provides an interactive conversation interface with an AI coding agent. The agent has access to tools for reading, editing, and executing code in your workspace.

Starting a REPL Session

# Start new session
loom

# Start with specific workspace
loom --workspace /path/to/project

# Start with specific provider
loom --provider openai

# Start private (local-only) session
loom private

REPL Interface

When you start a session, you’ll see:

Welcome to Loom! Type your request and press Enter.
Thread ID: 01HX2K3M4N5P6Q7R8S9T0V1W2X3Y4Z5A6B7C8D9E
Type your message or press Ctrl+C to exit.

> 

Interaction Flow

1. User Input: Type your request in natural language
2. Agent Response: The AI agent responds with text and/or tool calls
3. Tool Execution: Tools are executed automatically (bash, file edits, etc.)
4. Agent Continuation: Agent receives tool results and continues
5. Repeat: Conversation continues until you exit (Ctrl+C or EOF)

Available Tools

The agent has access to the following tools:

read_file

Read the contents of a file from the workspace.

path · string · required

Path to the file to read (absolute or relative to workspace)

max_bytes · integer · default: 1048576

Maximum number of bytes to read (default: 1MB)

Example Usage:

> Show me the contents of src/main.rs

The agent will use read_file to retrieve and display the file contents.

edit_file

Edit a file by replacing text snippets.

path · string · required

Path to the file to edit

edits · array · required

Array of edit operations to apply

Edit Operation:

edits[].old_str · string · required

Text to find and replace

edits[].new_str · string · required

Replacement text

edits[].replace_all · boolean · default: false

Replace all occurrences (default: false - fails if multiple matches)

Example Usage:

> Change the function name from "processData" to "handleData" in src/lib.rs

The agent will use edit_file to perform the text replacement.

list_files

List files in a directory with optional glob patterns.

path · string

Directory path (defaults to workspace root)

pattern · string

Glob pattern to filter files (e.g., “.rs”, “src/**/.ts”)

recursive · boolean · default: false

List files recursively

Example Usage:

> List all Rust files in the src directory

bash

Execute shell commands in the workspace directory.

command · string · required

Shell command to execute

cwd · string

Working directory (relative to workspace root)

timeout_secs · integer · default: 60

Command timeout in seconds (max: 300)

Limits:

• Default timeout: 60 seconds
• Maximum timeout: 300 seconds (5 minutes)
• Maximum output: 256KB per stream (stdout/stderr)

Example Usage:

> Run the tests
> Check the git status
> Build the project with cargo

The agent will use bash to execute the appropriate commands.

Commands are executed with the same permissions as the CLI process. Be cautious when running destructive operations.

oracle

Think step-by-step and reason about complex problems.

question · string · required

Question or problem to reason about

context · string

Additional context for reasoning

Example Usage:

> Help me design the architecture for a new feature that handles real-time notifications

web_search

Search the web using Google or Serper.

query · string · required

Search query

num_results · integer · default: 5

Number of results to return

Example Usage:

> Search for best practices for Rust async programming

Web search requires API keys configured on the server.

Auto-Commit

Loom includes an intelligent auto-commit feature that automatically creates git commits when you make changes through the agent.

How It Works

1. Trigger: Activated after edit_file or bash tool calls
2. Analysis: Analyzes the git diff to understand changes
3. Message Generation: Uses Claude Haiku to generate descriptive commit messages
4. Commit: Creates a git commit with the generated message

Configuration

Disable Auto-Commit:

export LOOM_AUTO_COMMIT_DISABLE=true
loom

Default Settings:

• Model: claude-3-haiku-20240307
• Max diff size: 32KB
• Trigger tools: edit_file, bash

Example Output:

> Fix the authentication bug in src/auth.rs

[Agent makes edits]

[Auto-commit: Fix authentication bug by adding null check]

Thread State

Each REPL session maintains a conversation thread with:

Metadata

• Thread ID: Unique identifier
• Workspace root: Working directory path
• Current directory: Process working directory
• Loom version: CLI version used
• Provider: LLM provider (anthropic/openai)
• Model: Specific model identifier

Git State

• Repository URL: Remote repository slug
• Initial branch: Branch when session started
• Current branch: Current branch
• Initial commit SHA: Starting commit hash
• Current commit SHA: Latest commit hash
• Commit history: List of commits made during session
• Start dirty: Whether workspace had uncommitted changes at start
• End dirty: Current uncommitted changes status

Conversation

• Messages: Complete conversation history
• Tool calls: All tool invocations and results
• Agent state: Current agent status (waiting, processing, error)

Session Persistence

Threads are automatically saved to:

• Local: ~/.local/share/loom/threads/ (or XDG data directory)
• Remote: Synced to server (unless private session)

Resume Behavior

When you resume a thread:

1. Conversation history is restored
2. Git state is updated to current workspace
3. Agent continues from where it left off
4. Previous context is available to the agent

Keyboard Controls

Ctrl+C · keyboard

Gracefully save thread and exit

Ctrl+D (EOF) · keyboard

Save thread and exit (same as Ctrl+C)

Enter · keyboard

Submit message (empty lines are ignored)

Example Session

$ loom --workspace ~/projects/myapp

Welcome to Loom! Type your request and press Enter.
Thread ID: 01HX2K3M4N5P6Q7R8S9T0V1W2X3Y4Z5A6B7C8D9E
Type your message or press Ctrl+C to exit.

> Show me the main.rs file

[Agent reads src/main.rs using read_file tool]

Here's the content of src/main.rs:

```rust
fn main() {
    println!("Hello, world!");
}

Change the message to “Hello, Loom!”

[Agent uses edit_file tool to replace the string]

I’ve updated the message to “Hello, Loom!”.

[Auto-commit: Update greeting message to “Hello, Loom!”]

Run the program

[Agent uses bash tool to execute: cargo run]

Compiling myapp v0.1.0 Finished dev [unoptimized + debuginfo] target(s) in 0.5s Running target/debug/myapp Hello, Loom!

The program ran successfully and printed “Hello, Loom!”.

^C Thread saved. Goodbye!

## Logging

Control REPL logging with flags:

```bash
# Debug logging
loom --log-level debug

# JSON logs
loom --json-logs

# Combined
loom --log-level trace --json-logs

Log levels: trace, debug, info, warn, error

Log formats: pretty (default), compact, json

Internationalization

REPL messages are localized based on system locale:

Supported Languages:

• English (en)
• Spanish (es)
• Arabic (ar) - RTL support

Locale is detected automatically from:

1. System locale (sys-locale crate)
2. Falls back to English if unsupported

Troubleshooting

Connection Issues

# Verify server connectivity
curl https://loom.ghuntley.com/health

# Check authentication
loom --server-url https://loom.ghuntley.com login

Thread Not Syncing

For private sessions:

Thread <id> is a local-only private session and cannot be shared.
Start a normal session if you want to sync to the server.

Solution: Use loom instead of loom private for synced sessions.

Tool Execution Errors

File not found:

• Verify the file exists in your workspace
• Check path is relative to workspace root or absolute

Path outside workspace:

• Tools are restricted to workspace directory
• Use --workspace flag to set correct workspace

Command timeout:

• Increase timeout with timeout_secs parameter
• Maximum timeout is 300 seconds

Related Pages

CLI Overview

Main CLI commands and configuration

Weaver Management

Remote container sessions