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
sudoni instales o cambies paquetes del sistema. Docker con el plugin compose ya debe funcionar para tu usuario, ycurl,tar,python3, Node.js 18 o superior (los hooks del plugin se ejecutan con él) y tu propia CLI (claudeocodex) deben estar enPATH; 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 unloom: 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 enlocalhost:7777y 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
PASSen un paso que no se ejecutó. Una líneaFAILes 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.
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>.