Loom

An LLM agent framework for Go. Create agents from natural language, orchestrate them with workflow patterns, and give them domain knowledge as skills and patterns the model loads on demand.

Version: v1.4.0

Quick Start

# 1. Install
git clone https://github.com/teradata-labs/loom && cd loom
./quickstart.sh          # macOS/Linux (handles Go, Buf, patterns)
# .\quickstart.ps1       # Windows (PowerShell)

# 2. Set your LLM provider
export ANTHROPIC_API_KEY="your-key"    # or Bedrock, Ollama, OpenAI, etc.

# 3. Start the server
looms serve              # gRPC :60051, HTTP :5006

# 4. Launch the TUI
loom                     # Opens with Guide agent
loom --thread weaver     # Or go straight to the Weaver

The Weaver is a meta-agent that creates other agents from natural language:

You: Create a Teradata query optimizer that analyzes EXPLAIN plans
Weaver: Analyzing requirements... selecting patterns... activating agent.

API endpoints after looms serve:

gRPC: localhost:60051 (151 RPCs)
HTTP/REST: localhost:5006 (with SSE streaming)
Swagger UI: localhost:5006/swagger-ui
MCP Apps: localhost:5006/apps/

How It Works

Domain knowledge lives outside the system prompt, as YAML skills and patterns the model pulls into the conversation when it decides it needs them. Nothing is injected: the model decides what enters its own context.

User message → LLM call ─┬─ manage_skills(list)      → the skill catalog, each entry marked
                         │                             active for this session or not
                         ├─ manage_skills(load NAME) → skill instructions enter the conversation
                         ├─ load_pattern(REFERENCE)  → pattern content enters as a tool result
                         └─ any other tool           → result enters the conversation
                                                                     ↓
                                                                  Response

The system prompt carries only a menu of the agent's bound skills — name and description — rendered once when the session is created. A skill's body reaches the model only after a manage_skills load, and a pattern's body only after a load_pattern call.

Patterns and skills are plain-English YAML files anyone can write. They turn generic LLMs into domain specialists for SQL optimization, data quality, Teradata analytics, code review, and more.

Features

Weaver (Meta-Agent)

Describe what you need; the Weaver builds it:

Analyzes requirements to determine domain and capabilities
Selects patterns from the library (158 patterns across 16 domains)
Generates YAML configuration and activates the agent
Automatically selects workflow patterns for multi-agent tasks
/agent-plan mode for guided requirement gathering with skills-based recommendations

Multi-Agent Workflows

9 orchestration patterns defined in proto:

Pattern	Use Case
Pipeline	Sequential stages (ETL, multi-step analysis)
Parallel	Independent concurrent tasks
Fork-Join	Parallel execution with merged results
Debate	Multiple agents argue perspectives, reach consensus
Conditional	Route based on agent decisions
Swarm	Dynamic agent collaboration
Iterative	Pipeline with autonomous restart on failure
Pair Programming	Two agents collaborate on code
Teacher-Student	One agent teaches/evaluates another

Judge Evaluation System

Multi-judge evaluation with 6 aggregation strategies (weighted-average, all-must-pass, majority-pass, any-pass, min-score, max-score) and 3 execution modes (synchronous, asynchronous, hybrid). Includes DSPy integration for judge optimization.

See Judge CLI Guide.

Learning Agents

Self-improving agents that analyze successes/failures and propose pattern improvements. Three modes: observation, proposal, and auto-apply. Integrates with DSPy for prompt optimization.

See Learning Agent Guide.

Pattern Library

158 YAML patterns across 16 domains, installed to $LOOM_DATA_DIR/patterns/:

Domain	Count	Examples
`teradata/`	84	ML models, analytics, data quality, performance, FastLoad
`libraries/`	20	Domain-specific pattern bundles (sql-core, teradata-analytics, etc.)
`postgres/`	12	Query optimization, index analysis, vacuum tuning
`weaver/`	9	Workflow patterns (debate, pipeline, fork-join, swarm, etc.)
`sql/`	8	Data validation, profiling, duplicate detection
`fun/`	5	Entertainment patterns
`prompt_engineering/`	4	Chain-of-thought, few-shot, structured output
`documents/`	4	PDF extraction, Excel analysis, CSV import
Others	12	Vision, code, text, document, debugging, REST API, NASA, evaluation

Write your own patterns in plain English YAML to make Loom agents into domain experts for your specific use cases.

MCP Integration

Connect any MCP server without code:

looms config set mcp.servers.github.command /path/to/github-mcp
looms config set mcp.servers.github.env.GITHUB_TOKEN "${GITHUB_TOKEN}"
# MCP servers auto-start with: looms serve

4 built-in MCP UI Apps served at /apps/ and as MCP resources (ui:// scheme):

App	Description
Conversation Viewer	Browse agent conversations, sessions, tool calls
Data Chart	Interactive Chart.js visualizations for time-series data
EXPLAIN Plan Visualizer	SVG DAG rendering of Teradata EXPLAIN plans with cost coloring
Data Quality Dashboard	Completeness, uniqueness, distribution, and outlier analysis

Dynamic App Creation: Agents and MCP clients can create custom dashboards at runtime from a declarative JSON spec with 14 component types (stat cards, charts, tables, heatmaps, DAGs, etc.). Up to 100 dynamic apps, compiled to secure standalone HTML with the Tokyonight Dark theme. See MCP Apps Guide.

Built-in Tools

Tool	Description
`manage_skills`	Two actions: `list` the skill library annotated with what is active for the session, or `load` a skill by name so its instructions and required tools enter the session
`load_pattern`	Load one pattern's content by reference (references come from a loaded skill's pattern list)
`web_search`	Web search (Tavily, Brave, SerpAPI, or DuckDuckGo)
`file_read` / `file_write`	File system operations
`http_request` / `grpc_call`	External service calls
`shell_execute`	Sandboxed command execution
`analyze_image`	Vision analysis (work in progress)
`parse_document`	PDF, Excel, CSV extraction (work in progress)
`send_message` / `publish`	Inter-agent messaging (event-driven delivery)
`shared_memory_read` / `shared_memory_write`	Key-value store for multi-agent shared state
`workspace`	Session-scoped artifact management with FTS5 search
`graph_memory`	Persistent cross-session knowledge graph (remember/recall/supersede/consolidate/relate)
`agent_management`	Spawn, list, pause, resume agents with structured JSON API
`contact_human`	Request human-in-the-loop intervention

Graph Memory

Salience-driven graph-backed episodic memory for persistent, cross-session knowledge. Agents automatically build a knowledge graph of entities, relationships, and memories that survives across sessions.

Entities (mutable nodes) represent people, tools, projects, concepts
Edges (directed relationships) link entities: USES, WORKS_ON, KNOWS_ABOUT, etc.
Memories (immutable records) store facts, decisions, preferences, experiences, failures
Salience scoring with time decay and access boosting ranks memories by importance
Lineage tracking for corrections (SUPERSEDES) and merges (CONSOLIDATES)
FTS5 search over memory content, summaries, and tags
Token-budgeted context injection per turn (default 20% of context window)
Enabled by default (opt-out) when storage backend supports it

# Agent config
agent:
  memory:
    graph_memory:
      enabled: true              # default when store available
      context_budget_percent: 20 # % of context window
      decay_rate: 0.995          # salience decay per day

See Graph Memory Architecture.

Artifact Management

Session-scoped file storage with SQLite FTS5 full-text search, automatic metadata extraction, soft/hard delete with 30-day recovery, and archive support. See loom artifacts --help.

Skills System

LLM-agnostic YAML behaviors the model loads by name through the manage_skills tool. Each skill carries instructions, the tools it requires, and optional pattern references.

The system prompt lists the agent's bound skills as name — description only, rendered once at session creation
manage_skills has two actions, list and load. There is no unload: a loaded skill stays active, and its required tools stay registered, until the session ends
A load returns a short confirmation as the tool result and delivers the skill body as a separate user-role message
A high- or restricted-risk skill returns an approval_required error instead of loading, unless YOLO mode is enabled or no permission checker is wired
Skill files hot-reload via fsnotify

See pkg/skills/.

Per-Role LLM Providers

Assign different LLM providers per operational role (judge, orchestrator, classifier, compressor) with automatic fallback to the main agent LLM. Enables cost optimization by using smaller models for classification while reserving larger models for complex reasoning.

LLM Providers

8 providers, 73 cataloged models with mid-session switching:

Provider	Models
Anthropic	Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1
AWS Bedrock	Claude Opus 4.7 (regional + global), Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1
OpenAI	GPT-5.4 Pro, GPT-5.4, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.3 Codex, GPT-5.3 Chat, GPT-5.2, GPT-5.1, GPT-5, GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano, o3-pro, o3, o3-mini, o4-mini
Azure OpenAI	GPT-5.4, GPT-5.4 Mini, GPT-5.3 Chat, GPT-5, GPT-4.1, GPT-4.1 Mini, o3, o4-mini
Google Gemini	Gemini 3.1 Pro, Gemini 3.1 Flash-Lite, Gemini 3 Pro, Gemini 3 Flash (Preview), Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite
Mistral	Mistral Large, Mistral Large 3, Mistral Medium, Mistral Medium 3.1, Mistral Small, Magistral Medium, Magistral Small, Ministral 3 (14B/8B/3B), Codestral, Devstral Medium, Devstral Small
Ollama	Llama 4, Llama 3.3, Llama 3.2, Llama 3.2 Vision, Llama 3.1, Qwen 3.5, Qwen 3, Qwen 2.5, DeepSeek R1, DeepSeek V3, Phi 4 Mini, Phi 4, Gemma 4, Gemma 3 (+ any local model)
HuggingFace	Any model via HuggingFace Inference API (Llama, Mixtral, Gemma, Qwen, etc.)

TUI

The terminal UI (loom) is built on Bubbletea with a Crush-inspired color theme.

Guide agent greets you and helps find the right agent for your task
Slash commands — /clear, /quit, /sessions, /model, /agents, /workflows, /patterns, /help, and more
Sidebar shows Weaver status, MCP servers, the installed pattern library by category, model info, keyboard hints
Mid-session model switching with cost transparency
Multi-agent colors (6 predefined + golden-ratio generation for 50+ agents)
Streaming with animated progress, tool execution states, cost tracking

Shortcuts: ctrl+e agents | ctrl+w workflows | ctrl+p command palette | ctrl+o sessions | ctrl+n new session

Architecture

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   loom (TUI)     │  │  looms (server)  │  │  loom-mcp        │
│   Interactive     │  │  gRPC + HTTP     │  │  MCP bridge      │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         │                     │                      │
         └─────────────────────┼──────────────────────┘
                               v
┌──────────────────────────────────────────────────────────────┐
│                      Loom Framework                          │
│  ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────┐ │
│  │ Agent       │ │ Orchestration│ │ Patterns   │ │ Shuttle│ │
│  │ Runtime     │ │ (9 patterns) │ │ (158 YAML) │ │ (tools)│ │
│  └─────────────┘ └──────────────┘ └────────────┘ └────────┘ │
│  ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────┐ │
│  │ Judges      │ │ Skills       │ │ MCP Apps   │ │ Comms  │ │
│  │ (6 strats)  │ │ (hot-reload) │ │ (4 apps)   │ │ (3-way)│ │
│  └─────────────┘ └──────────────┘ └────────────┘ └────────┘ │
│  ┌─────────────┐                                             │
│  │ Graph Memory│                                             │
│  │ (salience)  │                                             │
│  └─────────────┘                                             │
└──────────────────────────────────────────────────────────────┘
         │                     │                      │
         v                     v                      v
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Observability  │  │  LLM Providers   │  │  SQLite/FTS5     │
│   (self-contained│  │  (8 providers)   │  │  or PostgreSQL   │
│    + Hawk opt.)  │  │                  │  │  (persistence)   │
└──────────────────┘  └──────────────────┘  └──────────────────┘

Proto is law: All APIs defined in proto/loom/v1/ first. 151 RPCs covering agents, workflows, patterns, sessions, artifacts, MCP, judges, skills, and scheduling. HTTP/REST via gRPC-gateway.

Installation

Quickstart (Recommended)

git clone https://github.com/teradata-labs/loom && cd loom
./quickstart.sh     # macOS/Linux
# .\quickstart.ps1  # Windows

Installs Go, Buf, builds binaries, installs 158 patterns, and configures your LLM provider interactively. See QUICKSTART.md.

Manual

git clone https://github.com/teradata-labs/loom && cd loom
just install        # Builds binaries to ~/.local/bin/, installs patterns

From Source

go install github.com/teradata-labs/loom/cmd/loom@latest
go install github.com/teradata-labs/loom/cmd/looms@latest
just install-patterns   # Patterns required for Weaver

Upgrading

When upgrading to a new version, run just upgrade (build from source) or looms upgrade to migrate the database schema:

# From source: builds new binaries, installs assets, migrates database
just upgrade

# Or run the upgrade command directly
looms upgrade              # Backup + migrate (default)
looms upgrade --dry-run    # Show pending migrations without applying
looms upgrade --backup-only # Create a backup only
looms upgrade --no-backup  # Skip backup (not recommended)
looms upgrade --yes        # Skip confirmation prompt

SQLite databases are backed up automatically before migration (via VACUUM INTO). Backup files are named with a timestamp suffix (e.g., loom.db.backup.20260224T153000). PostgreSQL backends use the same versioned migration system with advisory locks.

# Create a standalone backup at any time
just backup

Package Managers

macOS (Homebrew via teradata-labs/homebrew-tap) and Windows (Chocolatey, winget) packages are published automatically on each release. Scoop manifests are ready in packaging/ but not yet published to a bucket.

Release Verification

Releases are GPG-signed with SLSA provenance starting v1.1.0. See docs/installation/ for verification steps.

Documentation

Topic	Link
Getting Started	QUICKSTART.md
Architecture	docs/architecture/
Pattern System	docs/reference/patterns.md
Backend Implementation	docs/reference/backend.md
HTTP Server & CORS	docs/reference/http-server.md
Judge System	docs/guides/judge_cli_guide.md
Learning Agents	docs/guides/learning-agent-guide.md
Observability (Hawk)	docs/guides/integration/observability.md
Graph Memory	docs/architecture/graph-memory.md
Streaming	docs/reference/streaming.md
MCP Apps Guide	docs/guides/mcp-apps-guide.md
MCP Apps Reference	docs/reference/mcp-apps.md
Supabase Integration	docs/guides/supabase-integration.md
Database Upgrade	`looms upgrade --help`
API Reference	pkg.go.dev
Examples	examples/

Contributing

Run go test -tags fts5 -race ./... before submitting PRs
Follow existing code patterns and proto-first design
Add tests for new features
See CONTRIBUTING.md

Support

Issues: github.com/teradata-labs/loom/issues
Security: security@teradata.com (do not post security issues in GitHub Issues)

Quality

3,743 test functions across 397 test files
All tests run with -race detector; 0 race conditions
CI: proto lint, golangci-lint, race detection, fuzz tests, gosec, CodeQL, multi-platform build

License

Apache 2.0 - see LICENSE

Built by Teradata Labs

Name		Name	Last commit message	Last commit date
Latest commit History 502 Commits
.github		.github
RELEASE_NOTES		RELEASE_NOTES
cmd		cmd
deploy		deploy
docs		docs
embedded		embedded
examples		examples
gen		gen
internal		internal
packaging		packaging
patterns		patterns
pkg		pkg
prompts		prompts
proto/loom/v1		proto/loom/v1
scripts/longmemeval-eval		scripts/longmemeval-eval
skills		skills
test		test
tests		tests
web		web
workflow_examples		workflow_examples
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.golangci.yml		.golangci.yml
BUILD_TAGS.md		BUILD_TAGS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ENV_VARS.md		ENV_VARS.md
Justfile		Justfile
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
VERSION		VERSION
buf.gen.yaml		buf.gen.yaml
buf.lock		buf.lock
buf.yaml		buf.yaml
go.mod		go.mod
go.sum		go.sum
loom-release-key.asc		loom-release-key.asc
quickstart.ps1		quickstart.ps1
quickstart.sh		quickstart.sh

Navigation Menu

Uh oh!

Repository files navigation

Loom

Quick Start

How It Works

Features

Weaver (Meta-Agent)

Multi-Agent Workflows

Judge Evaluation System

Learning Agents

Pattern Library

MCP Integration

Built-in Tools

Graph Memory

Artifact Management

Skills System

Per-Role LLM Providers

LLM Providers

TUI

Architecture

Installation

Quickstart (Recommended)

Manual

From Source

Upgrading

Package Managers

Release Verification

Documentation

Contributing

Support

Quality

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Loom

Quick Start

How It Works

Features

Weaver (Meta-Agent)

Multi-Agent Workflows

Judge Evaluation System

Learning Agents

Pattern Library

MCP Integration

Built-in Tools

Graph Memory

Artifact Management

Skills System

Per-Role LLM Providers

LLM Providers

TUI

Architecture

Installation

Quickstart (Recommended)

Manual

From Source

Upgrading

Package Managers

Release Verification

Documentation

Contributing

Support

Quality

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages