Plugins

Plugins are how AgentOps shapes command output for tools it doesn't know about yet. When your agent runs a command, AgentOps asks each installed plugin whether it recognizes the output (match), then hands the winner the full output to compress into a compact summary (shape). The summary goes back to the agent; the raw output stays on disk.

A good plugin turns 400 lines of Prisma migration output into Migration OK — 2 applied and saves a few thousand tokens every time that command runs.

The three tiers

  • built-in — ships with AgentOps: the core classifiers for test, typescript, eslint, build, git-diff, search, logs, and generic output
  • community — written by users, distributed through the catalog, free
  • premium — advanced plugins, part of the upcoming pro tier

Every plugin declares its tier in its metadata, and the catalog can be filtered by tier.

The agentops plugins page shows built-ins first, then installed community plugins. Built-ins can be toggled with agentops plugins --disable <id> and re-enabled with agentops plugins --enable <id>. Community plugins can be removed with agentops plugins --remove <id>.

Installing from the catalog

Browse what's available:

agentops plugins --available

Install one by id:

agentops plugins --install <id>

Downloads are checksum-verified before install; a checksum mismatch aborts. Other management commands:

agentops plugins                  # list installed plugins with stats
agentops plugins --info <id>      # detailed info about one plugin
agentops plugins --remove <id>    # remove an installed plugin
agentops plugins --sync           # force sync with the server
agentops plugins --json           # machine-readable output

You can also manage plugins from your dashboard. Per-plugin stats (match count, shape count, tokens saved, average shape time) are tracked locally and shown in agentops plugins.

Expected success after install:

agentops plugins --info <id>
agentops plugins

The plugin should appear as installed, enabled, and checksum-verified. If it does not appear, run agentops plugins --sync and retry the install command.

Writing your own

Plugins live in ~/.agentops/plugins/. Each plugin is a single ESM .js file that default-exports an object with meta, match, and shape. Drop a file in the directory and it loads on the next command — no build step, no registration.

The interface

type AgentOpsPlugin = {
  meta: {
    name: string;
    version: string;
    description: string;
    author?: string;
    tier: "built-in" | "community" | "premium";
    outputKind?: string;
    priority?: number;        // higher wins ties, default 100
    targetModels?: string[];
  };
  match(
    command: string,
    outputSnippet: string,
    exitCode: number | null,
  ): { matched: boolean; confidence: number; signals?: string[] };
  shape(
    output: string,
    context: {
      command: string;
      exitCode: number | null;
      outputBytes: number;
      outputLines: number;
    },
  ): { summary: string; renderMode?: "summary" | "raw" };
};

When multiple plugins match, the one with the highest confidence wins. If shape throws, AgentOps falls back to the first 500 characters of raw output — a broken plugin degrades gracefully, it never breaks the session.

A real example

This is a condensed version of the Prisma plugin from the examples directory:

const meta = {
  name: "prisma",
  version: "1.0.0",
  description: "Prisma ORM migrate/generate output optimizer",
  author: "agentops",
  tier: "community",
  outputKind: "prisma",
  priority: 120,
};

function match(command, outputSnippet, exitCode) {
  if (/\bprisma\b/i.test(command)) {
    return { matched: true, confidence: 0.95, signals: ["prisma command"] };
  }
  return { matched: false, confidence: 0 };
}

function shape(output, context) {
  const lines = output.split("\n").filter((l) => l.trim());
  if (/migrate\s+(dev|deploy|reset)/i.test(context.command)) {
    const errors = lines.filter((l) => /error/i.test(l));
    if (errors.length > 0) {
      return { summary: `Migration FAILED\n${errors.slice(0, 5).join("\n")}` };
    }
    const applied = lines.filter((l) => /applied migration/i.test(l));
    return { summary: `Migration OK — ${applied.length} applied` };
  }
  return { summary: `Prisma: ${lines.length} lines output`, renderMode: "raw" };
}

export default { meta, match, shape };

Design rules that matter:

  • Fail toward raw. If you can't confidently summarize, return renderMode: "raw". A wrong summary costs the agent a retry; raw output only costs tokens.
  • Keep errors verbose. Success can be one line; failures should keep enough detail (first 3–5 error lines) for the agent to act without re-running.
  • Match conservatively. Use high confidence (0.9+) for command-name matches, lower (around 0.6) for output-pattern matches.

Testing locally

Put your file in ~/.agentops/plugins/, then run a matching command through the wrapper:

agentops run npx prisma migrate dev
agentops plugins    # check matchCount / tokens saved
agentops plugins --disable builtin-git-diff

Loader errors (invalid exports, syntax errors) show up in agentops plugins output next to the broken file — invalid plugins are listed but never executed.

Operational checks

Use these when debugging a plugin or helping an agent verify setup:

agentops plugins --json
agentops run <command-that-plugin-should-match>
agentops plugins --info <plugin-id>

Expected success:

  • matchCount increases when the plugin recognizes output.
  • shapeCount increases when the plugin produces a summary.
  • tokensSaved is positive after a successful summary.

Privacy: plugins run locally and receive command output because their job is to summarize it. Plugin usage stats may be submitted as counts and savings totals; raw output is not sent through leaderboard submission. The optional data pipeline is documented in Model Communication and Privacy.

← Model Communication and Privacy CLI Reference →