@claxedo/agent-extensions

Reusable agent capabilities for Codex, Claude, OpenCode, and Cursor.

Agent Extensions let a host install one package and materialize the supported components into runner-native locations: skills, MCP server configs, and local runner plugins where the install path is verified.

Install

npm install @claxedo/agent-extensions

Quickstart

import { createAgentExtensions } from "@claxedo/agent-extensions"

const extensions = createAgentExtensions({
  projectDir: process.cwd(),
})

await extensions.install({
  source: "acme/review-tools",
  targets: ["codex", "claude", "opencode"],
})

console.log(await extensions.list())

For local project packages:

await extensions.installCached({
  packagePath: "agent-extensions/review-tools",
  id: "review-tools",
  targets: ["cursor"],
})

CLI

agent-extensions install acme/review-tools --targets codex,claude
agent-extensions install --path agent-extensions/review-tools --id review-tools
agent-extensions list --json
agent-extensions disable review-tools
agent-extensions enable review-tools
agent-extensions update review-tools
agent-extensions uninstall review-tools
agent-extensions doctor

--cache-dir controls durable package data: fetched package cache, machine installs, and mirrored workspace state. --runtime-dir controls generated runtime state for materialize and list output, defaulting to <project>/.agent-extensions.

materialize replays the full desired state — first-party project extensions stored under agent-extensions/ plus everything added with install:

agent-extensions materialize --targets codex,claude,opencode,cursor

--targets limits the first-party package only; installed packages keep the targets they were installed with.

Package Shape

An extension package can include one or more supported components:

review-tools/
  SKILL.md
  mcp.json
  .cursor-plugin/plugin.json

Conventional component directories are also supported by runtime replay and the first-party materialize command:

agent-extensions/
  skills/review/SKILL.md
  mcp/docs.json
  plugins/cursor/notes/plugin.json

Supported targets are:

["opencode", "claude", "codex", "cursor"]

Host Integration

The package owns deterministic extension mechanics:

• source parsing and GitHub fetch/cache
• desired install state and lock files
• install/update/enable/disable/uninstall lifecycle
• policy overlay resolution
• runtime snapshot creation
• materialization and replay
• owned-artifact cleanup and conflict detection

Product hosts own authorization and orchestration:

• user and organization identity
• workspace admin checks
• catalog allowlists
• hosted persistence
• telemetry and audit
• fanout to connected workspace runtimes

Use pure policy overrides when a host has already made authorization decisions:

const snapshot = await extensions.snapshot({
  policyOverrides: [
    { id: "review-tools", scope: "workspace", enabled: false },
  ],
})

Then apply the snapshot in a runtime host:

import { applyRuntimeAgentExtensions } from "@claxedo/agent-extensions/replay"

await applyRuntimeAgentExtensions(snapshot, process.cwd())

The snapshot is the whole world for the runtime that applies it: installs absent from the snapshot are uninstalled on replay. Disabled installs are kept in the snapshot with enabled: false (host policy is folded into that flag), so disable/enable round-trips survive replay.

Safety Model

Agent Extensions keep ownership records in .agent-extensions/materialized.json and refuse to overwrite unmanaged target paths. Uninstall and disable remove only owned artifacts.

Remote (GitHub) packages are pinned in lock.json by resolved SHA, package digest, and source tuple, and materialization fails closed: nothing reaches disk unless the package tree on disk hashes to the digest the lock pins. An install whose lock is missing, records no resolved SHA, or records no package digest is refused rather than materialized unverified, and a requested source that disagrees with the locked source is refused too — changing the pinned owner/repo/ref is a deliberate re-install (agent-extensions update <id>), not something a pushed snapshot can do implicitly. Fetches check out the locked commit id itself rather than FETCH_HEAD, so a remote that serves a different commit fails the checkout instead of becoming the content that gets cached. Verification runs inside materializeAgentExtensionSnapshot, so every caller gets it, and it runs for every install in a snapshot before any of them writes. project sources are exempt from the pinning requirement — they are a path in your own working tree, with no remote content to pin — but a digest recorded for one is still enforced.

State files and target configs are written atomically (temp file + rename). Corrupted (unparseable) state or target config files abort the operation instead of being read as empty — a truncated installed.json or a typo in a hand-edited .mcp.json never triggers deletion of other installs or a rewrite of the user's file. agent-extensions doctor reports such files as corrupt_state_file issues. When a component fails to materialize (for example an MCP-server name conflict), everything applied up to that point is still recorded as owned, so a retry after fixing the conflict succeeds.

One special case: the first-party claxedo-mcp install (exact id and kyashrathore/Claxedo@dev source) gets its connection env rewritten from the materializing process's environment and any CLAXEDO_* auth tokens stripped from target files. Third-party packages are always materialized verbatim.

Run agent-extensions doctor to inspect desired state, locks, cache roots, and materialized paths.

Learn More

• Architecture — the install → lock → materialize → replay data flow, the four runner materializers, and the state-locking mechanism
• Package source