| license | Apache-2.0 |
| name | vibe-coding-background-agent |
| description | Build background AI agents that run alongside developers during vibe coding sessions, proactively helping without being asked. Covers file watcher architecture, event queue design, LLM router for triage, action executors, permission models (silent vs. approval-required), non-intrusive suggestion UX, and editor integration (VS Code, Cursor background agents, Claude Code hooks). Activate on 'background agent', 'vibe coding assistant', 'proactive AI helper', 'file watcher agent', 'ambient coding intelligence', 'background coding agent', 'auto-fix agent'. NOT for: chat-based AI (use prompt-engineer), long-running daemons (use daemon-development), real-time human collaboration (use cooperative-vibe-coding).
|
| allowed-tools | Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch |
| metadata | {"category":"AI & Agents","tags":["background-agent","vibe-coding","file-watcher","proactive-ai","ambient-intelligence","developer-experience","automation","event-driven","editor-integration"],"pairs-with":[{"skill":"always-on-agent-architecture","reason":"Background agents are a specialization of always-on agents with IDE-specific lifecycle"},{"skill":"daemon-development","reason":"The agent process itself is a daemon that needs graceful lifecycle management"},{"skill":"cooperative-vibe-coding","reason":"Background agents are AI participants in collaborative vibe coding sessions"},{"skill":"multi-agent-coordination","reason":"Multiple background agents need coordination to avoid conflicts and redundant work"}]} |
| category | Code Quality & Testing |
| tags | ["background-agents","vibe-coding","automation","continuous","monitoring"] |
Vibe Coding Background Agent
You build AI-powered background agents that observe developer workflow and proactively offer help without breaking flow state. You know the architectural stack: file watchers → event triage → action execution → permission gates → suggestion UX. The north star: the best background agent is one you forget is there until it saves you 10 minutes.
DECISION POINTS
Event Triage Matrix
IF event.type === 'file:saved' AND event.ext === '.ts'
→ run-typecheck (immediate, silent)
IF event.type === 'file:saved' AND isTestFile(event.path)
→ run-related-tests (immediate, silent)
IF event.type === 'build:error' AND confidence > 0.8
→ suggest-fix (immediate, requires-approval)
IF event.type === 'build:error' AND confidence <= 0.8
→ queue-for-batch-analysis (background, silent)
IF event.type === 'git:branch-switch'
→ cancel-all-running + prefetch-context (immediate, silent)
IF event.type === 'deps:changed' AND has-lockfile
→ generate-types + security-scan (background, notify)
Permission Decision Tree
Action has side effects?
├─ NO → silent execution
│ └─ Examples: run-tests, typecheck, fetch-docs, lint-check
└─ YES → Check determinism
├─ Deterministic & reversible → notify-after
│ └─ Examples: auto-format, generate-types
└─ Non-deterministic OR irreversible → requires-approval
└─ Examples: suggest-fix, auto-commit, npm-publish
Cost vs Confidence Matrix
CONFIDENCE
Low (<0.6) High (>0.8)
Cost Low | queue-batch | execute-immediate |
High | require-human | execute-with-notify |
Suggestion Timing
IF keystroke-rate > 60/min → queue-suggestions
IF idle-time > 5s AND queue-length > 0 → flush-queue
IF context-switch (file-open, branch-switch) → immediate-delivery
IF flow-state (typing-streak > 2min) → defer-non-critical
FAILURE MODES
Race Condition Cascade
- Symptoms: Multiple actions running on same file, conflicting outputs, test flake
- Detection Rule: If 2+ actions with same dedupeKey within 1s, you've hit this
- Fix: Implement proper debouncing with awaitWriteFinish: {stabilityThreshold: 200}
Permission Creep
- Symptoms: Agent asking approval for everything OR doing dangerous things silently
- Detection Rule: If approval-rate > 40% OR any git/deploy commands in silent-list, you've hit this
- Fix: Review permission policy, move destructive actions to blocked-list
LLM Cost Explosion
