---
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)

```bash
# 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:**
```json
{
  "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:**
```json
{
  "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`:**
```typescript
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

```typescript
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:

```typescript
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

```bash
# 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`:

```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

```bash
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

```bash
# 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)