plugin-guide

name	plugin-guide
description	This skill should be used when the user asks to "create a plugin", "build an awareness plugin", "publish a plugin", "install a plugin", "uninstall a plugin", "configure a plugin", "write a provider plugin", mentions "agent-awareness plugin", or needs guidance on plugin structure, packaging, the build pipeline, npm publishing, or plugin development for agent-awareness.
version	0.1.0

agent-awareness Plugin Development Guide

Plugin Architecture

agent-awareness plugins are TypeScript modules that export a default AwarenessPlugin object. Plugins provide contextual data to AI agents via gather() — one-way context injection into agent sessions.

Plugin sources (discovery order, later overrides earlier):

1. Built-in — src/plugins/ inside agent-awareness
2. Global npm — npm root -g directory, packages matching agent-awareness-plugin-*
3. Local npm — agent-awareness's own node_modules/agent-awareness-plugin-*
4. Local dir — ~/.config/agent-awareness/plugins/ (.ts or dirs with index.ts)

Creating a Plugin

Quick start (scaffold)

# npm package (for publishing)
npx agent-awareness create my-plugin
# local-only (no npm needed)
npx agent-awareness create my-secret --local

npm package structure (generated by scaffold)

agent-awareness-plugin-my-plugin/
  index.ts              # re-export: export { default } from './src/index.ts'
  src/index.ts          # plugin source
  package.json          # exports: "./index.js" (compiled)
  tsconfig.json         # dev config (noEmit, allowImportingTsExtensions)
  tsconfig.build.json   # build config (emits .js + .d.ts)
  .gitignore
  README.md

CRITICAL: Build Pipeline for npm Plugins

Node 24+ blocks TypeScript stripping inside node_modules/. All npm-distributed plugins must ship compiled .js files.

package.json requirements:

{
  "type": "module",
  "exports": { ".": "./index.js" },
  "main": "./index.js",
  "files": ["index.js", "src/**/*.js", "src/**/*.d.ts", "README.md"],
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "prepublishOnly": "npm run build"
  }
}

tsconfig.build.json requirements:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "declaration": true,
    "rewriteRelativeImportExtensions": true
  },
  "include": ["index.ts", "src/**/*.ts"],
  "exclude": ["**/*.test.ts"]
}

The key compiler option is rewriteRelativeImportExtensions — it rewrites ./src/index.ts to ./src/index.js in the emitted output.

The root index.ts must re-export from src/index.ts:

export { default } from './src/index.ts';

Local plugin structure (simpler)

A single .ts file at ~/.config/agent-awareness/plugins/my-plugin.ts. No build step needed — local plugins run raw TypeScript since they're not inside node_modules/.

Plugin API

import type { AwarenessPlugin, GatherContext, PluginConfig, Trigger } from 'agent-awareness';

export default {
  name: 'my-plugin',
  description: 'What this plugin provides',
  triggers: ['session-start', 'interval:10m'],
  defaults: {
    triggers: { 'session-start': true, 'interval:10m': true },
  },

  gather(trigger: Trigger, config: PluginConfig, prevState, context: GatherContext) {
    // context.provider — 'claude-code' | 'codex'
    // context.signal   — AbortSignal for cancellation
    // context.log      — { warn, error } structured logging
    // context.claims   — multi-agent event claiming (tryClaim, isClaimedByOther, release)
    return { text: 'compact output for agent context', state: { /* persisted */ } };
    // Return null to suppress output (nothing to report)
  },

  // Optional lifecycle hooks
  // async onInstall() {},
  // async onStart() {},
  // async onStop() {},
  // async onUninstall() {},
} satisfies AwarenessPlugin;

Trigger types

Trigger	When	Use for
session-start	New agent session	Full status dump
prompt	Each user message	Lightweight updates
change:hour	Hour changes	Time-sensitive data
change:day	Day changes	Daily summaries
interval:Nm	Every N minutes (background ticker)	Polling external services

State persistence

prevState contains the plugin's state from the last run. Return state: { ... } in results to persist. State is stored at ~/.cache/agent-awareness/state.json with atomic file locking.

Multi-agent coordination (claims)

When multiple sessions run concurrently, use context.claims to prevent duplicate actions:

const claimed = context.claims?.tryClaim('event-key');
if (claimed?.status === 'claimed_by_other') {
  return { text: 'Being handled by another session', state: prevState };
}
// Proceed with action...

Installing Plugins

# Global install (recommended for users)
npm install -g agent-awareness-plugin-<name>

# The loader auto-discovers agent-awareness-plugin-* from global and local node_modules

Configuring Plugins

Per-plugin config files at ~/.config/agent-awareness/plugins.d/<name>.json:

{
  "enabled": true,
  "triggers": { "session-start": "detailed", "interval:15m": "compact" },
  "customOption": "value"
}

Config resolution (later overrides earlier):

1. Plugin built-in defaults
2. Package defaults (config/default.json)
3. User global (~/.config/agent-awareness/plugins.d/)
4. Rig/project override ($AGENT_AWARENESS_CONFIG/plugins.d/)

Publishing Workflow

cd agent-awareness-plugin-my-plugin
npm run build          # compile .ts -> .js (prepublishOnly does this too)
npm install -g .       # test globally before publishing
npm publish            # publish to npm

After publishing, users install with: npm install -g agent-awareness-plugin-my-plugin

Diagnosing Issues

# CLI
npx agent-awareness doctor    # shows loaded/failed plugins, config, log location

# MCP tool (diagnostic, always available to agents)
awareness_doctor              # same info, available as MCP tool

Log file: ~/.cache/agent-awareness/agent-awareness.log (ticker errors, plugin failures)