agent-awareness

Your AI coding agent is blind. It doesn't know what time it is, that it's burning through quota, that a deploy just failed, or that your toddler's nap ends in 20 minutes.

agent-awareness gives agents senses. A plugin system that injects real-world context into AI coding agents, not just at startup but continuously throughout the session. A background daemon monitors your plugins on schedule and pushes updates to the agent in real time. Your agent's world view stays current without you doing anything.

[agent-awareness]
Session: 2h14min | 5h: 35% (↻3h22m) | 7d: 48%
14:32 CET Wed 26 Mar 2026 | Week 13 | Business hours
Weather Stockholm: 12°C partly cloudy | Wind: 8km/h | Sunset: 18:45

Three lines. Your agent now knows more about your world than most humans you work with.

What can agents be aware of?

Anything. That's the point. Built-in:

| Plugin | What it knows | |--------|--------------| | time-date | Time, date, weekday, week number, business hours |

Everything else ships as installable npm plugins (agent-awareness-plugin-*). Some examples:

• Quota: subscription usage, reset times, burn rate
• Weather: temperature, conditions, sunset
• System: CPU, memory, disk
• GitHub: PR status, CI results, assigned issues
• Home automation: room temperatures, door locks, appliance status
• Infrastructure: pod health, latency percentiles, deploy recency

If you can fetch() it, exec() it, or readFile() it, your agent can know about it.

For real-world examples, check out agent-awareness-plugins.

Quick start

Claude Code

/plugin marketplace add edimuj/agent-awareness
/plugin install agent-awareness@agent-awareness

That's it. Restart your session. Your agent gets context at startup and keeps receiving updates in real time as things change. For details on the daemon, activity tracking, and diagnostics: docs/claude-code.md

Codex

npm install -g agent-awareness
agent-awareness codex setup
codex-aware                  # preferred: realtime updates via Codex app-server

Full setup guide and CLI reference: docs/codex.md

Add more senses

Install plugins globally. They're auto-discovered:

npm install -g agent-awareness-plugin-quota
npm install -g agent-awareness-plugin-weather

Build your own plugin

npx agent-awareness create coffee-level          # npm package
npx agent-awareness create my-secret-sauce --local  # local only

Fill in gather(). That's the whole API:

import type { AwarenessPlugin } from 'agent-awareness';

interface CoffeeState extends Record<string, unknown> {
  cups: number;
  lastBrew: string;
}

export default {
  name: 'coffee-level',
  description: 'Tracks remaining coffee supply via smart scale',
  triggers: ['session-start', 'interval:30m'],
  defaults: {
    triggers: { 'session-start': true, 'interval:30m': true },
    scaleEndpoint: 'http://kitchen-scale.local/api/weight',
  },

  async gather(trigger, config, prevState, context) {
    const weight = await fetch(config.scaleEndpoint as string, { signal: context.signal });
    const cups = Math.floor((await weight.json()).grams / 250);

    if (cups > 2) return null; // not worth mentioning

    return {
      text: cups === 0
        ? 'Coffee: EMPTY — brewing strongly recommended'
        : `Coffee: ${cups} cup${cups > 1 ? 's' : ''} left`,
      state: { cups, lastBrew: prevState?.lastBrew ?? 'unknown' },
    };
  },
} satisfies AwarenessPlugin<CoffeeState>;

• Return null to suppress output. Only inject when there's something worth saying.
• context.signal: AbortSignal for cancellation. Pass it to fetch(), execFile(), etc.
• Auto-discovered: no registration, no config editing, no restart.

Full authoring guide: docs/plugin-creator-guide.md

Plugin sources

Plugins load from four places (later overrides earlier by name):

1. Built-in: time-date
2. Global npm: npm install -g agent-awareness-plugin-*
3. Local npm: node_modules/agent-awareness-plugin-*
4. Local: ~/.config/agent-awareness/plugins/

Configuration

Each plugin gets its own config file:

~/.config/agent-awareness/plugins.d/weather.json

{
  "latitude": 59.33,
  "longitude": 18.07,
  "city": "Stockholm"
}

Config layers deep-merge: plugin defaults > package defaults > user global > rig/project override. Set AGENT_AWARENESS_CONFIG for per-project overrides.

Execution safety

All plugin execution routes through a unified dispatcher:

• Per-plugin queue: bounded (default 3), drops oldest on overflow
• Timeout: 30s default, configurable per-plugin
• Serial per plugin: prevents state races
• Parallel across plugins: one slow plugin doesn't block others
• Errors never crash: failures resolve to null, logged to stderr

{ "timeout": 10000, "maxQueue": 5 }

Multi-agent coordination

When multiple sessions run in parallel, they all receive the same plugin notifications. That's fine for awareness, but when a plugin says "act" (fix the CI failure, merge the PR), you don't want three agents racing each other.

State locking: all reads/writes go through an atomic file lock. Automatic. Plugins don't need to do anything.

Event claiming: before rendering an "act" directive, plugins can claim the event. First session to claim it gets the "act" framing; others see a downgraded "notify" with a note that another session is handling it.

async gather(trigger, config, prevState, context) {
  if (context.claims) {
    const { claimed } = await context.claims.tryClaim('ci-failure-pr-47');
    if (!claimed) return { text: 'CI failure on PR #47 (another session is on it)', state };
  }
  return { text: 'CI failure on PR #47 — fix it', state };
}

Claims auto-expire (default 30min), release on session death, and are pruned at session start.

CLI

agent-awareness create <name>          # scaffold npm plugin
agent-awareness create <name> --local  # scaffold local plugin
agent-awareness doctor                 # diagnose loading, config, logs
agent-awareness list                   # show plugins + status
agent-awareness reload                 # hot-reload plugins in running daemon

Provider-specific commands: Claude Code · Codex

Providers

agent-awareness is provider-agnostic. Plugins receive a GatherContext with context.provider and don't need to know which agent they're running under.

| Provider | Hooks | Realtime | Docs | |----------|:-----:|:--------:|------| | Claude Code | ✓ | ✓ | docs/claude-code.md | | Codex | ✓ | ✓ via codex-aware | docs/codex.md |

Adding your own provider is ~60 lines. See docs/creating-a-provider.md.

Requirements

• Node.js 24+

License

MIT