---
title: Integrations
---

Integrations put Loom's tools in front of a model, capture its conversations, or receive
its telemetry. Each one below is opt-in; one you leave unconfigured does nothing (Loom on
a bare ClickHouse service is a complete deployment). They fall into three groups:

- **Agent-side:** put Loom's tools in front of a model (plugins, MCP clients, framework
  adapters).
- **Capture:** feed the conversation and observation planes without the agent's help
  (plugin hooks, transcript templates).
- **Backend:** receive Loom's telemetry, or delete a user's data in another system during
  erasure (Langfuse and ClickStack).

## Map

| Integration                                                                                                                                                                                    | Kind                                                                                             | Where                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Claude Code                                                                                                                                                                                    | plugin: MCP tools, hooks, code shunt, skills                                                     | `integrations/claude-code-plugin/`: [claude-code.md](/pt-BR/features/integrations/claude-code)                                             |
| Codex                                                                                                                                                                                          | plugin: MCP tools, hooks, code shunt, skills                                                     | `integrations/codex-plugin/`: [codex.md](/pt-BR/features/integrations/codex)                                                               |
| Hermes (experimental)                                                                                                                                                                          | native memory provider: model-selected recall and fact writes; live server qualification pending | [source setup](https://github.com/ClickHouse/loom/blob/main/integrations/hermes-memory/README.md)                                                    |
| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed, Gemini CLI                                                                                                                              | MCP client config                                                                                | `loom install --client …`: [mcp-clients.md](/pt-BR/features/integrations/mcp-clients)                                                      |
| VS Code agent mode                                                                                                                                                                             | MCP tools                                                                                        | install links and `mcp.json`: [vscode.md](/pt-BR/features/integrations/vscode)                                                             |
| Any MCP client without a plugin                                                                                                                                                                | an instruction block for the client's rule file                                                  | [agent-instructions.md](/pt-BR/features/integrations/agent-instructions)                                                                   |
| Gemini CLI                                                                                                                                                                                     | extension: MCP tools and the `loom`, `loom-code` skills                                          | `gemini extensions install`: [mcp-clients.md](/pt-BR/features/integrations/mcp-clients#other-editors-and-agents)                           |
| GitHub Copilot CLI (experimental)                                                                                                                                                              | plugin: MCP tools and the `loom`, `loom-code` skills                                             | `copilot plugin install`: [mcp-clients.md](/pt-BR/features/integrations/mcp-clients#other-editors-and-agents)                              |
| JetBrains, Visual Studio, Neovim, Emacs and other agents                                                                                                                                       | MCP client config                                                                                | [other editors and agents](/pt-BR/features/integrations/mcp-clients#other-editors-and-agents)                                              |
| claude.ai, ChatGPT, Copilot Studio, Replit Agent, Lovable, v0, n8n, Dify, Zapier, Make and other hosted services                                                                               | a custom connector to a Loom the service can reach                                               | [hosted builders and chat apps](/pt-BR/features/integrations/mcp-clients#hosted-builders-and-chat-apps)                                    |
| Cline CLI (experimental)                                                                                                                                                                       | hooks: session primer, prompt recall, a file's memories on a read                                | `integrations/cline/`: [README](https://github.com/ClickHouse/loom/blob/main/integrations/cline/README.md)                                           |
| Cursor                                                                                                                                                                                         | MCP tools, skills (untested plugin) + `sessionEnd` capture hook                                  | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](/pt-BR/features/integrations/cursor)                                                |
| Any Agent-Skills client                                                                                                                                                                        | the `loom` and `loom-code` skills, no hooks                                                      | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents)                                                     |
| Aider, Continue (no longer actively maintained), OpenCode, JetBrains AI                                                                                                                        | transcript capture template                                                                      | `integrations/generic/`: [below](#transcript-capture-hooks)                                                      |
| Agents that only use shell grep                                                                                                                                                                | the grep shim                                                                                    | `integrations/grep-shim/`: [grep-shim.md](/pt-BR/features/integrations/grep-shim)                                                          |
| LibreChat v0.8.8                                                                                                                                                                               | chat client on the assistant toolset, per-user token                                             | `integrations/librechat/`: [librechat.md](/pt-BR/features/integrations/librechat)                                                          |
| LangChain, LlamaIndex, OpenAI Agents SDK, CrewAI, AutoGen, AG2, Microsoft Agent Framework, Google ADK, Claude API memory tool, Pydantic AI, Mastra, AI SDK, LangGraph, Strands Agents, Pipecat | SDK retrievers, memory adapters and tools                                                        | `loom.integrations.*` in Python, `@clickhouse/loom/integrations/*` in TypeScript: [frameworks.md](/pt-BR/features/integrations/frameworks) |
| Agent orchestrators                                                                                                                                                                            | shared MCP mount                                                                                 | [frameworks.md](/pt-BR/features/integrations/frameworks)                                                                                   |
| Agent Substrate                                                                                                                                                                                | MCP through the egress gateway, per-agent token                                                  | [agent-substrate.md](/pt-BR/features/integrations/agent-substrate)                                                                         |
| AX (sandboxed agent tasks)                                                                                                                                                                     | Workspace manifest: MCP config, `AGENTS.md`, run budget                                          | `integrations/ax/`: [README](https://github.com/ClickHouse/loom/blob/main/integrations/ax/README.md)                                                 |
| Langfuse                                                                                                                                                                                       | traces, retrieval scores, erasure; needs Langfuse                                                | [langfuse.md](/pt-BR/features/integrations/langfuse)                                                                                       |
| ClickStack / HyperDX                                                                                                                                                                           | OpenTelemetry spans, logs, metrics; erasure                                                      | [clickstack.md](/pt-BR/features/integrations/clickstack)                                                                                   |
| Git repositories (OKF bundles)                                                                                                                                                                 | export, import, CI lint gate                                                                     | `integrations/okf-ci/`: [okf.md](/pt-BR/features/integrations/okf)                                                                         |
| Shell pipelines                                                                                                                                                                                | `loom memory-search --json-agent`                                                                | [below](#command-line-search-for-pipelines)                                                                      |
| Provider prompt caches                                                                                                                                                                         | byte-stable `context.pack` prefix                                                                | [below](#prompt-caching)                                                                                         |
| GitHub                                                                                                                                                                                         | code index, PR history; needs the code workers enabled                                           | [code index overview](/pt-BR/features/code-index/overview)                                                                 |

## Coding agents

- Plugins (MCP tools, session hooks, code shunt): [connect a coding agent](/pt-BR/getting-started/connect-a-coding-agent),
  then [claude-code.md](/pt-BR/features/integrations/claude-code) or [codex.md](/pt-BR/features/integrations/codex).
- Any other MCP client (`loom install --client …`): [mcp-clients.md](/pt-BR/features/integrations/mcp-clients), plus the
  [agent instructions](/pt-BR/features/integrations/agent-instructions) block in the client's rule file.
- The Cline CLI's hooks (experimental): the session primer, prompt recall and a file's memories on a read,
  through the Claude Code plugin's scripts: [`integrations/cline/`](https://github.com/ClickHouse/loom/blob/main/integrations/cline/README.md).
- The `loom` and `loom-code` skills alone, no hooks: `npx skills add ClickHouse/loom --skill loom loom-code`,
  or `claude plugin install loom-code-skill@loom`. Install either the `loom` plugin or
  `loom-code-skill`, not both; the plugin already ships `loom-code`, and its other skills cover what `loom` says.

## Transcript capture hooks

These are templates you wire into a client yourself. Turns are stored only when
conversation logging is on.

Two shell templates pass a finished transcript to `loom ingest-transcript`, which posts
each turn to `conversation.append`:

| Client                                                                  | Template                                     | Wiring                                                                                               | `LOOM_AGENT` default |
| ----------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------- |
| Cursor                                                                  | `integrations/cursor/cursor-session-hook.sh` | `sessionEnd` hook in `~/.cursor/hooks.json`, reads hook input on stdin ([cursor.md](/pt-BR/features/integrations/cursor))      | `cursor`             |
| Aider, Continue (no longer actively maintained), OpenCode, JetBrains AI | `integrations/generic/ingest.sh`             | run after the session on the exported transcript ([README](https://github.com/ClickHouse/loom/blob/main/integrations/generic/README.md)) | `generic`            |

Both need `LOOM_NAMESPACE` and a token (`LOOM_API_KEY`, else `~/.loom/token`).
`LOOM_BASE_URL` defaults to `http://localhost:7777`; `LOOM_BIN` to `loom` on `PATH`.
Limits, exit codes and the dry run are in
[`integrations/generic/README.md`](https://github.com/ClickHouse/loom/blob/main/integrations/generic/README.md).

A transcript is a `.json` array of `{role, content}` objects or a `.md` file with
alternating `# user` / `# assistant` sections. By hand:

```bash
loom ingest-transcript --server-url https://loom.example.com --namespace <ns> --file session.md
```

- The thread is named after the file's resolved path (or `--thread-id`).
- Each turn's `msg_id` hashes its role, content and count of identical earlier turns, so
  re-ingesting a grown file appends only new turns.
- `--dry-run` prints the turn count and sizes, never the text.
- **Logging must be on** (`conversation.set_logging`, off for a new namespace).
  `conversation.append` succeeds even when it drops the turn.
- **Stored turns are not mined.** To write memories from a transcript, post its turns to
  `memory.set_from_messages`.

The plugins capture sessions with their own hooks and do not need these templates
([Claude Code hooks](/pt-BR/features/integrations/claude-code#what-the-hooks-do)). See
[conversations and sessions](/pt-BR/features/conversations-and-sessions).

## Joining a request across systems

Every HTTP response carries an `X-Request-Id`: yours, if you sent one of 1 to 64 letters,
digits, `.`, `_` or `-`; else a generated UUID.
The same id is written to:

| System              | Where                                                     |
| ------------------- | --------------------------------------------------------- |
| Loom's event ledger | `loom.agent_events.request_id`                            |
| Langfuse            | trace metadata `request_id`                               |
| OpenTelemetry       | span attribute `loom.request_id` in `default.otel_traces` |

Send your own `X-Request-Id` to join Loom's records to your application's logs.

## Command-line search for pipelines

`loom memory-search` runs `memory.search` over HTTP:

```bash
loom memory-search --namespace <ns> --query "retry policy for the ingest queue" --json-agent
```

`--json-agent` prints one JSON envelope (`command`, `query`, `namespace`, `results`; each
result has `memory_key`, `content`, `similarity`, `source`, `temporal_anchor`,
`namespace`). Without it the output is a readable list.

| Flag            | Default                                                                   |
| --------------- | ------------------------------------------------------------------------- |
| `--search-mode` | `bm25_hybrid`                                                             |
| `--top-k`       | `10`                                                                      |
| `--token`       | `LOOM_API_KEY`, then `~/.loom/config.json`, then `~/.loom/token`          |
| `--org`         | the token's `org` claim, else `dev`                                       |
| `--server-url`  | `LOOM_BASE_URL`, then `~/.loom/config.json`, else `http://localhost:7777` |

All flags: [CLI reference](/pt-BR/reference/cli).

## Prompt caching

Tool results serialise in a fixed field order, so the same content returns the same
bytes. `context.pack` puts query-independent sections first and returns
`stable_sections`, `stable_prefix_chars` and `stable_hash`. The first
`stable_prefix_chars` characters of `rendered` stay byte-identical until working memory,
the profile or the pins change: put the cache breakpoint there, and compare `stable_hash`
to see whether the prefix moved. The Python SDK exposes `pack.stable_prefix` and
`pack.volatile_suffix`.

Loom's own model calls report `gen_ai.usage.cache_read.input_tokens` and
`loom.llm.prompt_cache_hit_ratio` on their spans.

## Related

- [Agent integration guide](/pt-BR/guides/agent-integration): plugin, MCP or SDK.
- [MCP reference](/pt-BR/reference/mcp): endpoint, toolsets, results, errors.
- [Tokens and grants](/pt-BR/guides/tokens-and-grants): the token each integration needs.
- [Operations reference](/pt-BR/reference/operations#conversation): `conversation.*`.
