Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.

Configura Loom con tu agente de programación

Esta página es para un agente de programación, Claude Code o Codex, al que se le pide instalar Loom en la máquina donde se ejecuta y demostrar que la instalación funciona. Indica qué ejecutar, qué no hacer, qué debe ver cada comprobación y el informe que debe entregar. Cada paso está escrito para ejecutarse tal cual; los pasos que debe realizar una persona están marcados.

Cada versión adjunta esta página como texto plano, con su propia versión y su propio commit ya rellenados:

https://github.com/ClickHouse/loom/releases/latest/download/agent-setup.txt
https://github.com/ClickHouse/loom/releases/download/v<version>/agent-setup.txt

Versiones fijadas

Esta copia no indica ninguna versión, por lo que sus comandos no se ejecutan tal como están. Sigue el agent-setup.txt de la versión que se te pidió instalar, donde cada <version> y <commit> de abajo está completado; si no se indica ninguna versión, sigue el de la última: https://github.com/ClickHouse/loom/releases/latest/download/agent-setup.txt.

Reglas

  • No uses sudo ni instales o cambies paquetes del sistema. Docker con el plugin compose ya debe funcionar para tu usuario, y curl, tar, python3, Node.js 18 o superior (los hooks del plugin se ejecutan con él) y tu propia CLI (claude o codex) deben estar en PATH; si falta alguno, detente e infórmalo.
  • No configures ninguna clave de proveedor ni pidas una. El stack arranca y todas las comprobaciones siguientes pasan sin ella.
  • Antes del paso 1, detente e informa si hay alguna variable LOOM_* definida en tu entorno (el instalador, el plugin y los SDK la leen: un puerto, una dirección de bind, otro servidor), si existe ~/.loom, o si tu CLI ya conoce un loom: un plugin (claude plugin list, codex plugin list), un marketplace (claude plugin marketplace list, codex plugin marketplace list) o un servidor MCP (claude mcp list, codex mcp list). Decidir si se cambia alguno de ellos le corresponde a la persona. Si no hay ninguno, el stack responde solo en localhost:7777 y el plugin se conecta a él.
  • Nunca debilites una comprobación para que pase: no edites el script de comprobación, no omitas un paso, no cambies lo que espera una comprobación ni informes PASS en un paso que no se ejecutó. Una línea FAIL es un informe correcto.

1. Instalar la release

mkdir -p ~/loom-agent-setup
curl -fsSL "https://github.com/ClickHouse/loom/releases/download/v<version>/install.sh" \
  -o ~/loom-agent-setup/loom-install.sh && sh ~/loom-agent-setup/loom-install.sh \
  && rm ~/loom-agent-setup/loom-install.sh

El instalador verifica el SHA-256 del bundle, instala en ~/.loom, inicia el stack y espera a que /v1/health del servidor responda. Si el comando falla, el informe es únicamente su línea install; no continúes. La guía de inicio rápido explica con detalle qué hace el instalador.

2. Instalar el plugin

El plugin viene del código fuente de la misma versión, por lo que coincide con el servidor:

curl -fsSL "https://github.com/ClickHouse/loom/archive/refs/tags/v<version>.tar.gz" \
  | tar -xz -C ~/loom-agent-setup

Conserva ~/loom-agent-setup: es el origen del marketplace. Luego, para Claude Code:

claude plugin marketplace add ~/loom-agent-setup/loom-<version>
claude plugin install loom@loom

o para Codex:

codex plugin marketplace add ~/loom-agent-setup/loom-<version>
codex plugin add loom@loom

El stack instalado es de un solo usuario, por lo que el plugin se conecta a http://localhost:7777 sin token. La persona inicia ahora una nueva sesión del agente (Codex: una ejecución interactiva de codex, donde también aprueba los hooks del plugin), le da este texto de nuevo y le dice "continúa en el paso 3". Los pasos 3 y 4 se ejecutan en esa sesión.

3. Ejecutar la comprobación

Guarda este script como loom-setup-check.py y ejecuta python3 loom-setup-check.py. Usa solo la biblioteca estándar de Python y se comunica con Loom por HTTP. Escribe en el espacio de nombres agent-setup-check, etiqueta lo que escribe con su propia ejecución, busca solo las filas de esa ejecución y las elimina al terminar.

loom-setup-check.py
import json
import os
import pathlib
import random
import sys
import urllib.error
import urllib.parse
import urllib.request

PIN_VERSION = "<version>"
PIN_COMMIT = "<commit>"
# Loom's own tests point the check elsewhere; an agent sets neither.
BASE = os.environ.get("SETUP_CHECK_URL", "http://localhost:7777")
WHO = {"org": os.environ.get("SETUP_CHECK_ORG", "dev"), "namespace": "agent-setup-check"}
AGENT = "agent-setup"
SESSION = "setup-1"
RUN = f"{random.randrange(100_000):05d}"
TAGS = [f"setup-check:{RUN}"]
FACT = f"The setup check orchard has {RUN} pear trees."
KEY = f"setup/check/orchard-{RUN}"
DOC = f"setup-check://irrigation-{RUN}"
NOTE = f"Irrigation valve {RUN} opens at five in the morning, every second day."
LOOPBACK = ("localhost", "127.0.0.1", "::1")
checks = []


def call(op, **body):
    req = urllib.request.Request(
        f"{BASE}/v1/{op}",
        data=json.dumps({**WHO, **body}).encode(),
        headers={"Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.load(resp)
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"{op} answered {e.code}: {e.read()[:200].decode(errors='replace')}")


def check(name, probe):
    try:
        grade, detail = probe()
    except Exception as e:  # any failure is this check's FAIL line
        grade, detail = "FAIL", f"{type(e).__name__}: {e}"
    checks.append((name, grade, detail))
    return grade == "PASS"


def hit_problem(hits, field, wanted, text_field):
    """Why the first hit is not the row this run wrote, or None when it is."""
    if not hits["results"]:
        return "no hits"
    top = hits["results"][0]
    if top[field] != wanted:
        return f"the first hit is {top[field]}, not {wanted}"
    if RUN not in top[text_field]:
        return f"{wanted} came back without its text"
    return None


def bind_host():
    """LOOM_BIND_HOST from the installed stack's .env, or "" when it sets none."""
    env = pathlib.Path.home() / ".loom" / ".env"
    lines = env.read_text().splitlines() if env.exists() else []
    values = [line.split("=", 1)[1].strip() for line in lines if line.startswith("LOOM_BIND_HOST=")]
    return values[-1] if values else ""


def server():
    if PIN_VERSION.startswith("<"):
        return "FAIL", "this copy names no release: use the release's agent-setup.txt"
    if urllib.parse.urlsplit(BASE).hostname not in LOOPBACK:
        return "FAIL", f"{BASE} is not a loopback address"
    host = bind_host()
    if host not in ("", *LOOPBACK):
        return "FAIL", f"~/.loom/.env publishes Loom on {host}"
    with urllib.request.urlopen(f"{BASE}/v1/health", timeout=30) as resp:
        health = json.load(resp)
    version, commit = health.get("version"), health.get("build_commit")
    # A release candidate's server reports the final version it leads to.
    final = PIN_VERSION.split("-")[0]
    if (version, commit) != (final, PIN_COMMIT):
        return "FAIL", f"serves {version} at {commit}; the pins name {final} at {PIN_COMMIT}"
    return "PASS", f"{BASE} serves {version} at {commit[:12]}"


def memory():
    call("memory.set", agent=AGENT, memory_key=KEY, value=FACT, tags=TAGS, session_id=SESSION)
    # A new session reads with no session_id: it sees what the last one wrote.
    hits = call(
        "memory.search", query="how many pear trees does the setup check orchard have", tags=TAGS
    )
    problem = hit_problem(hits, "memory_key", KEY, "content_excerpt")
    if problem:
        return "FAIL", problem
    similarity = float(hits["results"][0]["similarity"])
    return "PASS", f"a new session finds {KEY} (similarity {similarity:.2f})"


def knowledge():
    call("knowledge.add", agent=AGENT, source_uri=DOC, title="Irrigation", content=NOTE, tags=TAGS)
    hits = call("knowledge.search", query="when does the irrigation valve open", tags=TAGS)
    problem = hit_problem(hits, "source_uri", DOC, "content")
    if problem:
        return "FAIL", problem
    similarity = float(hits["results"][0]["similarity"])
    return "PASS", f"knowledge.search finds {DOC} (similarity {similarity:.2f})"


def cleanup():
    gone = call("memory.delete", agent=AGENT, memory_key=KEY, session_id=SESSION)["found"]
    dropped = call("knowledge.delete", source_uri=DOC)["deleted"]
    if not (gone and dropped):
        return "FAIL", f"memory deleted: {gone}, document deleted: {dropped}"
    return "PASS", "deleted the memory and the document it wrote"


# Nothing is written to a server the pins or the loopback rule refuse.
if check("server", server):
    check("memory", memory)
    check("knowledge", knowledge)
    check("cleanup", cleanup)
width = max(len(name) for name, _, _ in checks)
for name, grade, detail in checks:
    print(f"  [{grade}]  {name:<{width}}  {detail}")
failed = [name for name, grade, _ in checks if grade == "FAIL"]
if failed:
    print(f"\n{len(failed)} check(s) failed: {', '.join(failed)}")
    sys.exit(1)
print(f"\nAll {len(checks)} checks passed.")

Qué debe verificar cada comprobación:

Comprobación Pasa cuando
server La URL y el LOOM_BIND_HOST de ~/.loom/.env son loopback, y /v1/health indica la versión fijada (la final de un release candidate) y el commit.
memory Un dato escrito en una sesión es el primer resultado de una búsqueda que no indica sesión, tal como lo sería para la sesión siguiente, con su propio texto y una similitud numérica.
knowledge Un documento añadido con knowledge.add es el primer resultado de knowledge.search, con su propio texto y una similitud numérica.
cleanup La memoria y el documento que escribió el script quedan eliminados.

Cuando server falla, el script no escribe nada y no ejecuta ninguna otra comprobación.

4. Comprueba la conexión del agente

Llama una vez a tu herramienta loom_search, con la consulta agent setup check, y ejecuta claude plugin list (o codex plugin list). La línea es [PASS] agent loom_search answered cuando la herramienta responde sin error y la lista muestra loom@loom habilitado; de lo contrario, la línea es [FAIL] agent <the tool's error, or the plugin's status>.

Informe

Indica las líneas del script, luego la línea agent, y después un resumen que cuente también la línea agent, con el formato de loom doctor:

  [PASS]  server     http://localhost:7777 serves 1.2.3 at 0123456789ab
  [PASS]  memory     a new session finds setup/check/orchard-04211 (similarity 0.91)
  [PASS]  knowledge  knowledge.search finds setup-check://irrigation-04211 (similarity 0.77)
  [PASS]  cleanup    deleted the memory and the document it wrote
  [PASS]  agent      loom_search answered

All 5 checks passed.

Si algo falla, el resumen dice <n> check(s) failed: <names>, y la primera línea FAIL es la que hay que corregir. Un paso que detiene la ejecución ocupa una sola línea y su resumen:

  • una regla que te detiene antes del paso 1: [FAIL] setup <what was missing or found>;
  • una instalación fallida: [FAIL] install <the command's last line>;
  • un paso 2 fallido: [FAIL] plugin <the failed command's last line>;

cada una seguida de 1 check(s) failed: <its name>.