diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index eba00f9b82..9838dcd968 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -33,7 +33,7 @@ { "name": "loom-code-skill", "source": "./", - "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. Skills only, no hooks.", + "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. No hooks; GitHub Copilot CLI also adds the loom MCP server.", "license": "Apache-2.0", "category": "code-intelligence" } diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index 69c11d531b..6628f8ea92 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -4,6 +4,8 @@ paths: - "skills/**" - ".claude-plugin/**" - ".cursor-plugin/**" + - "plugin.json" + - "mcp.json" --- # Integrations and coding-agent plugins @@ -12,8 +14,8 @@ paths: - A behaviour change to any file the Claude Code or Codex plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first. - A hook, `lib/` or `bin/` change that calls an op or a field the server does not serve yet says so in its changelog entry ("needs the next server release"), so the release notes list it: that release's pull request raises `MIN_SERVER_VERSION` in `lib/server-version.mjs` to its own version and bumps both plugin versions (clients get it only through a new version); a pull request on `main` before it never raises it (`tests/unit/test_codex_plugin.py` keeps it no newer than the server). Between such a hook's merge and that release, a server of the previous release gets no warning. - Hooks run inside a user's session: they never throw to the agent, never block past their timeout, never print a token, and degrade to silence when the server is unreachable. -- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and, for `.cursor-plugin/`, its own row; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. +- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and, for `.cursor-plugin/` and the root Agent Plugins package (`plugin.json`, `mcp.json`), their own rows; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case. - Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding. - An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting. -- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). +- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json` and the root `plugin.json`, whose plugins ship them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)). - The skills here ship to users. Their text is prompt: every line costs tokens in every session, so keep them short and exact. diff --git a/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index 4ca1c8da67..d9ef7e4287 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -43,6 +43,7 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=` | auth, write paths, erasure, migrations, the worker supervisor | the per-module branch-coverage floors CI enforces: `make test-unit-cov` (about 30 minutes on two cores, less with more) | | `integrations/`, `.claude-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin --port ` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses | | `.cursor-plugin/` | `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py tests/unit/test_release_prepare.py tests/unit/test_published_links.py`; its version follows the server's and is never bumped on its own | +| `plugin.json`, `mcp.json` (the Agent Plugins package) | `.venv/bin/python -m pytest tests/unit/test_agent_plugin.py tests/unit/test_release_prepare.py tests/unit/test_published_links.py`; its version follows the server's and is never bumped on its own | | `frontend/` | `npm --prefix frontend run test && npm --prefix frontend run build && npm --prefix frontend run budget`; the Playwright run CI adds (`npx --prefix frontend playwright install chromium` once (its system libraries, `playwright install-deps`, only on a machine you own), then `E2E_PORT= npm --prefix frontend run e2e`); `make lint` covers the accessibility rules | | `deploy/helm/` | the commands of CI's "lint and validate every overlay" step (`.github/workflows/ci.yml`, job `helm`): a `secrets.jwtSecret` of at least 32 characters (CI uses `openssl rand -hex 32`; `helm lint` passes a shorter one, the kind overlay's `helm template` refuses it), `helm lint --strict` and `helm template … \| kubeconform -strict -kubernetes-version 1.30.0` for each overlay, once more with every optional object on; then the job's `scripts/gates/helm_extractor_isolation.py`, `scripts/gates/helm_metadata_egress.py` and `scripts/gates/helm_assistant_isolation.py` | | `extractor/`, `compose.yaml` | the extractor tests (`.venv/bin/python -m pytest tests/unit/test_extractor_service.py tests/unit/test_compose_extractor_service.py`), then push and read `docker-smoke.yml`'s Quickstart jobs, which build both images and run the installed stack's extractor probes; `dev/docker-compose.dev.yml` is checked by that compose test and `make dev`, no CI job runs it | diff --git a/docs/development/release-process.md b/docs/development/release-process.md index aa3ed102ba..c00327d2be 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -1,6 +1,6 @@ # Release process -Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. The Claude Code and Codex plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). +Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin and the Agent Plugins package that ship them, and the Gemini CLI extension share one version `X.Y.Z`. The Claude Code and Codex plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). ## Where the version lives @@ -12,7 +12,7 @@ Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom- | Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | | TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | | Web app | `frontend/package.json` and `frontend/package-lock.json` | -| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | +| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | | Gemini CLI extension | `gemini-extension.json` | | Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | | Claude Code and Codex plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | @@ -420,17 +420,18 @@ The coding-agent plugins install from the repository's marketplaces (`claude plu Agents and people find Loom through these listings. Each reads files in this repository: -| Listing | Reads | How it updates | -| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | -| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | -| npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | -| Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | -| Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | -| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | -| Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | -| Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | -| Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | +| Listing | Reads | How it updates | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP Registry, and the directories that copy it | `server.json`: its metadata and a remote at `https://{loom_host}/mcp` with an optional secret `Authorization` header | the `mcp-registry` job on each dispatched final release | +| PyPI page of `clickhouse-loom` | the `[project]` metadata of `sdk/python/pyproject.toml`, and `sdk/python/README.md` as the page body | the `pypi` job on each dispatched release; the page shows the highest final version, or the highest candidate before the first final | +| npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | +| Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | +| Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | +| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | +| Awesome Copilot marketplace | the root `plugin.json` and `mcp.json` (the Agent Plugins package), at the release tag and commit the submission names | not submitted; a submission goes through the external-plugin issue form of `github/awesome-copilot`, which checks the package and installs it with Copilot CLI; a new version is a pull request to that repository's `plugins/external.json` | +| Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | +| Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | +| Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | The `mcp-registry` job runs in the `mcp-registry` environment. Give it the same protection rules as `pypi` and `npm` before the first dispatch: GitHub creates a missing environment with none. Its login needs no secret. diff --git a/docs/development/repository-guide.md b/docs/development/repository-guide.md index 4f6bf09a14..680d8d038e 100644 --- a/docs/development/repository-guide.md +++ b/docs/development/repository-guide.md @@ -4,31 +4,31 @@ What every top-level directory holds, where a concern lives inside `server/`, th ## Top-level layout -| Path | Holds | -| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | -| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | -| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | -| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | -| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | -| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | -| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | -| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | -| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | -| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | -| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | -| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | -| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | -| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | -| `i18n/` | machine translations of the README, the quickstart and the use-case pages, one folder per language in `LANGUAGES`; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | -| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | -| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | -| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | -| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | -| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Cursor marketplace and plugin, the Codex marketplace | -| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | -| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | -| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | +| Path | Holds | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | +| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | +| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | +| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | +| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | +| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | +| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | +| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | +| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | +| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | +| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | +| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | +| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | +| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | +| `i18n/` | machine translations of the README, the quickstart and the use-case pages, one folder per language in `LANGUAGES`; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | +| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | +| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | +| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | +| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | +| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `plugin.json`, `mcp.json`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Cursor marketplace and plugin, the Agent Plugins package GitHub Copilot CLI installs, the Codex marketplace | +| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | +| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | +| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | ## Inside server/ diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index 26b55d7744..aab0811a87 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -21,6 +21,7 @@ a bare ClickHouse service is a complete deployment). They fall into three groups | VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | | Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | +| GitHub Copilot CLI (experimental) | plugin: MCP tools and the `loom`, `loom-code` skills | `copilot plugin install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | | JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#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](mcp-clients.md#hosted-builders-and-chat-apps) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 351f0422e4..b066fc8ecf 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -184,7 +184,7 @@ client afterwards. | Visual Studio (Copilot agent mode) | `%USERPROFILE%\.mcp.json`, or `.mcp.json` in the solution | `{"servers": {"loom": {"type": "http", "url": "URL", "headers": {…}}}}` (Visual Studio also reads `.vscode/mcp.json`) | | | Kiro | `~/.kiro/settings/mcp.json`, or `.kiro/settings/mcp.json`; Kiro CLI reads the same `~/.kiro/settings/mcp.json` as the Kiro IDE (and copies `~/.aws/amazonq/mcp.json` there once, when Kiro CLI is installed, skipping servers that conflict with ones already there) | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` (Kiro documents that it expands a `${LOOM_API_KEY}` placeholder only for a variable listed in the **Mcp Approved Env Vars** setting); for a single-user server, an install link `https://kiro.dev/launch/mcp/add?name=loom&config=` | | | Gemini CLI | `~/.gemini/settings.json`, or `.gemini/settings.json` | `{"mcpServers": {"loom": {"httpUrl": "URL", "headers": {…}}}}`, or `gemini mcp add --transport http --header "Authorization: Bearer " loom URL` (drop `--header` for a single-user server); or the extension, below; Gemini lists a server as disabled in a folder it does not trust | connected (`gemini mcp add`, and the extension) | -| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}` | accepted | +| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `{"mcpServers": {"loom": {"type": "http", "url": "URL", "headers": {…}, "tools": ["*"]}}}`; or the plugin, below | accepted | | Neovim with mcphub.nvim (also serves avante.nvim and CodeCompanion) | `~/.config/mcphub/servers.json` | `{"mcpServers": {"loom": {"url": "URL", "headers": {…}}}}` | | | Emacs with mcp.el and gptel | `mcp-hub-servers` in your init file, then `gptel-mcp-connect` | `(setq mcp-hub-servers '(("loom" . (:url "URL"))))` (single-user server only: no header field is documented) | | | OpenCode | `opencode.json` or `.opencode/opencode.json` in the project or a folder above it, or `~/.config/opencode/opencode.json` | `opencode mcp add loom --url URL --header "Authorization=Bearer "`, which in OpenCode 2.x writes `{"mcp": {"servers": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}}`; the 1.x `opencode-ai` npm package takes `{"mcp": {"loom": {"type": "remote", "url": "URL", "headers": {…}}}}`, which 2.x still reads | connected | @@ -257,6 +257,34 @@ On a single-user server, an empty token still sends `Authorization: Bearer`, whi server accepts with a warning in its log for each request; `gemini mcp add` without `--header` (above) avoids it. +GitHub Copilot CLI (experimental) installs Loom as a plugin from the repository's root +`plugin.json`, an [Agent Plugins](https://agent-plugins.org) package: + +```bash +copilot plugin install ClickHouse/loom +``` + +Copilot CLI installs it from the default branch. The plugin adds the `loom` MCP server at +`http://localhost:7777/mcp?toolset=coding`, a single-user server on the same machine, and +the `loom` and `loom-code` skills; `copilot mcp get loom` shows the entry. + +- **Team server**: the URL is fixed and a user entry named `loom` does not replace it, so + skip the plugin and add the entry from the table. To remove an installed one, run + `copilot plugin uninstall clickhouse-loom`, or `copilot plugin uninstall loom-code-skill` + for an install named `loom-code-skill` (below). +- **Skills only**: a `loom-code-skill` install that `copilot mcp get loom` does not list + has only the skills. `copilot plugin update loom-code-skill` turns it into this plugin, + local entry included, so on a team server uninstall it instead; installing again without + updating keeps both and loads the skills twice. +- **Claude Code marketplace**: `copilot plugin marketplace add ClickHouse/loom`, then + `copilot plugin install loom-code-skill@loom`, installs the same package, MCP server + included, under the name `loom-code-skill`. + +Checked with Copilot CLI 1.0.112: the install, the update, the marketplace install, +`copilot mcp get loom`, and MCP `initialize` and `tools/list` through the entry pointed at +a local Loom on another port. A Copilot session needs a sign-in and was not run, so whether +a session offers the tools to the model is untested. + ### Hosted builders and chat apps A hosted agent or app builder (Replit Agent, Lovable, v0, Zapier, Make, Microsoft Copilot diff --git a/llms.txt b/llms.txt index 70323038bc..59574de5c7 100644 --- a/llms.txt +++ b/llms.txt @@ -175,7 +175,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Extend Loom](docs/development/extending-loom.md): Loom has one registry per kind of thing: operations, workers, settings, providers, language lanes, extraction steps and tracker sources. - [Local development](docs/development/local-development.md): This page sets up a checkout for working on Loom's code. - [Migrations](docs/development/migrations.md): This page holds the rules for writing a migration. -- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. +- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin and the Agent Plugins package that ship them, and the Gemini CLI extension share one version `X.Y.Z`. - [Repository guide](docs/development/repository-guide.md): What every top-level directory holds, where a concern lives inside `server/`, the order to read the code in, and the conventions a pull request fails without. - [Testing](docs/development/testing.md): Which suite a test belongs in, what each suite needs to run, how tests skip when their environment is missing, which gates CI enforces, and how to regenerate what they pin. diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000000..631a562f03 --- /dev/null +++ b/mcp.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "loom": { "type": "streamable-http", "url": "http://localhost:7777/mcp?toolset=coding" } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000000..47fd3099bc --- /dev/null +++ b/plugin.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "clickhouse-loom", + "version": "1.2.0", + "description": "Shared long-term memory, document search and a code index from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index. Experimental: checked with Copilot CLI 1.0.112.", + "author": { "name": "ClickHouse", "url": "https://github.com/ClickHouse" }, + "homepage": "https://clickhouse.github.io/loom/features/integrations/mcp-clients/#other-editors-and-agents", + "repository": "https://github.com/ClickHouse/loom", + "license": "Apache-2.0", + "keywords": [ + "agent-memory", + "long-term-memory", + "code-intelligence", + "code-search", + "mcp", + "clickhouse", + "self-hosted" + ] +} diff --git a/scripts/release/prepare.py b/scripts/release/prepare.py index 4d01b607af..4e23533a82 100755 --- a/scripts/release/prepare.py +++ b/scripts/release/prepare.py @@ -68,6 +68,7 @@ class Pin(NamedTuple): Pin("frontend/package-lock.json", _LOCK_ROOT), Pin(".claude-plugin/plugin.json", _TOP_JSON), Pin(".cursor-plugin/plugin.json", _TOP_JSON), + Pin("plugin.json", _TOP_JSON), Pin("gemini-extension.json", _TOP_JSON), Pin("skills/loom-code/SKILL.md", r'^ version: "(?P[^"]+)"$'), Pin("skills/loom/SKILL.md", r'^ version: "(?P[^"]+)"$'), diff --git a/tests/unit/test_agent_plugin.py b/tests/unit/test_agent_plugin.py new file mode 100644 index 0000000000..c07dd58a54 --- /dev/null +++ b/tests/unit/test_agent_plugin.py @@ -0,0 +1,53 @@ +"""The Agent Plugins package at the repository root: `plugin.json` is the manifest GitHub +Copilot CLI installs, `mcp.json` its MCP entry, and its skills are the root `skills/` +(`tests/unit/test_cursor_plugin.py` checks that directory).""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +MANIFEST = json.loads((ROOT / "plugin.json").read_text()) +MCP = json.loads((ROOT / "mcp.json").read_text()) +CURSOR = json.loads((ROOT / ".cursor-plugin" / "plugin.json").read_text()) + +# Agent Plugins 1.0.0 refuses any other top-level field; it has no skills field, and a +# client loads the skills/ directory next to plugin.json. +MANIFEST_FIELDS = { + "$schema", + "name", + "version", + "description", + "author", + "homepage", + "repository", + "license", + "keywords", + "extensions", +} + + +def test_the_manifest_holds_only_agent_plugins_fields() -> None: + assert MANIFEST["$schema"] == "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" + assert set(MANIFEST) <= MANIFEST_FIELDS + assert re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", MANIFEST["name"]) + + +def test_the_docs_uninstall_both_install_names() -> None: + # A repository install is named by plugin.json; Copilot CLI names a marketplace install + # after the .claude-plugin marketplace entry whose source is the repository root. + marketplace = json.loads((ROOT / ".claude-plugin" / "marketplace.json").read_text()) + (root_entry,) = [e for e in marketplace["plugins"] if e["source"] == "./"] + docs = " ".join((ROOT / "docs/features/integrations/mcp-clients.md").read_text().split()) + for name in (MANIFEST["name"], root_entry["name"]): + assert f"`copilot plugin uninstall {name}`" in docs + + +def test_the_entry_is_the_local_server_with_no_headers() -> None: + # Agent Plugins forbids credentials in headers; a single-user server needs none. + assert MCP["$schema"] == "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json" + entry = MCP["mcpServers"]["loom"] + default = CURSOR["variables"]["properties"]["LOOM_MCP_URL"]["default"] + assert entry == {"type": "streamable-http", "url": default} diff --git a/tests/unit/test_published_links.py b/tests/unit/test_published_links.py index 3c9dc6eb8a..264a97119a 100644 --- a/tests/unit/test_published_links.py +++ b/tests/unit/test_published_links.py @@ -45,6 +45,7 @@ def test_published_links_resolve() -> None: "server.json", ".claude-plugin/plugin.json", ".cursor-plugin/plugin.json", + "plugin.json", "integrations/claude-code-plugin/.claude-plugin/plugin.json", "integrations/codex-plugin/.codex-plugin/plugin.json", "pyproject.toml",