GoodVibes Plugin

Plug in. Receive good vibes.

A Claude Code plugin that replaces native tools with token-efficient precision equivalents, adds 73 MCP tools across 6 engines, and orchestrates 11 specialized agents with persistent cross-session memory.

Installation

Prerequisites: Node.js (v18+) and tmux must be installed.

Supported platforms: Linux (x64, ARM64), macOS (x64, Apple Silicon), Windows (x64, ARM64, ia32). Native AST binaries are included for all platforms.

claude plugin marketplace add mgd34msu/goodvibes-plugin
claude plugin install goodvibes@goodvibes-market

After installation, run the Setup hook to pre-write CLAUDE.md chain files:

claude --init-only

This ensures all GoodVibes instruction files are in place before your first session. On each session start, the SessionStart hook:

• Detects your project stack (frameworks, languages, tools)
• Analyzes git status (branch, uncommitted changes)
• Checks project health (missing dependencies, build issues)
• Verifies CLAUDE.md chain files (writes/appends any that are missing)
• Injects project context into Claude's system message

Set your output style:

/output-style goodvibes:vibecoding   # Interactive mode
/output-style goodvibes:justvibes    # Autonomous mode

At a Glance

Why GoodVibes?

Token Efficiency

Token consumption in AI coding sessions follows a layered pattern: individual operations add tokens, round trips resend conversation context, sessions accumulate state, and knowledge either persists or gets rediscovered. GoodVibes optimizes all seven layers.

Layer 1: Per-Operation Savings

Native tools return maximum output regardless of need. Precision tools let you request exactly the detail level required.

Note: Token estimates below are for typical small-to-medium files (~50-100 lines). Savings scale linearly with file size (e.g., a 500-line file would be ~5,000 tokens native vs. the same low precision overhead).

Mechanisms:

• Verbosity levels (4-6 per tool): count_only, files_only, minimal, standard, verbose. Tools default to minimal output automatically — precision_edit defaults to minimal, precision_grep to files_only, precision_glob to paths_only. Savings are automatic even without explicit requests.
• Extract modes (precision_read): content, outline, symbols, ast, lines. Get function signatures (~50 tokens) instead of full file content (~500+ tokens). 75-95% savings.
• Token budget pagination: Large results auto-paginate to stay within a specified token limit. Prevents single responses from consuming disproportionate context.
• AST pattern matching (precision_edit): More precise than regex, fewer false positives, fewer failed edits requiring retry.

Layer 2: Per-Round-Trip Savings

Every API call resends the entire conversation (system prompt + tool definitions + all messages). Fewer calls = less overhead.

• Batch operations: Read 10 files, edit 5 files, run 3 commands, fetch 5 URLs — each in a single tool call. Eliminates N-1 round trips.
• discover tool: Runs grep + glob + symbol queries simultaneously in one call. Results keyed by query ID. 5 searches in 1 round trip instead of 5.
• Atomic transactions: precision_edit and precision_write in atomic mode. If any operation fails, all roll back. Prevents partial failures that require re-investigation (which costs more round trips).

Quick example:

Reading 10 files:
  Native: 10 calls x (full conversation prefix resent each time)
  Precision: 1 call x (conversation prefix sent once)
  = 9 fewer prefix resends

Layer 3: Per-Session Savings

State tracked within a session avoids redundant work.

• File state caching: SHA256 hash-based. Re-reading an unchanged file returns ~20 tokens instead of full content. In edit-verify-edit cycles, this compounds rapidly.
• Search cache: Last 20 grep results stored by query ID. Enables incremental refinement without re-running expensive searches.
• Stack detection caching: detect_stack results cached to .goodvibes/detected-stack.json. Re-detection skipped within session.
• Context injection at session start: SessionStart hook gathers context types in parallel (stack, git, environment, TODOs, health, folder structure, memory, ports) and injects them upfront. Agents skip discovery.
• Conditional context sections: Context builder omits healthy sections entirely. If no health warnings exist, no health section is injected. Saves 200-500 tokens on healthy projects.
• Subagent context pre-loading: SubagentStart hook injects project name, git branch, and stack info into every subagent at spawn. No per-agent discovery needed.

Layer 4: Cross-Session Savings

Knowledge persists across conversations. Same problem next week? Already documented.

• Memory system: .goodvibes/memory/ stores decisions, patterns, failures, and preferences in structured JSON. Agents read memory before acting. An agent that would spend 5K+ tokens debugging a known issue instead reads a 200-token failure record.
• PostToolUseFailure logging: Failed tool attempts are logged with root cause and prevention guidance. Future sessions inherit this knowledge automatically.
• Learn-and-abandon pattern: Fix attempts are capped. If the issue is upstream (in a package you can't change), you don't burn tokens trying to fix it again — every future session reads the failure record and skips the investigation entirely.

Layer 5: Infrastructure Savings (Dual-Layer Caching)

Precision engine's local file cache and Anthropic's remote prompt cache operate at different layers and compound:

Without local caching, re-reading a file adds full content to the conversation every time. With local caching, only the first read adds full content; subsequent reads return cache hits (~20 tokens each). This keeps the conversation prefix smaller.

Since Anthropic's prompt cache pricing uses multipliers (cache reads at ~10% of base input price), a smaller prefix means cheaper cache operations on every turn.

Re-reading a 500-line file 3 times during a session:
  Native tools:  5,000 + 5,000 + 5,000 = 15,000 tokens added to conversation
  Precision:     5,000 + 20 + 20       = 5,040 tokens added

Over 20 files read multiple times:
  Native:    ~100K+ tokens x cache rates = expensive prefix
  Precision: ~20K tokens x cache rates   = 80% reduction in cache cost

Context window longevity: Slower conversation growth delays context compaction. Compaction rewrites the conversation prefix, which means the remote cache no longer matches, requiring a new cache write. Precision caching keeps the remote cache hot longer, avoiding repeated cold starts.

Layer 6: Prevention Savings

Structured error handling prevents expensive failure cascades.

• 3-phase fix loop: Systematic escalation (internal -> docs -> community -> internet) with capped attempts instead of random debugging that burns tokens.
• Blocker classification: Output style classifies blockers by type (issue/error/other) with specific recovery strategies. Structured response = targeted fix = fewer wasted tokens.
• Atomic transactions with rollback: Failed batch operations roll back cleanly. No partial corruption requiring manual investigation.

Layer 7: Orchestration Savings

The output style enforces patterns that keep the entire agent tree efficient.

• Orchestrator stays lean: "You ARE the orchestrator. Coordination, NOT implementation." The main context — the most expensive one because it persists across the whole session — never bloats with file contents or grep results. All implementation happens in subagent contexts that are discarded after completion.
• Mandatory precision tools for all agents: The output style and PreToolUse hook force precision tools across the entire agent tree. One rogue subagent using native Read in a loop would burn thousands of tokens. This prevents it.
• Planned execution: "Gather->Plan->Apply Workflow" means agents execute targeted operations instead of speculative exploration. Pre-meditated work = fewer wasted reads and searches.
• Parallel agents with background execution: Agents run concurrently in the background (Default = 6 concurrent, can be increased). Parallel execution plus explicit instructions not to monitor agents via Task Output unless absolutely necessary (and even then to use the non-blocking version), and to wait for a Task Completion notification means fewer wasted tokens and the ability to keep conversing and planning in the main conversation context while work is done in the background.

Summary

These seven layers compound: per-operation savings reduce round-trip overhead, which shrinks per-session context growth, which delays compaction, which keeps the remote cache hot, while cross-session memory prevents rediscovering solved problems, and orchestration patterns ensure the entire agent tree operates efficiently. For API users paying per token, this directly reduces cost. For Pro/Max subscribers, it means less of your weekly allocation consumed per session, allowing more work before hitting limits.

Transparent Tool Upgrade

A PreToolUse hook intercepts Claude's native Read, Edit, Write, Glob, and Grep calls and redirects them to precision equivalents. The hook fires on every tool call — Claude requests Read, the hook blocks it and tells Claude to use precision_read instead. This happens for all agents including subagents. Once this behavior has been recorded in memory, native tool use is rarely attempted.

This means the efficiency gains are automatic — Claude uses precision tools without configuration.

11 Specialized Agents

Domain-specific agents (engineer, reviewer, tester, architect, deployer, 3 integrators, planner, 2 factories) each bring focused expertise. Opus-powered agents handle complex work; Sonnet-powered agents handle high-volume tasks.

Persistent Memory

A two-tier memory system stores decisions, patterns, failures, and preferences in .goodvibes/memory/. Agents read these files before acting. The PostToolUseFailure hook automatically logs failures after exhausting its 3-phase fix loop. Same bug next session? Already documented.

Quality Loops

WRFC (Work-Review-Fix-Check) is a mandatory quality cycle enforced on every unit of work. The runtime engine drives these loops autonomously — the orchestrator spawns work, and the engine handles review, fix, and completion via directives.

The cycle:

1. WORK    →  Orchestrator spawns agent to implement the task
2. REVIEW  →  Runtime engine auto-spawns reviewer (directive-driven)
3. FIX     →  If issues found, engine spawns fixer (directive-driven)
4. CHECK   →  Engine re-reviews until zero issues remain
5. COMPLETE →  Engine issues complete directive → git commit + log update

How it works:

• Directive-driven: The runtime engine's WRFC plugin evaluates review scores, decides whether to fix or complete, and issues <gv> directives that the orchestrator executes mechanically. The orchestrator does not decide when to review or fix — the engine does.
• Per-task isolation: Each unit of work gets its own WRFC workflow with independent state tracking.
• All agents run in background: The orchestrator coordinates; it never implements. Up to 6 concurrent WRFC chains. (Default = 6, can be configured)
• No issue is too minor: Reviewers flag everything — major, minor, nitpick. All must be addressed before the chain completes. (Minimum review score can be configured)
• Iterative convergence: Fix → Check repeats until the reviewer returns zero issues or max attempts are reached. Default for max attempts is 3 loops where a single loop contains 4 separate attempts to fix a problem by gathering additional information and retrying. In an interactive Vibecoding session, the user can direct the flow after max retries; In an automated Justvibes session, failures are documented for later examination.
• Failure logging: If max fix attempts are exhausted, the failure is recorded in .goodvibes/memory/failures.json with root cause and prevention guidance.
• Score-gated completion: Code is only committed after the reviewer confirms a passing score. The threshold is configurable per workflow.

Two Execution Modes

vibecoding (interactive: shows progress, explains decisions, asks on ambiguity) and justvibes (autonomous: silent execution, auto-chains tasks, logs everything).

Installation

claude plugin marketplace add mgd34msu/goodvibes-plugin
claude plugin install goodvibes@goodvibes-market

After installation, run the Setup hook to pre-write CLAUDE.md chain files:

claude --init-only

This ensures all GoodVibes instruction files are in place before your first session. On each session start, the SessionStart hook:

• Detects your project stack (frameworks, languages, tools)
• Analyzes git status (branch, uncommitted changes)
• Checks project health (missing dependencies, build issues)
• Verifies CLAUDE.md chain files (writes/appends any that are missing)
• Injects project context into Claude's system message

Set your output style:

/output-style goodvibes:vibecoding   # Interactive mode
/output-style goodvibes:justvibes    # Autonomous mode

Precision Engine — 12 Tools

The core of GoodVibes. Replaces Claude Code's native tools with token-efficient alternatives that support batching, extract modes, caching, and atomic transactions.

Key capabilities:

• Batch operations: read 10 files, edit 5 files, run 3 commands, fetch 5 URLs — each in a single tool call
• Atomic transactions: if any operation in a batch fails, all changes roll back (rollback ID provided for manual undo)
• AST-Grep matching: structural code patterns with captures across 18 languages
• Multi-format reading: images (returned as visual blocks), PDFs (per-page), Jupyter notebooks (structured cell output)

Project Engine — 26 Tools

Project-wide intelligence layer. Consolidates code analysis, API tooling, database tools, security scanning, runtime profiling, and scaffolding in a single MCP server with a consistent project_* naming convention.

Key capabilities:

• TypeScript Language Service: compiler-grade analysis for dead code, safe deletion, and virtual edit validation
• Multi-ORM database support: Prisma, Drizzle, raw SQL schema parsing; PostgreSQL, MySQL, SQLite query execution
• LLM-powered analysis: breaking change detection and semantic diff with configurable model (haiku/sonnet/opus)
• Security scanning: 40+ secret patterns, 330+ permission patterns, env var auditing

Frontend Engine — 14 Tools

Static analysis tools for React/TypeScript frontends. All analysis is AST-based — no runtime, no DOM, no browser required.

Key capabilities:

• AST-based analysis: all tools use the TypeScript compiler API — no runtime required
• Tailwind-aware: resolves breakpoints from tailwind.config.js, classifies utilities by CSS property group
• Next.js App Router support: client/server boundary analysis, route segment error boundary coverage
• WCAG 2.1 AA: checks roles, focus order, keyboard interactions, and ARIA composite patterns

Analytics Engine — 7 Tools

Session intelligence daemon. Tracks token usage, API costs, tool call metrics, agent lifecycle, file hotspots, and anomalies. Renders into tmux panes via a mini (4-line) or full (4-page interactive) TUI dashboard.

Key capabilities:

• Cost tracking: per-model pricing map computed from Claude JSONL session files
• Anomaly detection: 6 rule types including cache degradation, error spikes, and token burn
• Cross-session history: global SQLite DB (~/.claude/.goodvibes/analytics/analytics.db) with tag filtering
• TUI dashboards: spawns standalone tmux pane processes (mini: 4-line statusline; full: 4-page interactive Ink/React app)

Runtime Engine — 7 Tools

Event-driven orchestration backbone. Manages WRFC quality loops, event-driven triggers, workflow state machines, and agent coordination. Runs as a persistent process with Unix domain socket IPC.

Architecture

Three-layer design separating generic event processing from domain-specific behavior:

Layer 1 — Core (generic event loop):

• EventQueue: Binary min-heap with O(log n) enqueue, priority ordering, dedup TTL, cancel by ID/ref
• EventProcessor: Tick-driven processing loop with backpressure detection and budget limits
• TriggerRegistry: Pattern-based event matching with glob support and LRU cache
• StateStore: Debounced JSON persistence with structuredClone snapshots
• LoopLifecycleManager: State machine (stopped → running → paused → draining → stopped)
• ErrorHandler: Retry engine (fixed/exponential backoff) with dead-letter queue routing
• EventMetrics: Rolling window statistics (latency, chain depth, per-trigger/per-type counts)
• DeadLetterQueue: Failed event storage with max-size eviction and optional disk persistence

Layer 2 — Extensions (typed event/trigger factories):

• 5 event factories: agent, hook, time, external, human — each producing typed RuntimeEvent payloads
• 4 trigger factories: WRFC, cron, webhook, and generic — with condition builders and type guards

Layer 3 — Plugins (domain implementations):

• WRFC Plugin: Score evaluation, directive building, quality gate handlers, review/fix orchestration
• Time Plugin: Heartbeat monitoring, cron-style scheduling with dirty-flag persistence
• External Plugin: File watcher (polling with dedup), HTTP webhook listener (SHA-256 auth), pluggable normalizers
• Hook Processing Plugin: Maps Claude Code hook events to runtime events via priority-sorted registry

Executor Modes

The runtime engine supports three execution modes that determine how events are processed:

Mode selection: Explicit via config/command, inferred from session origin (tmux cron tick → daemon, human → engaged), or hybrid by default in engaged sessions with queued events.

Key Capabilities

• Directive-driven WRFC: Autonomous Work → Review → Fix → Check loops managed by the engine, not the orchestrator
• Event-driven triggers: Declarative conditions that fire handlers when matching events arrive
• Workflow state machines: Formal state tracking for WRFC chains and fix loops with cancellation support
• Five event sources: Time (heartbeats, crons), human (prompts, approvals), external (webhooks), internal (hooks), and agent (inter-agent) — all entering a single priority queue
• Circuit breakers: Chain depth limits, max fires per trigger, cooldowns, global queue depth limits, and cost budgets
• Unix socket IPC: Low-latency communication between hooks, MCP tools, and the runtime process
• Plugin architecture: Layer 3 plugins register event types, triggers, and handlers at startup — extensible without modifying core

Registry Engine — 7 Tools

Discovery and search layer for skills, agents, and tools. Uses Fuse.js fuzzy search indexed over YAML registry files. Supports deferred loading — tools are registered only when activated via ToolSearch.

Key capabilities:

• Fuzzy search: Fuse.js with weighted fields (description 0.4, name 0.3, keywords 0.3) and relevance scoring
• Lazy loading: server starts instantly; registry indexes are loaded on first use (single-flight pattern)
• Deferred tools: all 7 tools use defer_loading: true — loaded on-demand via ToolSearch to minimize startup cost
• Three registries: skills (25), agents (11), tools (73) — each indexed independently with Fuse.js

Agents

11 specialized agents with distinct expertise. The orchestrator spawns them for focused tasks — each consults memory, applies relevant skills, and returns results.

Skills - 25 Total

Organized into 4 tiers with progressive loading — protocol skills are always active, others load when relevant to the task.

Protocol skills are embedded in every agent's context via the subagent protocol chain — they're too critical for token efficiency and execution patterns to depend on lazy loading.

Outcome and quality skills load proactively when Claude detects a matching task. Each skill includes a ## Resources tree pointing to scripts and reference materials the agent can navigate as needed.

Fallback: If a skill doesn't load automatically, the registry engine's get_skill_content tool serves as an escape hatch.

Hooks - 11 Types

Lifecycle hooks run transparently on every session. They're the mechanism behind tool redirection, context injection, and automatic error recovery.

Output Styles

Two execution modes for different workflows. Set via /output-style goodvibes:vibecoding or /output-style goodvibes:justvibes.

Memory System

Two-tier persistent memory. Session logs track the current session. Cross-session memory persists across conversations.

Session Logs (.goodvibes/logs/)

• decisions.md — Architectural choices with options considered, rationale, implications
• errors.md — Failures categorized by type (TOOL_FAILURE, BUILD_ERROR, TEST_FAILURE, etc.) with root cause and resolution
• activity.md — Completed work that passed review (primarily used in justvibes mode)

Cross-Session Memory (.goodvibes/memory/)

• decisions.json — Decision records with category, scope, confidence (max 1000 entries, auto-prunes oldest)
• patterns.json — Proven approaches with example files and keywords (max 500)
• failures.json — Failed approaches with root cause and prevention guidance (max 500)
• preferences.json — User conventions (code style, naming, patterns)

Agents read memory before acting. The PostToolUseFailure hook automatically records failures after its 3-phase fix loop is exhausted.

Telemetry

Built-in telemetry tracks tool usage, session activity, and performance metrics in a local SQLite database (sql.js WASM). Query via precision_config action=telemetry with filters for tool, status, session_id, and date range. All data stays local — nothing is sent externally.

Configuration

GoodVibes works out of the box. Minimal configuration needed.

Path Sandboxing

Controls whether precision tools can access files outside the project root. Disabled by default.

/goodvibes:sandbox true    # Enable (restrict to project root)
/goodvibes:sandbox false   # Disable (allow external paths, default)

Service Registry

Named API services with stored credentials for precision_fetch auto-auth:

/goodvibes:services add Github    # Configure a new API service
/goodvibes:services list          # Show registered services
/goodvibes:services test Github   # Test service connectivity

Output Style

Switch execution modes:

/output-style goodvibes:vibecoding
/output-style goodvibes:justvibes

Slash Commands

License

MIT License - see LICENSE for details.

Plug in, receive good vibes

claude plugin marketplace add mgd34msu/goodvibes-plugin
claude plugin install goodvibes@goodvibes-market
claude --init-only