✨ Core Features

• 🧠 Persistent AI Memory Moat: Keeps project context intact across chat sessions via version-controlled .avvarre/ markdown files and a local SQLite memory.db store. Features iterative <private> tag redaction, multi-stage deduplication (5-minute in-memory burst, 15-minute rolling hash, Jaccard token similarity, and ONNX cosine embedding similarity), topic-key revisions, and hybrid RRF search (FTS5 + Vector + Graph) with project-isolated SQL filtering.
• 🕸️ AST Code Review Graph (On-Demand Freshness): SQLite-backed dependency tracker across 15 languages using web-tree-sitter. Re-indexes affected files on edit events with hash-checked parsing (<5ms unchanged, <50ms changed) and calculates blast-radius impact warnings before code modifications.
• 🎯 Smart Stack & Community Skill Detector: Scans project manifests (package.json, requirements.txt, go.mod, etc.), framework signatures, and file extensions to suggest community rules from awesome-cursorrules, complete with project-level skill suppression tracking (.declined.json). Fully validated by 74 vitest unit tests.
• 🔄 Autopilot Self-Correction Loop: Enables agents to run /avvarre:autopilot to autonomously resolve code style and structural violations until achieving a Grade A (90+) quality score.
• 🪝 Multi-IDE Lifecycle Hooks: Integrates into bootstrap, prompt loading, impact warning, and session sync lifecycle events across 6 major IDE plugins.
• 🔌 Universal IDE Portability: Operates as a unified Model Context Protocol (MCP) server compatible with Codex, Cursor, Claude Code, Antigravity 2.0, VS Code + GitHub Copilot, and OpenCode.
• ⚡ Instant Style Guide Audits: Analyzes source code locally against 732 Google Style Guide rules across 21 languages in under 100ms with zero API keys or external dependencies.

🛠️ Tech Stack

• Core Language: TypeScript
• Runtime: Node.js (v22.5+ required for native node:sqlite)
• Parsing Engine: web-tree-sitter (Wasm-based Abstract Syntax Tree parsing, bundled per plugin hooks/graph/wasm/)
• Database: SQLite (built-in via node:sqlite, WAL, graph.db time-boxed 8s + on-demand, memory.db long-term FTS5+vector src/memory/store.ts:1 + memory-schema.sql with soft-delete deleted_at + idx_memories_deleted and FTS purge memories_fts_update_delete/insert v3 migration memory-connection.ts:33)
• Vector: @huggingface/transformers Xenova/all-MiniLM-L6-v2 384d lazy vector.ts:38, AVVARRE_LIGHT=1 FTS-only (memory-connection.ts:45), XDG_CACHE_HOME shared cache vector.ts:16, embedTextSync intentional null stub vector.ts:93
• Testing: vitest + @vitest/coverage-v8 (74 tests across 6 files + harness R@5 93.3%, vitest.config.ts:13 includes memory/graph)
• Supported Environments: Codex, Cursor, Claude Code, VS Code / GitHub Copilot, Antigravity 2.0, OpenCode

🚀 Getting Started

1. Prerequisites

Ensure you have Node.js (v22.5 or higher) and npm installed on your local environment. Node 22.5+ is required for the built-in node:sqlite module used by the AST graph engine.

2. Installation

Initialize all compatible local IDE configurations in a single command:

npx -y avvarre@latest install
# Offline / CI / low-RAM — skip 90MB vector model, FTS-only
AVVARRE_LIGHT=1 npx -y avvarre@latest install
# or
npx -y avvarre@latest install --light

3. Target Specific IDE Environments

To target specific IDEs and environments, use the corresponding CLI flags:

• VS Code / Copilot: npx -y avvarre@latest install --vscode
• Cursor: npx -y avvarre@latest install --cursor
• Antigravity (IDE & CLI): npx -y avvarre@latest install --antigravity
• Claude Code (Bootstrap & MCP): npx -y avvarre@latest install --claude
• OpenCode: npx -y avvarre@latest install --opencode
• Codex: npx -y avvarre@latest install --codex

💻 Usage

Slash Commands

Trigger avvarre directly inside your editor or terminal prompt chat:

• /avvarre - Audit the currently active file.
• /avvarre-workspace - Perform a full repository quality and memory scan.
• /avvarre-pr - Audit staged files before commit.
• /avvarre-init - Initialize the local .avvarre/ directory in your workspace.
• /avvarre-autopilot - Start the autonomous quality remediation loop.
• /avvarre-garden - Audit the persistent memory directory for context drift and stale tasks.

In Codex, these workflows are bundled as Avvarre skills. Select them from the skill picker or invoke them explicitly with $avvarre, $avvarre-init, $avvarre-workspace, $avvarre-pr, $avvarre-autopilot, or $avvarre-garden.

CLI Commands

avvarre can be executed directly from your terminal:

• npx avvarre install [--global|--local|--both] [--cursor] [--claude] [--vscode] [--opencode] [--codex] [--antigravity] - Install the MCP server configuration and agent plugins into your IDEs.
• npx avvarre check --file <path> [--format score-only|full] [--light|--fts-only] - Quickly analyze and check the quality score and violations of a specific file. --light/AVVARRE_LIGHT=1 = FTS-only (skip 90MB vector model).

MCP Tools

avvarre exposes 17 MCP tools that can be invoked programmatically:

• avvarre_file: Runs local rules analysis and outputs quality score, list of violations, and drop-in fixes. Takes workspaceRoot to auto-log to history.
• avvarre_workspace: Scans the entire project and outputs a quality score heatmap. Configurable via ai_depth, include_badge, include_trends.
• avvarre_pr: Evaluates staged git changes and fails below a threshold score (minScoreThreshold, default 80).
• avvarre_get_impact: Queries the AST graph to analyze modification blast-radius, dependency risk scores, and coverage gaps.
• list_rules: Lists available Google Style Guide rules, filterable by language.
• scaffold_avvarre: Guided interactive setup for .avvarre/ workspace assets.
• setup_claude_code: Bootstrap Claude Code — creates .claude/, .avvarre/, and CLAUDE.md.
• suggest_skills: Auto-detects package stack and downloads/declines community rules (detect/fetch/decline actions with .declined.json).
• avvarre_garden: Audits the workspace persistent memory folders (.avvarre/) to detect context drift, conventions mismatch, and stalled task lists.
• Long-Term Memory (8 tools): | Tool | Purpose | Key params | |---|---|---| | avvarre_memory_store | Save with dedup 5m DedupWindow+15m hash+Jaccard 0.7+cosine 0.92 strength 0.1..10 (server.ts:573, store.ts:12) | title, content, kind, topic_key, scope, strength | | avvarre_memory_search | Hybrid BM25(0.4)+vector(0.6)+graph(0.3) RRF k=60 exp(-0.01) diversify 3 (search.ts:10) | query, project, scope, kind, limit — AVVARRE_LIGHT=1 FTS-only | | avvarre_memory_timeline | Focus + before/after neighbors (store.ts:179) | id, before, after | | avvarre_memory_get | Get by id (soft-delete aware) | id | | avvarre_memory_delete | Soft/hard delete | id, hard | | avvarre_memory_digest | ~70 tok recent+stale+pinned (retention.ts:50) | project, limit | | avvarre_memory_sweep | TTL+180d/low sweep (no LLM) (retention.ts:26) | workspaceRoot | | avvarre_suggest_topic_key | Family heuristic architecture/bug/... (hygiene.ts:68) | type, title, content | — memory.db src/db/memory-schema.sql + vectors ~/.cache/avvarre (vector.ts:16).

Resources: avvarre exposes 21 MCP resources (one per language) at avvarre://rules/{language} so AI agents can query rule rationales directly.

⚙️ Configuration & Architecture Deep-Dive

⚠️ The Problem

Vibe coding is fast, but AI models quickly lose context:

• The memory resets: Every new chat session starts from absolute zero. You spend precious time re-explaining the tech stack, directory paths, and code conventions.
• Style guides are ignored: The AI writes code that runs but breaks project style guides—leading to inconsistent naming, undocumented functions, and spaghetti patterns.
• Verification is manual: Linters run in your terminal after the fact, not during the AI's generation process. Errors are caught too late.
• Tooling sprawl: You need different linters for different languages—ESLint, Ruff, Checkstyle, SwiftLint—or you can just use avvarre for all of them.

💡 The Solution

avvarre is an IDE-agnostic MCP server and agent plugin ecosystem that embeds directly into your AI workflows.

[!NOTE]

• Grade F to Grade A: Analyzes and suggests clean style guide fixes in milliseconds.
• Continuous Handoff: Dev A works Monday, Dev B pulls Tuesday—the AI immediately catches up on context.
• Autopilot Remediation: Let the AI autonomously clean up its own violations before presenting them to you.

avvarre operates across 8 layers to lock down quality and context:

• Layer 1: Persistent AI Memory (The Core Moat) — Creates a version-controlled .avvarre/ directory in your workspace storing state documents (context.md, conventions.md, tasks.md, session-log.md, history.json, and modular skills/) plus SQLite memory.db long-term store.
• Layer 2: Smart Stack Detection (Hard-Tested) — Scans package.json/go.mod/Cargo.toml + configs (tsconfig.json) + extensions at startup, maps to 12 fetchable skills, and tracks .declined.json — 74 vitest tests + 8 memory (AVVARRE_LIGHT=1) + harness R@5 93.3%, stack_detector 97% coverage, mocked https 301/404/500 + fs corruption + dedup + alreadyFetched vs declined precedence. (vitest.config.ts:13 covers memory/graph)
• Layer 3: Rule-Based Linting Engine — Instant style guide analysis enforcing 732 Google Style Guide rules locally across 21 languages with zero API keys or cloud dependencies.
• Layer 4: AI-Powered Deep Review — Catches semantic design issues (logical anti-patterns, leaky abstractions, or hard-to-maintain closures) using configured LLMs.
• Layer 5: Autopilot Loop — Self-correction loop where the agent autonomously repairs code violations (fixing, checking, and validating) up to 15 times until hitting Grade A (90+).
• Layer 6: Lifecycle Hooks (On-Demand Freshness) — Automates quality and context checks (SessionStart 4×15 PreToolUse 15 PostToolUse 5 UserPromptSubmit 5 Stop 30 PreCompact 10):
  • Bootstrap: Prompts to init project memory if .avvarre/ is missing.
  • Context Loader: Injects conventions and task targets into prompt context.
  • Skill Suggest: Recommends relevant plugins based on package signatures (once per session, alreadyFetched + declined filtered).
  • Impact Warn: On-demand full-parse pre-tool hook (Write|Edit|...) re-indexes affected files before CTE (9s guard, delete handling) and alerts on downstream risks — WASM bundled in every plugin.
  • Memory Hooks: SessionStart digest ~70 tok (retention.ts:50), PostToolUse+UserPromptSubmit auto-save hook-memory-store.cjs:46 8000 truncate + 500ms + stripPrivate, PreCompact checkpoint topic_key=session-compact — triple survival across 6 plugins (Claude/Cursor/Antigravity/Codex/OpenCode/Awesome).
  • Session Sync & Doc Gardening: Writes session-log.md when the agent exits/goes idle, runs automated context/conventions/tasks freshness audits, and displays warnings to prevent memory rot.
• Layer 7: IDE Portability — One MCP server powers all major AI dev clients: Claude Code, OpenCode, Antigravity 2.0, VS Code + GitHub Copilot, Cursor, and Codex.
• Layer 8: AST Code Review Graph — SQLite-backed dependency graph tracer (CALLS, IMPORTS_FROM, INHERITS, TESTED_BY) across 15 languages (JavaScript, TypeScript, Python, Go, Java, C#, C++, Shell, Kotlin, Swift, Objective-C, Dart, HTML, CSS, R). Calculates blast radius via recursive CTE queries prior to edits.

graph TD
    classDef clientStyle fill:#1e1b4b,stroke:#818cf8,stroke-width:2px,color:#e0e7ff;
    classDef hookStyle fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#e0f2fe;
    classDef serverStyle fill:#022c22,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef dbStyle fill:#1c1917,stroke:#fb923c,stroke-width:2px,color:#fff7ed;
    classDef storageStyle fill:#311042,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;

    subgraph Clients ["1. IDE Clients & Plugins"]
        CC["Claude Code - settings.json"]:::clientStyle
        AG["Antigravity 2.0 - IDE & CLI Plugins"]:::clientStyle
        CO["VS Code & Copilot - awesome-copilot"]:::clientStyle
        CU["Cursor - MCP integration"]:::clientStyle
    end

    subgraph Hooks ["2. Lifecycle Hooks"]
        HB["Bootstrap Hook"]:::hookStyle
        HC["Context Loader"]:::hookStyle
        HS["Skill Suggest"]:::hookStyle
        HI["Impact Warn"]:::hookStyle
        HE["Session Sync"]:::hookStyle
    end

    subgraph Server ["3. avvarre MCP Server"]
        RE["Rules Engine (732 Google Rules)"]:::serverStyle
        AST["AST Graph Engine (Tree-Sitter)"]:::serverStyle
        AI["AI Semantic Reviewer (LLMs)"]:::serverStyle
    end

    subgraph Storage ["4. Workspace Memory Moat"]
        Docs["State Docs (.avvarre/)"]:::storageStyle
        Skills["Modular Skills"]:::storageStyle
        DB[("graph.db (SQLite)")]:::dbStyle
    end

    %% Flows
    Clients -->|Trigger| Hooks
    Hooks -->|Execute| Server
    Server -->|Sync / Index| Storage

    %% Detailed connections
    HC -->|Read context| Docs
    HC -->|Load| Skills
    HI -->|Query blast radius| DB

🗄️ Database Schema (graph.db)

Stored locally using node:sqlite, the schema tracks code declarations and relationships:

• nodes: Tracks declarations of files, classes, methods, and functions.
  • kind: 'File', 'Class', 'Function', 'Test'
  • qualified_name: Uniquely namespace-scoped identifier (e.g. src/server.ts::Router::handleRequest)
  • file_hash: SHA-256 hash of the containing file's text content, enabling incremental parsing.
• edges: Tracks structural links between symbols.
  • kind: 'CALLS' (invocations), 'IMPORTS_FROM' (module imports / #include / source), 'INHERITS' (class inheritance / interface implementation), 'TESTED_BY' (test-to-production mapping via call-graph + name heuristics).
  • source_qualified & target_qualified: Connecting node references using the filePath::Class::method qualified-name scheme.

🛠️ High-Performance AST Extraction

The AST parsing engine (parser.ts) uses WebAssembly grammars (web-tree-sitter) loaded dynamically on-demand from tree-sitter-wasms. It supports 15 extensions: JavaScript, TypeScript (+ TSX), Python, Go, Java, C#, C++, Shell (Bash), Kotlin, Swift, Objective-C, Dart, HTML, CSS, and R — 13 with full AST (Dart currently falls back to File-level due to ABI 15 vs [email protected] range 13-14; R falls back until tree-sitter-r.wasm ships in tree-sitter-wasms).

• Language-Accurate Extraction: Each language uses its verified grammar node types (probed empirically). Classes, functions, tests, imports, and inheritance chains are extracted per language's AST shape—not via regex.
• Three Edge Types: CALLS (callee names stripped to bare identifiers for cross-file join), IMPORTS_FROM (module paths cleaned of quotes), and INHERITS (base class / interface names). TESTED_BY edges are synthesised post-indexing by updateTestedByEdges().
• Namespace Scoping: A scopeStack maintains the filePath::Class::method hierarchy as the AST is walked depth-first.
• Incremental Hashing Moat (On-Demand): On every PreToolUse hook-impact-warn + tool.execute.after (and avvarre_get_impact), the engine re-indexes only affected files before the CTE — hash-checked (<5ms if unchanged, <50ms if changed), 9s guard, removeFileData on delete, WASM fallback to read-only. Scaffold is time-boxed to 8s (remaining indexed lazily), and WASM grammars (tree-sitter-wasms 15 wasm) are bundled into every plugin hooks/graph/wasm/ (claude/cursor/antigravity/codex/awesome/opencode — 6 plugins, scripts/postbuild.cjs:43) so all 6 IDEs get full parse without a watcher.

📈 Change Risk Calculation Formula

When files are edited, avvarre calculates risk based on test coverage, security tags, and downstream calls:

$$ \text{Risk Score} = (\text{Coverage Penalty} + \text{Fan-in Load}) \times \text{Security Multiplier} $$

1. Test Coverage Penalty:
   • Symbol lacks TESTED_BY edges: 0.30 penalty.
   • Symbol is covered: 0.05 penalty.
2. Fan-in Call-Graph Load:
   • Caller count (incoming CALLS edges): adds Math.min(callerCount / 20.0, 0.10).
3. Security Multiplier:
   • Name matches sensitive tokens (auth, login, credential, password, passphrase, token, secret, admin, jwt, wallet, session, encrypt, decrypt, privatekey, private_key, apikey, api_key, oauth, sshkey): 2.5x multiplier.
   • Otherwise: 1.0x multiplier.

The final risk score is normalized and clamped strictly between 0.0 and 1.0.

🔍 Recursive CTE Blast-Radius Query

avvarre executes a recursive Common Table Expression query up to a depth of 5 hops to trace caller dependencies:

WITH RECURSIVE impacted(node_qn, depth) AS (
    SELECT qn, 0 FROM _impact_seeds
    UNION
    -- Forward callee traversal
    SELECT n.qualified_name, i.depth + 1
    FROM impacted i
    JOIN edges e ON (e.source_qualified = i.node_qn OR i.node_qn LIKE '%::' || e.source_qualified)
    JOIN nodes n ON (n.qualified_name = e.target_qualified OR n.qualified_name LIKE '%::' || e.target_qualified)
    WHERE i.depth < 5
    UNION
    -- Backward caller traversal
    SELECT e.source_qualified, i.depth + 1
    FROM impacted i
    JOIN edges e ON (e.target_qualified = i.node_qn OR i.node_qn LIKE '%::' || e.target_qualified)
    WHERE i.depth < 5
)
SELECT DISTINCT node_qn, MIN(depth) AS min_depth
FROM impacted
GROUP BY node_qn LIMIT 200;

If downstream caller dependencies exist, the edit process halts and prompts a context warning.

🛡️ Language Rules & Grading Logic

Grading Scale

• Grade A (90–100): Google-grade quality code.
• Grade B (80–89): Minor style points only.
• Grade C (70–79): Needs attention.
• Grade D (60–69): Heavy style violations.
• Grade F (0–59): Critical structural issues.

[!TIP] Penalties are weighted by severity: critical = 15, high = 10, medium = 5, low = 2. Large files are dynamically dampened using log-normalization so they are not unfairly penalized.

Language Support (732 Rules)

| Language | Rules | Language | Rules | Language | Rules | | :------------------- | :---: | :-------------------- | :---: | :----------------- | :---: | | TypeScript | 74 | Dart | 49 | Shell | 37 | | JavaScript | 49 | Python | 46 | C++ | 44 | | Kotlin | 40 | Objective-C | 42 | C# | 37 | | Java | 39 | Go | 33 | Swift | 35 | | R | 36 | Vimscript | 19 | Lisp | 26 | | HTML | 16 | CSS | 15 | Markdown | 17 | | JSON | 16 | XML | 16 | Angular | 16 |

🔑 LLM Provider Configuration

avvarre is offline-first, but you can configure external LLM providers for semantic deep reviews:

• Gemini: Set the following environment variables:

  AI_PROVIDER="gemini"
  GEMINI_API_KEY="your-gemini-api-key"

• OpenAI: Set the following environment variables:

  AI_BASE_URL="https://api.openai.com/v1"
  AI_API_KEY="your-openai-api-key"
  AI_MODEL="gpt-4o"

• Local Models (Ollama / LM Studio): Set the base URL pointing to your local endpoint:

  AI_BASE_URL="http://localhost:11434/v1"
  AI_MODEL="your-local-model"

📂 Persistent Memory Structure (.avvarre/)

avvarre creates a version-controlled directory at the root of your project:

• context.md — Project purpose, tech stack, and system architecture.
• conventions.md — Custom styling preferences, naming rules, and patterns.
• tasks.md — Compact task tracker designed for AI ingestion.
• session-log.md — AI handoff log from the last active session.
• history.json — Quality score tracking history.
• skills/ — Modular feature guidelines and domain-specific rules.

scaffold_avvarre parameters (src/server.ts:280)

| Param | Type | Description | |---|---|---| | workspaceRoot | string required | Absolute path to workspace root | | projectName | string | Project name (auto from package.json) | | description | string | One-line description | | techStack | string | Languages, frameworks, databases | | targetAudience | string | Who is the target user | | keyFeatures | string[] | Initial tasks / key features | | externalApis | string | External APIs or services used | | namingConventions | string | Custom naming rules | | maxFileLines | number | Max lines before warning (default 1500) |

Instead of bloating context by feeding the AI your entire repository, avvarre dynamically loads only the relevant skill file for the active task (e.g., database_schema_rules.md, react_ui_guidelines.md).

📦 Monorepo Support

To enable monorepo support, set chat.useCustomizationsInParentRepositories to true in your VS Code settings. Place avvarre at the root:

monorepo/
├── awesome-copilot/  ← avvarre hooks, agent, skills, commands (VS Code)
├── cursor-plugin/    ← avvarre hooks, agent, skills, commands (Cursor)
├── .avvarre/          ← Shared project memory
└── packages/
    ├── frontend/     ← Open this folder — hooks still fire
    └── backend/      ← Open this folder — hooks still fire

🔌 Manual Plugin Setup

If you prefer to configure integrations manually, use the following configurations:

Claude Code

Copy claude-plugin/ to your workspace and add it to .claude/settings.json:

{
  "plugins": ["./claude-plugin"]
}

VS Code + GitHub Copilot

Copy awesome-copilot/ to your workspace and add this to your global VS Code settings:

{
  "chat.plugins.enabled": true,
  "chat.plugins.paths": ["./awesome-copilot"]
}

Cursor

Add avvarre to your Cursor MCP settings panel:

• Name: avvarre
• Type: command
• Command: npx -y avvarre@latest

Codex

You can automatically set up the Codex plugin using the installer (npx -y avvarre@latest install --codex). Alternatively, this repository includes a Codex plugin at plugins/avvarre and a repository marketplace at .agents/plugins/marketplace.json. Open the repository in the ChatGPT desktop app, restart it, select Avvarre Plugins, and install Avvarre. Review and trust the bundled hooks before they run.

For a Git-backed marketplace, add the repository with codex plugin marketplace add PralhadYadawad/avvarre, then install avvarre from the avvarre marketplace. Public availability uses the official plugin submission portal.

Antigravity 2.0 (IDE & CLI)

Copy antigravity-plugin/ to:

• Workspace: .agents/plugins/avvarre
• Global IDE: ~/.gemini/config/plugins/avvarre
• Global CLI: ~/.gemini/antigravity-cli/plugins/avvarre

🤖 AI Review Agent (@avvarre-reviewer)

The @avvarre-reviewer agent acts as a virtual auditor inside your chat workspace:

1. Gathers context and runs avvarre_file on changed files.
2. Orders fixes sequentially (high severity first).
3. Modifies code, re-runs verification, and updates tasks.md dynamically on success.

💎 Strategic Moats

• Token Optimization & Context Moat: Traditional code agents reload entire code files or subdirectories to understand impact, burning through context windows. avvarre solves this by indexing the project architecture in a local, fast database—loading only the necessary symbols when requested.
• Offline First & Airgapped Compliance: The core linting engine, SQLite DB, and tree-sitter parser run 100% locally. There is no telemetry, external network requests, or cloud dependency.
• Multi-IDE Handoff Sync: The .avvarre/ directory acts as a portable memory block. Dev A using Cursor and Dev B using Claude Code share the same session context, task states, and architecture guidelines.
• Graceful Degradation Moat: The server never blocks the developer. If an LLM key is missing, it runs local regex checks. If a file is too large for the model, it auto-chunks. If the AST parser fails, it defaults back to file-level lint rules.

🎯 Key Use Cases

• Continuous Handoff in Distributed Teams: When developers swap tasks, the AI reads the session-log.md and tasks.md to pick up exactly where the last agent left off—eliminating onboarding handoff friction.
• AST-Guided Quality Gates (CI/CD): Run avvarre_pr in your PR pipeline or pre-commit hooks to verify that code changes do not decrease the overall repository quality score below a set threshold.
• Blast-Radius Visual Warnings: During large refactors, the agent is immediately warned if modifying a shared method would break downstream endpoints, prompting it to write corresponding unit tests.

🎨 Design Philosophy

• Zero configuration to start: Out-of-the-box linting runs locally in under 100ms. No cloud keys needed.
• Graceful degradation: Gracefully falls back to regex analysis if LLM keys are absent, chunks files if too large, and never blocks code editing.
• Bypass memory limits: Scopes rule-sets and tasks into modular skills, avoiding context window clutter.
• Single Tool, Every Stack: Replaces fragmented quality chains with a single standard MCP engine.

🔍 Under the Hood

• Hardened Tokenizer: The getCleanLines utility strips out comments and raw strings before rules execute. This eliminates false positives triggered by URLs in strings or notes in comments.
• AST-Aware Chunker: Files exceeding LLM token capacities (~500 lines) are safely split at class/function AST boundaries using a parser-driven chunker (chunker.ts) across all 15 supported languages, reviewed individually per chunk, and merged with corrected line numbers. Falls back to line-based splitting if AST parsing is unavailable.
• Direct Resources: Every language style guide exposes rules as a avvarre://rules/{language} resource endpoint for agents to query.

📝 The Compressed Task Protocol

AI agents communicate across sessions using a compact format inside tasks.md:

[x] Built user auth flow (steps: schema→routes→middleware→tests→docs)
[/] Refactoring payments (done: extract-service→add-types | next: update-routes→tests)
[ ] Add rate limiting to API endpoints

Agents parse these steps directly into their working memory context, resolving context drift during task handoffs.

🛣️ Roadmap & Contributing

We welcome contributions to expand rulesets, IDE plugins, and integrations.

Local Development

1. Clone the repository:

   git clone https://github.com/PralhadYadawad/avvarre.git

2. Install dependencies:

   npm install

3. Build the project locally:

   npm run build

4. Run hard tests (skill stack + graph + hooks + memory, isolated temp fixtures):

   npm test              # 74 tests across 6 suites
   AVVARRE_LIGHT=1 npx vitest run src/memory/memory.test.ts # 8 memory hygiene/search/retention
   node scripts/run-harness.cjs # micro-15Q R@5 93.3%
   npm run test:coverage # v8, uncovered lines shown

5. Start the server:

   npm start

Troubleshooting

If lifecycle hooks fail to execute:

1. Enable agent debug logs inside your VS Code settings:

   "github.copilot.chat.agentDebugLog.enabled": true

2. Reload your IDE.
3. Run /troubleshoot in Copilot Chat to review logs.

Per-IDE logs:

• Claude Code: claude --debug / CLAUDE_DEBUG=1 + check .claude/settings.json hooks hookSpecificOutput
• Cursor: View → Output → Avvarre + cursor-plugin/hooks/hooks.json
• OpenCode: AVVARRE_WORKSPACE=. npx opencode --debug + opencode-plugin/plugins/avvarre/index.ts:540 tool.execute.after
• Antigravity: antigravity --verbose + hooks.json injectSteps

Vector offline / --light:

• AVVARRE_LIGHT=1 or --light/--fts-only skips 90MB Xenova/all-MiniLM-L6-v2 download, uses FTS-only BM25 (vector.ts:38, memory-connection.ts:45). Cache is XDG_CACHE_HOME or ~/.cache/avvarre (vector.ts:16, shared across plugins). embedTextSync intentionally returns null (vector.ts:93) — callers fallback to FTS.
• Env power users: AVVARRE_CACHE_DIR, AVVARRE_COSINE_MERGE=0.92, AVVARRE_EMBED_DIM=384/768.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.