{"id":48855526,"url":"https://github.com/edimuj/agent-awareness","last_synced_at":"2026-04-15T12:30:43.965Z","repository":{"id":346835285,"uuid":"1191629372","full_name":"edimuj/agent-awareness","owner":"edimuj","description":"Modular awareness plugins for AI coding agents","archived":false,"fork":false,"pushed_at":"2026-04-02T20:49:45.000Z","size":309,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T22:56:45.084Z","etag":null,"topics":["agent-awareness","claude-code","claude-plugin","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edimuj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T12:40:12.000Z","updated_at":"2026-04-02T20:49:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edimuj/agent-awareness","commit_stats":null,"previous_names":["edimuj/agent-awareness"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/edimuj/agent-awareness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edimuj%2Fagent-awareness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edimuj%2Fagent-awareness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edimuj%2Fagent-awareness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edimuj%2Fagent-awareness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edimuj","download_url":"https://codeload.github.com/edimuj/agent-awareness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edimuj%2Fagent-awareness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31841986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T11:29:19.690Z","status":"ssl_error","status_checked_at":"2026-04-15T11:29:19.171Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-awareness","claude-code","claude-plugin","mcp-server"],"created_at":"2026-04-15T12:30:43.233Z","updated_at":"2026-04-15T12:30:43.949Z","avatar_url":"https://github.com/edimuj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-awareness\n\nYour 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.\n\n**agent-awareness** gives agents senses. A plugin system that injects real-world context into AI coding agents — anything you can query with code, your agent can know about. Continuously.\n\n```\n[agent-awareness]\nSession: 2h14min | 5h: 35% (↻3h22m) | 7d: 48%\n14:32 CET Wed 26 Mar 2026 | Week 13 | Business hours\nWeather Stockholm: 12°C partly cloudy | Wind: 8km/h | Sunset: 18:45\nFocus: 18min left (deep work) | Energy: peak → stay ambitious\nCoffee: 1 cup left — brewing recommended before next session\n```\n\nSix lines. Your agent now knows more about your world than most humans you work with.\n\n## What can agents be aware of?\n\nAnything. That's the point. Here's what ships built-in:\n\n| Plugin | What it knows |\n|--------|--------------|\n| **time-date** | Time, date, weekday, week number, business hours |\n\nEverything else ships as installable npm plugins. Common ones:\n- `agent-awareness-plugin-quota`\n- `agent-awareness-plugin-system`\n- `agent-awareness-plugin-weather`\n- `agent-awareness-plugin-energy-curve`\n- `agent-awareness-plugin-focus-timer`\n\nThe plugin system is where it gets interesting:\n\n- **Home automation** — \"The living room is 24°C, toddler's room is 19°C, front door locked\"\n- **Infrastructure** — \"3 pods restarting in staging, prod latency p99 at 340ms\"\n- **GitHub** — \"PR #47 has 2 approvals, CI green. Issue #52 assigned to you 3h ago\"\n- **Calendar** — \"Next meeting in 45min with 3 attendees, prep doc unread\"\n- **Build pipeline** — \"Last deploy: 12min ago, 2 flaky tests skipped\"\n- **Team** — \"Sarah pushed to main 8min ago, 4 files overlap with your branch\"\n- **Health** — \"You've been coding for 3h straight, last break was 2h ago\"\n- **Finance** — \"AWS spend today: $4.20, on track for monthly target\"\n- **Smart home** — \"Washing machine done 20min ago, dryer available\"\n\nIf you can `fetch()` it, `exec()` it, or `readFile()` it — your agent can know about it. Write a `gather()` function, return a string, done.\n\nFor real-world examples, check out [agent-awareness-plugins](https://github.com/edimuj/agent-awareness-plugins) — it now hosts the former built-ins (`quota`, `system`, `weather`, `energy-curve`, `focus-timer`) plus community plugins like **github-watcher** and **server-health**.\n\n## Install\n\nAs a Claude Code plugin (distributed via npm — dependencies handled automatically):\n\n```bash\n# Add the marketplace (one-time)\n/plugin marketplace add edimuj/agent-awareness\n\n# Install\n/plugin install agent-awareness@agent-awareness\n```\n\nFor Codex CLI:\n```bash\nnpm install -g agent-awareness\nagent-awareness codex setup           # hooks-only setup (supported Codex path)\n```\nRun this once, then use Codex in any project.\n\nInstall additional awareness plugins globally (recommended):\n```bash\nnpm install -g agent-awareness-plugin-quota\nnpm install -g agent-awareness-plugin-system\nnpm install -g agent-awareness-plugin-weather\nnpm install -g agent-awareness-plugin-energy-curve\nnpm install -g agent-awareness-plugin-focus-timer\n```\n\nWhy not `npx` for Codex setup? The supported path writes stable on-disk hook commands into Codex config, so setup has to point at a real install. The optional Codex diagnostic MCP entry has the same path-stability requirement.\n\nCodex packaging artifacts live under `codex-plugin/`:\n- `codex-plugin/.codex-plugin/plugin.json`\n- `codex-plugin/.codex-mcp.json`\n- `codex-plugin/hooks.json`\n- `codex-plugin/hooks/`\n- `codex-plugin/README.md`\n\nCodex note: the supported integration in this repo is hooks-only. Clean-room validation showed that Codex marketplace/plugin install can cache and enable the `codex-plugin/` bundle, but it does not create hook config or activate awareness hooks. Use `agent-awareness codex setup`. Codex also does not currently have a documented equivalent to Claude Code channels, so real-time context push is not part of the Codex provider today. Optional Codex MCP support is diagnostic only. See [`codex-plugin/README.md`](./codex-plugin/README.md) for the exact contract of the packaged Codex bundle.\n\n## Build your own plugin in 5 minutes\n\n```bash\n# npm package (share with the world)\nnpx agent-awareness create weather-alerts\n\n# Local plugin (just for you)\nnpx agent-awareness create my-secret-sauce --local\n```\n\nFull authoring guide (step-by-step, caveats, troubleshooting, best practices, examples):\n[`docs/plugin-creator-guide.md`](./docs/plugin-creator-guide.md)\n\nFill in `gather()`. That's the whole API:\n\n```typescript\nimport type { AwarenessPlugin, GatherContext, PluginConfig, Trigger } from 'agent-awareness';\n\ninterface CoffeeState extends Record\u003cstring, unknown\u003e {\n  cups: number;\n  lastBrew: string;\n}\n\nexport default {\n  name: 'coffee-level',\n  description: 'Tracks remaining coffee supply via smart scale',\n  triggers: ['session-start', 'interval:30m'],\n  defaults: {\n    triggers: { 'session-start': true, 'interval:30m': true },\n    scaleEndpoint: 'http://kitchen-scale.local/api/weight',\n  },\n\n  async gather(trigger, config, prevState, context) {\n    const weight = await fetch(config.scaleEndpoint as string, { signal: context.signal });\n    const cups = Math.floor((await weight.json()).grams / 250);\n\n    if (cups \u003e 2) return null; // not worth mentioning\n\n    return {\n      text: cups === 0\n        ? 'Coffee: EMPTY — brewing strongly recommended'\n        : `Coffee: ${cups} cup${cups \u003e 1 ? 's' : ''} left`,\n      state: { cups, lastBrew: prevState?.lastBrew ?? 'unknown' },\n    };\n  },\n} satisfies AwarenessPlugin\u003cCoffeeState\u003e;\n```\n\nKey details:\n- **`context.signal`** — AbortSignal for cancellation. Use it in `fetch()`, `execFile()`, etc.\n- **`context.log`** — Structured logging (`context.log?.warn('scale offline')`)\n- **Generic state** — `AwarenessPlugin\u003cCoffeeState\u003e` gives you typed `prevState` with zero casts\n- **Return `null`** to suppress output — only inject when there's something worth saying\n- **Auto-discovered** — no registration, no config editing, no restart\n\n## Plugin sources\n\nPlugins load from four places (later overrides earlier by name):\n\n1. **Built-in** — currently `time-date` only\n2. **Global npm** — `npm install -g agent-awareness-plugin-*` (recommended for users)\n3. **Local npm** — `npm install agent-awareness-plugin-*` in the agent-awareness directory\n4. **Local** — drop a `.ts` file in `~/.config/agent-awareness/plugins/`\n\n## Publishing plugins to npm\n\nThe scaffold (`agent-awareness create`) sets up everything you need. The key requirement: **npm plugins must ship compiled `.js` files** — Node 24+ blocks TypeScript inside `node_modules/`.\n\nIf you want a complete publish workflow and troubleshooting checklist, see:\n[`docs/plugin-creator-guide.md`](./docs/plugin-creator-guide.md)\n\nThe scaffold generates a `tsconfig.build.json` with `rewriteRelativeImportExtensions` that compiles `.ts` → `.js` correctly, and a `prepublishOnly` script that builds automatically before `npm publish`.\n\n```bash\ncd agent-awareness-plugin-my-plugin\nnpm install             # install devDependencies\nnpm run build           # compile .ts → .js\nnpm install -g .        # test globally before publishing\nnpm publish             # ship it\n```\n\nLocal plugins (`--local`) don't need a build step — they run raw TypeScript since they're not inside `node_modules/`.\n\n## Configuration\n\nEach plugin gets its own config file. No monoliths:\n\n```\n~/.config/agent-awareness/plugins.d/weather.json\n```\n\n```json\n{\n  \"latitude\": 59.33,\n  \"longitude\": 18.07,\n  \"city\": \"Stockholm\"\n}\n```\n\nConfig layers deep-merge: plugin defaults → package defaults → user global → rig/project override.\n\nSet `AGENT_AWARENESS_CONFIG` for per-project or per-rig overrides.\n\n## Integration modes\n\nagent-awareness is a progressive system, but providers do not all expose the same surfaces.\n\n| Mode | Provider | What you get | Setup |\n|------|----------|--------------|-------|\n| **Hooks only** | Claude Code, Codex | Context injection at session start and on prompt. `interval:*` and `change:*` are evaluated inline on prompt. | Default baseline. |\n| **Realtime path** | Claude Code | Central daemon runs interval/change checks once, MCP bridge exposes `awareness_doctor`, and Claude channel notifications push updates between prompts. | Install Claude MCP and launch with channel support. |\n| **Diagnostics MCP** | Codex | Optional `awareness_doctor` MCP tool only. No realtime delivery, no hook activation. | `agent-awareness codex mcp install` |\n\nOn the Claude realtime path, the central daemon is the actual agent-awareness server. It owns the ticker and SSE broadcast. The Claude MCP server is just a thin provider adapter that forwards daemon results into `claude/channel` notifications and exposes diagnostics.\n\nCurrent provider support:\n- Claude Code: hooks baseline plus realtime daemon/MCP/channel path.\n- Codex: hooks only as the supported awareness path. Optional MCP exists for diagnostics, but it does not provide real-time context injection.\n\n```bash\n# Claude realtime path: launch with channel support\nclaude --dangerously-load-development-channels plugin:agent-awareness@agent-awareness\n```\n\nCodex integration:\n```bash\nagent-awareness codex setup          # install supported Codex hooks integration\nagent-awareness codex doctor         # diagnose Codex hooks + optional MCP health\n```\n\n## Lifecycle hooks\n\nSimple plugins just need `gather()`. Plugins that manage daemons, connections, or caches use lifecycle hooks:\n\n```typescript\nexport default {\n  // ...\n  async onInstall() { /* download models, create cache dirs */ },\n  async onStart()   { /* spawn daemon, connect to service */ },\n  onStop()          { /* graceful shutdown */ },\n  onUninstall()     { /* clean up everything */ },\n} satisfies AwarenessPlugin;\n```\n\n## Execution safety\n\nAll plugin execution — triggers, MCP, background ticks — routes through a unified dispatcher:\n\n- **Per-plugin queue** — bounded (default 3), drops oldest on overflow\n- **Timeout** — 30s default, configurable per-plugin\n- **Serial per plugin** — prevents state races\n- **Parallel across plugins** — one slow plugin doesn't block others\n- **Errors never crash** — failures → null, logged to stderr\n\nCommunity plugins can't hang your agent or eat unbounded memory:\n\n```json\n{ \"timeout\": 10000, \"maxQueue\": 5 }\n```\n\n## Multi-agent coordination\n\nWhen you run multiple agent sessions in parallel (e.g., different rigs via [claude-rig](https://github.com/edimuj/claude-rig)), they all receive the same plugin notifications. Getting notified is fine — but when a plugin says \"act\" (e.g., \"fix the CI failure on this PR\"), you don't want three agents racing to push competing fix commits.\n\nagent-awareness solves this at the framework level with two mechanisms:\n\n### State locking\n\nAll state reads and writes go through an atomic file lock. The ticker, prompt hooks, and MCP server can run concurrently without corrupting `state.json`.\n\nThis is automatic — plugins don't need to do anything.\n\n### Event claiming\n\nBefore rendering an \"act\"-level directive, plugins can _claim_ the event. Only the first session to claim it gets the \"act\" framing — other sessions see a downgraded \"notify\" with a note that another session is handling it.\n\n```typescript\nasync gather(trigger, config, prevState, context) {\n  const events = detectEvents(prevState);\n\n  for (const event of events) {\n    if (getAutonomy(event.type, config) === 'act' \u0026\u0026 context.claims) {\n      const { claimed } = await context.claims.tryClaim(event.key);\n      if (!claimed) {\n        // Another session is handling this — downgrade to notify\n        event.autonomy = 'notify';\n        event.note = 'being handled by another session';\n      }\n    }\n  }\n\n  return { text: formatEvents(events), state: newState };\n}\n```\n\nClaims are:\n- **Scoped per plugin** — different plugins can claim the same event key independently\n- **Auto-expiring** — default 30 minutes, configurable per claim\n- **PID-aware** — if the claiming session dies, the claim is automatically released\n- **Pruned at session start** — expired claims are cleaned up automatically\n\nThe full `context.claims` API:\n\n| Method | Description |\n|--------|-------------|\n| `tryClaim(eventKey, ttlMinutes?)` | Claim an event. Returns `{ claimed: true }` or `{ claimed: false, holder }` |\n| `isClaimedByOther(eventKey)` | Check without claiming |\n| `release(eventKey)` | Release your claim (e.g., after completing the action) |\n\n## Background daemon (Claude realtime path)\n\n`interval:10m` means every 10 minutes — not \"whenever you happen to type after 10 minutes.\"\n\nA central daemon process runs the ticker loop once per machine for the Claude Code realtime path. When the first session starts, the session-start hook auto-spawns the daemon. The daemon:\n\n- Loads all plugins once\n- Runs interval/change triggers on schedule\n- Broadcasts results to all connected sessions via SSE\n- Auto-shuts down after 15 minutes of inactivity\n\nThe Claude MCP server does not run the ticker itself. It connects to the daemon SSE stream, forwards results into Claude channel notifications, and exposes `awareness_doctor`.\n\nMultiple sessions share one daemon — no duplicated API calls, no state races.\n\n## Provider-aware\n\nPlugins know which agent they're running under via `context.provider`. The quota plugin uses this to fetch the right data for Claude vs Codex automatically. Same plugin, different agent, correct data.\n\nBuilt-in: **Claude Code**, **Codex**. Adding your own is ~60 lines.\n\n## CLI\n\n```bash\nagent-awareness create \u003cname\u003e          # scaffold npm plugin\nagent-awareness create \u003cname\u003e --local  # scaffold local plugin\nagent-awareness doctor                 # diagnose loading, config, logs\nagent-awareness list                   # show plugins + status\nagent-awareness mcp install            # add MCP server to Claude Code\nagent-awareness mcp uninstall          # remove MCP server from Claude Code\nagent-awareness mcp status             # check Claude Code MCP config\nagent-awareness codex hooks install --global   # add global Codex hooks (~/.codex/hooks.json)\nagent-awareness codex hooks install --project  # add project hooks (./.codex/hooks.json)\nagent-awareness codex hooks uninstall --global # remove global Codex hooks\nagent-awareness codex hooks uninstall --project # remove project hooks\nagent-awareness codex hooks status --global    # check global hooks config\nagent-awareness codex hooks status --project   # check project hooks config\nagent-awareness codex mcp install      # add optional diagnostic MCP server to Codex\nagent-awareness codex mcp uninstall    # remove optional Codex MCP server\nagent-awareness codex mcp status       # check optional Codex MCP config\nagent-awareness codex setup            # install supported Codex hooks integration\nagent-awareness codex doctor           # diagnose Codex hooks + optional MCP\n```\n\n## Diagnostics\n\n```bash\nagent-awareness doctor    # full health check\n```\n\n**Log file:** `~/.cache/agent-awareness/claude-code/agent-awareness.log` — captures ticker errors, plugin failures, lock contention. Auto-rotates at 256 KB. The `doctor` command shows the log location and file size.\n\n**MCP tool:** `awareness_doctor` — same diagnostics, available to agents.\n\n## Requirements\n\n- Node.js 24+ (runs TypeScript natively — no build step)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedimuj%2Fagent-awareness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedimuj%2Fagent-awareness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedimuj%2Fagent-awareness/lists"}