ai-toolbox
Public
Forked from crunch3r/ai-toolbox
Forked from crunch3r/ai-toolbox
Comprehensive overview of the AI Toolbox plugin, its architecture, features, and recent changes. This document provides a high-level summary for developers, maintainers, and users.
AI Toolbox Plugin is a comprehensive LM Studio plugin providing 108 tools across 17 categories for AI-assisted development workflows. The plugin enables language models to interact with file systems, execute code, browse the web, manage Git repositories, process documents, and more — all within a secure, configurable framework.
| Category | Tool Count | Purpose |
|---|---|---|
| File System | 17 tools | Read, write, search, and manage files with path validation |
| Web Research | 4 tools | Multi-engine search (DDG, Google, Bing) with automatic fallback |
| Browser Automation | 5 tools | Headless Puppeteer browser with persistent sessions |
| Git & GitHub | 15 tools | Full Git operations + GitHub API integration |
| Database | 1 tool | Read-only SQLite queries with SQL validation |
| Document Parsing | 1 tool | PDF, DOCX, TXT document reading (disk paths + attachments) |
| Background Commands | 3 tools | Long-running process management with timeout control |
| Execution | 5 tools | Sandboxed JS/Python + full shell commands (pipes, redirects) |
| Utilities | ~29 tools | Clipboard, notifications, system info, memory, session summaries, JSON query, env management |
| Image Processing | 4 tools | OCR (Tesseract.js), screenshots (Win32 API), image comparison |
| HTTP Client | 3 tools | REST API client with SSRF protection |
| Vector RAG | 4 tools | Semantic search with local embeddings, persistent state |
| Text Processing | 5 tools | Regex substitutions (text_transform), field extraction (text_extract), line operations, markdown table gen |
| Interactive UI Generation | 3 tools | Generate and render HTML/CSS/JS components (buttons, forms, charts) |
| Auto-Context Management | 7 tools | Automatic session tracking, decision logging, persistent memory |
| Backup & Restore | 4 tools | Create compressed ZIP backups with atomic write pattern |
Total: 108 tools across 17 categories ✅
All tools implement security controls by default:
All I/O operations use async/await to avoid blocking the event loop:
fs.promisesAutomatic session tracking and memory persistence:
.ai_toolbox_context.msgpack for compact binary formatComprehensive configuration via Zod schemas:
| Module | Purpose | Key Features |
|---|---|---|
config.ts | Configuration schema + UI toggles | Zod validation, default values, category gating |
security.ts | Input validation & sanitization | Path traversal prevention, command pattern blocking |
stateManager.ts | Persistent state with debounced writes | Atomic file operations, corruption recovery |
toolsProvider.ts | Central tool registration | Config-based filtering, God Mode bypass |
promptPreprocessor.ts | Document RAG + ContextGuard integration | History compression, temporal awareness injection |
Each category is implemented as a separate module in src/tools/:
Comprehensive performance overhaul targeting disk I/O reduction, cache utilization, and event-loop contention across stateManager.ts, autoTracker.ts, contextGuard.ts, and performanceUtils.ts.
cacheFuzzyResults() now deletes + re-inserts on access; Map insertion order ensures oldest entries (front) are evicted, not least-recently-used. Better cache hit rates for frequently queried file paths during IDE navigation.Total: 6 source files modified (stateManager.ts, autoTracker.ts, contextGuard.ts, performanceUtils.ts), zero breaking changes, fully backward compatible. All optimizations validated against existing test suite (369 tests pass).
refactor_code Full AST-Based extract_function ImplementationReplaced the entire Git/GitHub toolset with pure JavaScript isomorphic-git, resolving Windows path parsing bugs and eliminating native dependency overhead.
git_stash, git_blame & markdown_table_gen ToolsAdded json_query and env_update tools, plus @/ path aliases and ESLint fixes.
grep_files AST Mode Fallback FixFixed 3 failing AST mode tests caused by missing regex parameter in AST fallback path.
When mode: 'ast' was used with grep_files and AST parsing failed, the fallback to regex mode crashed silently. The fix passes the pre-validated regex variable, enabling proper fallback behavior.
Total: 1 line changed in src/tools/fileSystemTools.ts, zero breaking changes.
Fixed silent line ending corruption across 5 file-modifying tools on Windows.
Tools that split file content into lines (insert_at_line, delete_lines_in_file, text_transform line-range mode, line_operations, delete_lines) now detect \r\n (CRLF) before splitting and preserve it on output. Files with Windows-style line endings are no longer silently converted to LF.
Total: 10 code changes across 3 files, zero breaking changes.
Fixed grep_files test path separator normalization and corrected AutoTracker FSM re-trigger logic.
tests/grep_files.test.ts assertions to normalize Windows backslashes (\) to forward slashes (/) before comparison, ensuring reliable cross-platform test execution.Total: 4 assertion blocks updated + 1 logic block removed, zero breaking changes.
get_session_summary now correctly re-reads from the CURRENT working directory on every call.
Fixed stateManager.ts getAllKeys() to ALWAYS reload state from disk before returning keys (previously only loaded once at construction). This ensures reads see the latest data even if working directory changed mid-session via change_directory.
Test suite now passes after fixing MODULE_NOT_FOUND errors for dynamically imported tool modules.
Fixed all tool module dynamic import patterns in jest.config.cjs from two-dot ('\\.\\.') to single-dot ('\\./') regex matching. Removed conflicting ESM config file and added missing module mappings with a fallback catch-all rule.
All file-editing tools now automatically restore .bak backup on write failure.
Four tools (replace_text_in_file, insert_at_line, append_file, delete_lines_in_file) wrap their atomicWriteFile() calls in try/catch:
fs.copyFile(backupPath, fullPath) to restore original[FILE_EDIT] Atomic write failed — attempting rollback from <path>Impact: Protects against silent data corruption on disk-full, permission errors, or I/O failures during file modifications.
Sync → Async Conversion:
fileSystemTools.ts, documentTools.ts, stateManager.ts, contextManagementTools.ts, backupTools.ts, gitGithubTools.tsDocumentation Accuracy:
grep_files Token Consumption Hardening:
max_content_length (150 chars), max_file_size (100KB), max_results (20)save_file Atomic Writes:
writeFileSync with temp file + rename pattern.max() and runtime validationAuto-Tracking Enabled by Default:
autoTrackingEnabled changed from false → truegit_stash — Git Stash ManagementPurpose: Manage git stashes: save, pop, drop, or list uncommitted changes. Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
action | 'save' | 'pop' | 'drop' | 'list' | Yes | Stash action to perform |
message | string | No (required for save) | Optional: Stash message |
Features: Full stash lifecycle management using native exec() fallback (isomorphic-git does not support stash). Path validation via validatePath + resolvePath. |
git_blame — Per-Line Commit HistoryPurpose: Get commit history for specific lines in a file. Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Path to the file to blame |
line_number | number | No | Specific line number (if omitted, blames entire file) |
Returns: Array of { commitHash, author, timestamp, line, originalLine, summary } objects. |
markdown_table_gen — Markdown Table GenerationPurpose: Generate valid Markdown tables from arrays of objects with headers, alignment, and truncation. Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
data | Array<Record<string, unknown>> | Yes | Array of objects to convert |
headers | string[] | No | Custom header names (uses object keys if omitted) |
max_column_width | number | No | Max width per column before truncation (default: 40) |
truncate_ellipsis | string | No | Ellipsis character (default: …) |
json_query — JSON Field Extraction (jq Equivalent)Purpose: Extract specific fields from JSON files using jq-style dot notation queries. Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Path to the JSON file |
query | string | Yes | Query path (e.g., ".data.users[0].name" or ".*.id") |
output_format | 'json' | 'text' | No | Output format: json for structured output, text for raw value (default: text) |
Features: Supports .key, .key.subkey, .array[0], .array[*] (wildcard) syntax. Path validation (no directory traversal). Query depth limit: 50 segments. File size cap: 10MB. Implements safeJsonQuery() helper with comprehensive error handling. |
env_update — Environment Variable ManagementPurpose: Add or update key-value pairs in .env files.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Path to the .env file |
key | string | Yes | Environment variable key (alphanumeric + underscores only) |
value | string | Yes | Environment variable value |
ensure_newline | boolean | No | Ensure the file ends with a newline (default: true) |
Features: Key validation (must start with letter/underscore). Creates key if missing, updates if present. Ensures file ends with newline. File creation if .env doesn't exist. |
analyze_project — Static AnalysisPurpose: Run TypeScript diagnostics, ESLint, circular dependency checks, and import analysis. Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
categories | 'typecheck' | 'circular' | 'eslint' | 'config' | 'imports' | No | Analysis categories to run (default: all) |
max_imports_warning | number | No | Max imports per file before warning (default: 20) |
file_diff — Side-by-Side ComparisonPurpose: Compare two files and return a unified diff with +/- markers and line numbers.
directory_tree — Directory VisualizationPurpose: Visualize the directory structure of a path in a tree-like format. Supports max depth, optional file sizes, and automatic exclusion of large directories.
grep_files — Enhanced SearchPurpose: Search files with regex or AST mode. Includes three-layer token consumption controls (max_content_length, max_file_size, max_results). Fixed AST fallback path in v1.5.20.
run_tests — Test ExecutionPurpose: Execute test suites (Jest, PyTest, Go test) with timeout protection.
rag_web_content — Web Content RAGPurpose: Fetch content from a URL and use RAG to find and return only the text chunks most relevant to a specific query.
find_replace_all — Multi-File Search & ReplacePurpose: Search and replace text across multiple files in a directory using regex. Supports dry-run mode and safety confirmations. Added in v1.5.20.
validatePath() with base path enforcement| Threat | Risk Level | Mitigation | Status |
|---|---|---|---|
| Directory Traversal | High | validatePath() with base path enforcement | ✅ Active |
| Command Injection | Critical | sanitizeCommand() blocks dangerous patterns | ✅ Active |
| ReDoS Attacks | Medium | isSafeRegex() treats unsafe patterns as literals | ✅ Active |
| SSRF (HTTP Client) | High | URL protocol validation + private IP blocking | ✅ Active |
| Token Explosion | High | Three-layer controls in grep_files tool | ✅ Active |
| Large File DoS | Medium | Size limits on file operations (10MB writes, 50KB fetches) | ✅ Active |
All I/O operations use async/await to avoid blocking:
fs.promises for non-blocking reads/writes| Cache | TTL | Max Entries | Purpose |
|---|---|---|---|
| Fuzzy Search | 60s | 100 | File name similarity results with Levenshtein scoring |
| Web Requests | 30s | 50 | HTTP responses for web research tools |
Heavy dependencies loaded on first use to minimize startup time:
npx tsc --noEmit with zero errorsnpm run lint with zero errors| Tool | Version | Purpose |
|---|---|---|
| TypeScript | ^5.9.3 | Strict mode type checking (zero errors) |
| tsup | ^8.3.5 | Bundler for production builds (ESM + CJS) |
| Jest | ^30.0.0 | Test framework with ESM mocking |
| ESLint | ^9.15.0 | Code quality enforcement |
@/ Path Aliases | Configured | Simplified import resolution (src/* → @/*) |
npm audit with 0 vulnerabilities, 0 warnings ✅All documentation has been reconstructed based on actual source code analysis:
| File | Status | Notes |
|---|---|---|
README.md | ✅ Rebuilt | Accurate tool counts, configuration tables derived from Zod schema |
ARCHITECTURE.md | ✅ Rebuilt | Correct system overview diagram (16 modules), verified data flows |
TOOLS_REFERENCE.md | ✅ Rebuilt | All 108 tools documented with parameter tables matching implementations |
DOCUMENTATION.md | ✅ Rebuilt | Cleaned up duplicate sections, verified version history against source code |
CHANGELOG.md | ✅ Updated | Accurate release dates and tool count corrections |
CONTRIBUTING.md | ✅ Created | Development workflow, adding new tools guidelines |
SAFE_EDIT_GUIDE.md | ✅ Created | Backup-first strategy for safe file editing |
SECURITY.md | ✅ Rebuilt | Threat model, security controls, incident response procedures |
npm test)This summary is based on actual source code analysis performed on 2026-06-30. All tool counts, feature descriptions, and security controls reflect the current implementation in version 1.5.x.
For questions or issues, please refer to the individual documentation files linked above or contact the maintainers through appropriate channels.
fileSystemTools.ts — 17 file system toolswebResearchTools.ts — 4 web research toolsbrowserAutomationTools.ts — 5 browser automation toolsgitGithubTools.ts — 15 Git/GitHub tools (6 git + 9 GitHub API)databaseTools.ts — 1 database tool (SQLite queries)documentTools.ts — 1 document parsing tool (PDF/DOCX/TXT)backgroundCommandTools.ts — 3 background command toolsexecutionTools.ts — 5 execution tools (JS, Python, shell, terminal, tests)utilityTools.ts — ~29 utility tools (clipboard, notifications, system info, JSON query, env management)imageProcessingTools.ts — 4 image processing tools (OCR, screenshots, comparison)httpClientTools.ts — 3 HTTP client tools (GET/POST with SSRF protection)vectorRagTools.ts — 4 vector RAG tools (indexing, querying, clearing, web content)textProcessingTools.ts — 5 text processing tools (transform, extract, line operations, markdown table gen)uiGenerationTools.ts — 3 UI generation tools (buttons, forms, charts, dashboards)contextManagementTools.ts — 7 auto-context management tools (summary, memory, search)backupTools.ts — 4 backup & restore tools (create, list, restore, delete)_queueSave() with 500ms coalescing window replaces fire-and-forget void saveToFile() in set(), delete(), clear(), importState(). Bulk mutations within a 500ms window trigger only 1 batched disk write → ~90% fewer writes._keysCache + _keysCacheInvalidated flag + 1s TTL. Auto-invalidate on every mutation (set/delete/clear). getAllKeys() returns cached result in O(1) instead of clearing state and reloading from disk → critical for auto-tracker threshold checks running per-message.AI_TOOLBOX_DEBUG env var + debugLog() helper replaces unconditional console.warn() on every threshold check, state transition, and message analysis in autoTracker.ts and contextGuard.ts. Production mode (~80% less stderr I/O). Debug mode provides full diagnostic output.import('./tools/contextManagementTools.js') cached to this.contextStorageModule. Replaces dynamic await import() on every flushActionsToMemory() and autoSaveSessionMemory() call → eliminates ~5–10ms per-flush overhead.sizeValueCache: Map<string, number>JSON.stringify()getSizeOfValue()recalculateSize()_projectPathCache + _lastProjectPathCheck with 5s staleness check on getProjectMemoryFilePath(). Eliminates duplicate fs.access() + fs.stat() validation calls during rapid state operations.simple-git wraps native git.exe, causing persistent Windows path escaping issues when repository paths contain spaces (e.g., C:\Source Code\...). It also required ESM/CJS interop casting hacks that violated strict ESLint rules.isomorphic-git@1.38.6. Local operations (status, add, commit, log, checkout) now use pure JS with Node's native fs/promises adapter. Remote push and complex operations (stash, blame) retain native exec() fallbacks for compatibility.json_query: jq-style JSON field extraction with dot notation (.key, .array[0], .array[*]), path validation, query depth limit (50), 10MB file capenv_update: Safe .env key-value management with key name validation, create/update logic, newline enforcement@/ → src/ in tsconfig.json and tsup.config.tsTS2352 in refactorCodeTools.ts with intermediate unknown castidx → _idx) and redundant type assertions (as string on segment)src/autoTracker.ts checkTokenThreshold(). The method now correctly returns true only during the initial IDLE → THRESHOLD_REACHED transition, preventing duplicate checkpoint prompts and redundant memory saves.LM Studio Host
│
▼
Plugin Runner (Node.js 20+)
│
├── Config Layer (Zod schemas + UI schematics)
├── Security Layer (Path validation, command sanitization, SQL guards)
├── State Management (Debounced persistence to JSON/msgpack files)
└── Tool Registry (16 modules → 108 tools total)