Content
<div align="center">
<img src="./logo.svg" alt="Auditor Addon Logo" width="400">
### *The LLM Multi Tool for Code Auditing*
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
**A Gemini CLI Extension and Claude Code Plugin with Skills and Tools for code estimation, security auditing, and professional report writing.**
</div>
## 🎯 Skills
Skills are structured workflows that guide the AI through multi-step processes. Each skill contains detailed instructions, phases, and best practices for specific tasks.
| Skill | Purpose | Capabilities |
|:------|:--------|:-------------|
| 🛡️ **security-auditor** | Interactive security auditing with Map & Probe methodology | Map (structural inventory) → Checklist (optional, standard-specific) → Probe (per-path vulnerability analysis) |
| 🔍 **threat-modeling** | Systematic threat enumeration before code-level auditing | Analyze → Diagram → Attackers → Assets → Threats (STRIDE) → Report |
| 📊 **estimator** | Project scoping and effort estimation | Full scope (Discovery, Explore, Metrics, Report) or Diff scope (Discovery, Review, Report) |
| 🧠 **design-challenger** | Challenge overcomplicated designs | Propose simplifications with explicit trade-offs |
| 📝 **scribe** | Report writing and finding generation | Professional issue descriptions, report introductions |
### How Skills Work
Skills provide complete workflows that the AI follows autonomously. When invoked, the AI loads the skill's protocol and executes it step-by-step, using the available tools as needed. Each skill can be invoked through its respective slash command (e.g., `/security-auditor`, `/estimator`).
> [!NOTE]
> **Model Performance**: Skills perform differently across AI models. Depending on your needs, you may want to adjust the model for optimal results:
> - **Speed**: Lighter models (e.g., Claude Haiku, Gemini Flash) execute faster but may miss subtle issues
> - **Reasoning Effort**: More capable models (e.g., Claude Sonnet/Opus, Gemini Pro) provide deeper analysis and better edge case detection
> - **Thoroughness**: Higher-tier models tend to be more comprehensive in their exploration and validation
> - **Verbosity**: Models with higher reasoning capabilities can be less verbose in their thinking process
>
> Experiment with different models to find the right balance for your use case.
---
## 🧰 Tools
Tools provide structured code analysis through Tree-sitter AST parsing. They support glob patterns for analyzing multiple files at once. Skills use these tools automatically as part of their workflows.
### 👀 `peek`
Extracts function and method signatures from source files without reading full implementations. The **estimator** skill uses peek to quickly understand a codebase's API surface, what functions exist, their parameters, visibility, and modifiers. This is ideal for initial exploration and building a mental map of unfamiliar code, without the need to read full files.
### 📏 `metrics`
The metrics tool calculates code metrics:
- **Normalized Lines of Code (nLOC)**: Total lines minus blank lines, comment-only lines, and multi-line constructs normalized to single lines (e.g., a function signature spanning 3 lines counts as 1).
- **Lines with Comments**: Count of lines containing comments, including inline comments.
- **Comment Density**: Percentage of lines that have/are comments, indicating documentation coverage.
- **Cognitive Complexity**: Measures control flow complexity by counting branches (if, for, while, etc.) weighted by nesting depth. Deeply nested logic scores higher than flat code.
- **Estimated Hours**: Review time estimate based on nLOC, adjusted by complexity (penalty for high, benefit for low) and comment density (benefit for well-documented code).
The **estimator** skill uses this tool to calculate how long it takes to perform a security audit.
### 📊 `diff_metrics`
Calculates metrics for code changes between two git refs (commits, branches, or tags). Useful for estimating incremental audit effort when reviewing pull requests or comparing versions.
- **Added/Removed Lines**: Tracks line changes per file
- **Diff nLOC**: Lines of code added (excluding blanks and comments)
- **Diff Complexity**: Sum of nesting depths for changed lines (deeply nested changes score higher)
- **Estimated Hours**: Review time for the diff, using the same estimation formula as `metrics`
Deleted files are considered "free" (zero effort) since they reduce attack surface.
### 🔍 `diff`
Returns the actual diff content between two git refs, with two output modes:
- **`full`**: Raw unified diff per file - useful for deep inspection during security audits
- **`signatures`**: Function-level changes (added/modified/removed) - useful for understanding structural changes
The signatures mode compares function signatures between base and head versions:
- **Added**: Functions that exist only in head (new code to review)
- **Modified**: Functions that exist in both but contain changed lines
- **Removed**: Functions that existed in base but are gone (verify intentional, check for lost validation)
### ⛓️ `call_chains`
Traces call chains from root functions (functions nothing else calls) through the full call graph, grouped by root and sorted longest-first. The **security-auditor** skill uses this to understand how execution flows through a system and to identify attack surfaces. A hotspot summary highlights functions appearing across the most chains, giving an immediate prioritization signal for where to focus the audit.
### 🌐 Supported Languages
<div align="center">
| Language | Peek | Call Chains | Metrics |
|:--------:|:-----------:|:-----------:|:-------:|
| 🔷 **Solidity** | ✅ | ✅ | ✅ |
| 🦀 **Rust** | ✅ | ✅ | ✅ |
| 🐹 **Go** | ✅ | ✅ | ✅ |
| 🐍 **Python** | ✅ | ✅ | ✅ |
| 🐪 **Cairo** | ✅ | ✅ | ✅ |
| 📦 **Compact** | ✅ | ✅ | ✅ |
| 💧 **Move** | ✅ | ✅ | ✅ |
| 🌑 **Noir** | ✅ | ✅ | ✅ |
| 🧩 **Tolk** | ✅ | ✅ | ✅ |
| ⚙️ **Masm** | ✅ | ✅ | ✅ |
| ⚡ **C++** | ✅ | ✅ | ✅ |
| ☕ **Java** | ✅ | ✅ | ✅ |
| 🟨 **JavaScript** | ✅ | ✅ | ✅ |
| 🔷 **TypeScript** | ✅ | ✅ | ✅ |
| 🧩 **TSX** | ✅ | ✅ | ✅ |
| 🌀 **Flow** | ✅ | ✅ | ✅ |
</div>
## 📦 Installation
### Via Claude Code Plugin
```bash
# 1. Start Claude Code
claude
# 2. Go to plugins
/plugin
# 3. Navigate to Marketplaces tab
# 4. <enter> on "+ Add Marketplace"
# 5. Paste this repo's link, <enter>
# 6. Hit <space> and <i>
```
### Via Gemini CLI Extension
> [!NOTE]
> This extension uses Skills. Please ensure the **Skills Preview** feature is enabled in your Gemini CLI settings. Confirm by typing `/skills list` in the CLI.
```bash
# Install the MCP server
gemini extensions install <this repository URL>
# Verify installation
gemini extensions list
```
### Local Development Setup
```bash
# Clone the repository
git clone <repository-url>
cd auditor-addon
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run tests
pnpm test
# Watch mode for development
pnpm test:watch
```
---
## 🏗️ Architecture & Design
### Core Principles
- 🧩 Modular: Clear separation between MCP protocol, engine, and language adapters
- 🔌 Extensible: Easy to add new languages via `BaseAdapter` inheritance
- 🔄 DRY: Common logic shared via `BaseAdapter` class
- ✅ Tested: Tests for all language adapters
### Technology Stack
- **Runtime**:  
- **AST Engine**: [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) - Fast, incremental parsing for various languages
- **Output Format**: [TOON](https://github.com/toon-format/toon) - Token-Oriented Object Notation
- **Protocol**: [MCP](https://modelcontextprotocol.io) - Model Context Protocol
- **Testing**: 
### Key Project Files
- [`.claude-plugin/`](./.claude-plugin/): 🔌 Claude Code plugin configuration
- [`CLAUDE.md`](./CLAUDE.md): 🤖 Claude Code plugin context guide
- [`GEMINI.md`](./GEMINI.md): 🤖 Gemini CLI extension context guide with workflow instructions
- [`gemini-extension.json`](./gemini-extension.json): ⚙️ Gemini CLI extension configuration
- [`skills/`](./skills/): 🎯 Skill definitions and protocols
- [`src/languages/`](./src/languages/): 🔧 Language adapter implementations
- [`commands/`](./commands/): 📋 Command alias definitions for Gemini CLI
