Forked from crunch3r/ai-toolbox
Forked from crunch3r/ai-toolbox
TOOLS_REFERENCE.md
TOOLS_REFERENCE.md
Current state: v1.9.24 Β· manifest rev 0 Β· canon 84 suites / 1262 tests Β· 116 tools across the categories (re-counted 07.11:
apply_patchshipped) in the Overview below (two names serve two categories:read_document,rag_web_content). Audited against live code (src/tools/*.ts+toolsProvider.ts): 115 tool definitions across 23 module files, declarative registry pattern; per-module tables last fully re-audited 28.09 and kept current through v1.9.24. Version history:CHANGELOG_v5.md(active) Β·docs/history/(older volumes).
| Category | Count | Default State | Status |
|---|---|---|---|
| File System | 25 | β Enabled | Active |
| Code Refactoring | 1 | β Enabled | Active |
| Web Research | 3 | β Enabled | Active |
| Browser Automation | 5 | β Disabled | Active |
| Git & GitHub | 15 | β Disabled | Active |
| Database | 1 | β Disabled | Active |
| Background Commands | 3 | β Disabled | Active |
| Execution | 5 | β Mixed (JS/Python: enabled) | Active |
| Utilities | 0 live tools in this section (utilityTools.ts removed in the 23.09 cleanup; re-audit 28.09 verified every row below dead β see its β οΈ note) | β Utility toggle | Active |
| Image Processing | 4 | β Enabled | Active |
| Vector RAG | 7 | β Enabled | Active |
| UI Generation | 3 | β Enabled | Active |
| Context Management | 22 (12 core + 9 session-index/project-registry + 1 composite resume restore_session_context, 25.09) | β Enabled | Active |
| Text Processing | 3 | β Enabled | Active |
| Backup & Restore | 6 (incl. restore_from_bak β added by the 28.09 re-audit) | β Utility toggle | Active |
| Data Visualization | 1 | β Utility toggle | Active |
| Document Parsing | 1 | β Enabled | Active |
| HTTP Client | 3 | β Disabled | Active |
| Task Planning | 4 (incl. remove_plan, added by the PLAN-REMOVAL arc, 05.10) | β Enabled | Active |
Note: All tool categories are fully registered in
toolsProvider.tsusing the declarative registry pattern (v1.8.2+). The former gateway-tools file has been removed from the codebase (v1.9.10 session, 24.08) β direct SDK registration is the sole pattern and handles grammar parser compatibility via schema minification.
line_operations folded in from Text Processing, 23.09 Q6; + apply_patch, 07.11)| Tool | Description |
|---|---|
list_directory | List files and directories with optional depth control; supports recursive traversal |
read_file | Read file content with auto-chunking for large files; binary detection prevents corrupt output Β· Budget-Guard (05.11): when the projected context usage would cross the advisory threshold (budgetGuardAdvisoryThresholdPct, default 80 % of the limit), a self-describing budget advisory is returned INSTEAD of the full dump (with controlled re-read hints: small read_file_chunked / ripgrep / pattern_scan); OFF by default β legacy behavior byte-identical |
read_file_chunked | Read files in structured chunks returning start/end indices for streaming control |
save_file | Async atomic write operations via shared atomicWrite utility (src/utils/atomicWrite.ts) β randomized temp filenames prevent collisions, crash-resilient (original intact if interrupted); parent directory auto-creation; batch save support |
| Tool | Description |
|---|---|
replace_text_in_file | Replace text globally or per-occurrence with async atomic write + backup; line-ending preservation, binary protection, crash-resilient temp-file pattern |
insert_at_line | Insert content at specific 1-indexed line number; CRLF/LF detection preserves Windows line endings; async atomic write via shared utility |
append_file | Append text to file end (or create if missing); combined size limit enforcement (existing + new β€ 10MB); async atomic write with crash resilience |
delete_lines_in_file | Delete single or range of lines; default backup=true for irreversible operations; async atomic write via shared utility |
line_operations | Insert/delete/reorder lines using awk-like operations without shell dependencies; atomic writes safety + Three-layer guardrail system (v1.7.0+) (pattern matching, verification, bounds validation) + MD5 post-write integrity verify β folded in from textProcessingTools.ts 23.09 (Q6); full guardrails section at the end of this category |
| apply_patch | Apply unified-diff or binary byte-anchor patches fully in-process (no shell, no git CLI): EOL-preserving byte-accurate anchors with sequential multi-hunk re-anchoring; 64 MiB file / 1 MiB patch caps Β· added 07.11 |
| Tool | Description |
|---|---|
make_directory | Create directory with recursive parent creation; idempotent (succeeds if exists) |
move_file | Move/rename files or directories using async atomic rename with cross-filesystem copy+delete fallback |
copy_file | Copy file to new location with async atomic write and parent directory auto-creation |
delete_files_by_pattern | Delete multiple files in the current directory matching a regex pattern |
All file-modifying tools now use the shared atomicWrite utility (src/utils/atomicWrite.ts) for crash-resilient writes.
All 9 modules converted from sync writes to async atomic pattern:
| Module | Tools | Pattern |
|---|---|---|
lineOperations.ts β REMOVED 23.09 NEXT-REV | delete_lines [deleted]; line_operations already lived in textProcessingTools.ts (prior attribution here was incorrect) | async β atomicWrite |
refactorCodeTools.ts | rename_identifier, move_function, extract_function, unused_import_cleanup | async β atomicWrite + rollback-on-failure |
utilityTools.ts | ~25 tools (backup, chart, etc.) | All async β atomicWrite |
dataVisualizationTools.ts | generate_chart | async β atomicWriteBinaryFile |
imageProcessingTools.ts | attachment temp-file materialization (resolveAttachmentFile) | async β atomicWriteBinaryFile |
markdownPreviewTools.ts | markdown_preview HTML save | async β atomicWrite |
imageProcessingTools.ts | screenshot_desktop PNG/JPEG save | external platform process writes the file directly β no Node-side write |
uiGenerationTools.ts | UI component saves | async β atomicWrite |
recodeEngine.ts (recodeTool/) | AST transformation output | async β atomicWrite + rollback-on-failure |
Note: Zero
writeFileSync/renameSynccalls remain insrc/tools/. All file operations use asyncfs.promiseswith crash-resilient atomic write pattern. |delete_path| Delete file or recursively delete directory with proper error handling | |change_directory| Set working directory for all subsequent file operations; validates path exists and is a directory |
| Tool | Description |
|---|---|
find_files | Recursive filename search with async optimization and configurable depth limit (default: 5) |
fuzzy_find_local_files | Levenshtein-based fuzzy name matching with 60s caching; excludes large directories automatically |
get_file_metadata | Retrieve size, creation/modification/access timestamps via fs.stat(); for files also reports line-ending style (eol=crlf/lf/mixed) and BOM presence β check before editing to avoid EOL/encoding mismatches |
analyze_project | Project-wide analysis: TypeScript diagnostics, circular dependency detection, ESLint, config optimization, import structure (configurable max-imports warning) |
file_diff | Compare two files and return a unified diff with +/β markers and line numbers |
directory_tree | Visualize directory structure in tree format; supports max depth, optional file sizes, automatic exclusion of large directories |
ripgrep | Recursive content search (Rust-regex or literal) across files β standalone tool, 14.09 TOOL SWAP (owner directive): replaces the removed grep_files. The ENTIRE scan (file walk + pattern match) runs natively inside ONE worker-isolated ripgrep process (src/utils/ripgrepEngine.ts) off the host thread; a single wall-clock watchdog at 3 s (, owner directive) terminates wedged workers β + partial-coverage hint returned, plugin host never freezes (13.09 main-thread wedge class dead by construction). Parameters: (Rust regex by default; an invalid pattern auto-retries ONCE as fixed strings, reported via ), (directory , default CWD β relative paths resolve against the working dir), (/), ( β legacy contract; set for exact case), (positive filter glob β when given, the default exclusions are NOT applied), (always appended ON TOP of the defaults), (1ββ; omitted = unbounded). Default directory exclusions (exactly 12: node_modules/.git/dist/build/.next/.nuxt//.cache/vendor/.vscode/.idea/.vs) apply only when no is given. () β long scans settle at the 3 s watchdog with an aborted hint rather than truncating results; matched lines are shaped by the engine default ( chars + ellipsis, aligned to the pattern_scan contract β F2, 18.09). Host abort signal forwarded ( forensics on pre-abort); spawn failures surface as typed errors, never silent-empty. No AST mode (dropped with grep_files); -style case-insensitive matching is the default |
REV-24 (28.08, v1.9.10): Prose alternations with a bare
&(e.g."Backup & Restore|Git & GitHub") now correctly stay in regex mode β&is not a JS regex metacharacter and no longer false-positives the code-signature heuristic. Genuine code-signature patterns are still auto-escaped to literal only when an unescaped*,+or?pairs with a signature indicator; the response then carriespatternMode:"auto_escaped"with a hint string explaining why (no more silent 0-match fallback).
fileSystemTools.ts (folded in from textProcessingTools.ts, 23.09 Q6)Resolved recurring issues where LLMs inserted content at wrong lines due to stale line numbers. Three-layer defense-in-depth:
Find insertion point by searching file content instead of trusting line numbers β works regardless of current position.
| Parameter | Type | Required | Description |
|---|---|---|---|
insert_after_pattern | string | No | Line containing this text β insert AFTER it (max 500 chars) |
insert_before_pattern | string | No | Line containing this text β insert BEFORE it (max 500 chars) |
Example:
Verify expected text exists at target_line before proceeding β blocks operation with error + actual context on mismatch.
| Parameter | Type | Required | Description |
|---|---|---|---|
verify_before_insert | string | No | Content expected at target_line; if mismatch β blocked (max 200 chars) |
Example:
target_line outside valid range (1 to file length + 1)\n into individual array elements (fixed bug where \n became literal characters on single line)replace_text_in_file insteadMD5 hash verification ensures file content was written correctly. After writing content, the tool:
crypto.createHash('md5'))success: false with error showing both hashesTest Results: 9/9 test scenarios passed β zero regressions in existing delete/move operations.
Requires "π§ AST Code Refactoring Tools" toggle in settings or God Mode.
refactor_code)Leverages Babel's Abstract Syntax Tree (AST) parser for safe, syntax-aware code transformations. Replaces fragile line-based string manipulation with proper node traversal and regeneration. Supports TypeScript out-of-the-box.
| Operation | Description |
|---|---|
rename_identifier | Globally rename variables, functions, or class names across a file using AST binding analysis |
move_function | Extract functions (including Arrow Functions & Class Methods) to another file with proper syntax preservation |
extract_function | Pull selected code blocks into new standalone functions via Babel AST parsing |
unused_import_cleanup | Detect and remove dead imports/specifiers using static analysis; TypeScript-aware (import type) |
The src/tools/recodeTool/ module implements a pluggable rule engine for advanced AST-based code analysis. Rules are applied sequentially with dry-run diff output and backup/rollback support.
| Rule File | Purpose | Status |
|---|---|---|
unusedImports.ts | Identifies unused imports via cross-reference analysis against usage patterns | β Implemented (Tier 1) β the only live rule as of v1.9.12 rev 23 |
ποΈ Removed 01.09.2026: The former rules
deadCodeDetection.ts,modulePathNormalization.ts,typeInference.tsandasyncModernizer.ts(documented in v1.9.8-era entries below) were never wired into anyrefactor_codeoperation β removed as audited Tier-1 dead code; see the CHANGELOG_v2.md entry [01.09.2026 ~18:30].
1. Rename Identifiers
2. Move Functions Between Files
3. Extract Code Block into New Function
4. Clean Up Unused Imports
| Tool | Description |
|---|---|
web_search | Multi-engine search (DDG, Google, Bing) with automatic fallback chain configuration |
wikipedia_search | Search Wikipedia summaries supporting multiple languages; returns concise overviews |
fetch_web_content | Clean text extraction from URLs removing ads/navigation; supports custom headers and timeouts |
| Tool | Description |
|---|---|
browser_open_page | Navigate Puppeteer headless browser to URL with optional selector wait and screenshot capture |
browser_session_control | Manage persistent browser session lifecycle including connection state and inactivity timers |
browser_session_close | Gracefully close browser session preventing orphaned Chromium processes |
preview_html | Render raw HTML or existing .html file in default system browser via OS shell command |
open_file | Open files/URLs in system default application (Windows start, macOS open, Linux xdg-open) |
| Tool | Description |
|---|---|
git_status | Repository status: staged/unstaged files, branch info, ahead/behind counts vs remote |
git_diff | Changes between commits/branches/work-tree with stat summary and name-only options |
git_commit | Commit staged changes; supports --amend for modifying last commit and -a for auto-staging |
git_log | Ordered commit history with max-count, date range, author filtering and custom format output |
git_add | Stage files (individual, directory, or all) returning list of staged items with status |
git_checkout | Switch branches, create new (-b), checkout remote tracking; handles merge conflicts gracefully |
| Tool | Description |
|---|---|
git_stash | Manage uncommitted changes: save, pop, drop, and list stashes via native Git CLI fallback (isomorphic-git does not support stash) |
git_blame | Per-line commit history showing author, timestamp, hash; path validation prevents traversal attacks |
| Tool | Description |
|---|---|
gh_create_issue | Create repository issues supporting title, body, labels, assignees, milestones |
gh_list_issues | List issues filtered by state (open/closed), labels, assignees with pagination support |
gh_view_comments | Retrieve issue/PR comment threads with author, timestamp, body, and reaction data |
gh_create_pr | Create PRs from current branch with draft status, reviewers, and label assignment |
gh_list_prs | List pull requests filtered by state, author, base branch for lifecycle tracking |
gh_view_pr_diff | Fetch PR diff/patch showing added/removed lines without requiring local checkout |
gh_push | Push commits to remote via gh CLI with automatic auth and force push option support |
| Tool | Description |
|---|---|
query_database | Read-only SQLite queries with SQL injection prevention; parameterized binding for safe input handling |
| Tool | Description |
|---|---|
run_background_command | Start long-running process continuing independently without blocking the event loop |
check_background_command | Monitor status, stdout, stderr of running/completed background processes with exit codes |
cancel_background_command | Terminate running background command gracefully by PID or session reference |
| Tool | Description |
|---|---|
run_javascript | Execute JS in isolated VM context; blocks eval, require, child_process with 5s timeout default |
run_python | Execute Python in controlled environment; blocks os/subprocess/sys imports with 10s timeout default |
| Tool | Description |
|---|---|
execute_command | Run shell commands with multi-layer sanitization: dangerous pattern blocking and pipe limits |
run_in_terminal | Launch OS-native terminal window (cmd/PowerShell/zsh/bash) with env vars and visibility options |
run_tests | Auto-detect test framework from package.json scripts; supports Jest, Mocha, Vitest runners |
β οΈ DEAD-STATUS NOTE (verified against
src/tools/+toolsProvider.ts, 28.09): none of the tools in this former ~29-row Utilities section is registered anywhere in current code β zero hits per name insrc/tools/*.tsand no registry entry for any of them (the old host moduleutilityTools.tswas removed in the 23.09 cleanup, after the last full audit on 28.08). Of its former rows, FIVE memory tools are LIVE β but registered under Context Management (src/tools/contextManagementTools.ts):save_memory,get_memory,delete_memory,save_session_summary,get_session_summary. Everything else listed below is DEAD (names retained for traceability; locale entries may still reference some of them, e.g.findLMStudioHomeβ see the header gap note). The residualpackageManageconfig toggle exists inconfig.tsbut gates NO registered tool (stale config residue).Former rows: Memory & Context β , , , , , Β· System & Environment β , , , , Β· Clipboard & Notifications β , , Β· File & Data Utilities β , , , , , , , , , , .
| Tool | Description |
|---|---|
image_to_text | Tesseract.js OCR extracting text with confidence score, language detection, bounding boxes (50MB max) |
describe_image | Get image metadata: dimensions, format, size, timestamps for PNG/JPG/BMP/GIF/WebP/TIFF |
screenshot_desktop | Cross-platform desktop capture via PowerShell (.NET GDI+), macOS screencapture, or ImageMagick import |
compare_images | Byte-level similarity comparison with dimension checking; pixel-level requires sharp/jimp library |
| Tool | Description |
|---|---|
rag_index_pdf | Extract PDF text via pdf-parse, chunk by page boundary with page_number metadata; bounded ~300 words/chunk for OOM safety; traceable results per page number |
rag_index_docx | Extract DOCX raw text via mammoth library, word-bounded chunks (default 300 words, 50 overlap); same embedding pipeline as PDF |
rag_index_xlsx | Extract all sheets as row arrays via xlsx package; chunks by rows (default 100), optional sheet-name prefix for traceability; includeSheetNames parameter controls prefix behavior |
| Tool | Description |
|---|---|
rag_index_files | Index files for semantic search supporting TS/JS/MD/JSON/YAML/text formats with batch processing |
rag_query_vector | Cosine similarity query returning top-k results (default 5, max 20) with chunk content and scores |
rag_clear_index | Clear entire vector index requiring confirm=true for safety; useful before full reindexing |
rag_web_content | RAG pipeline fetching URL content then extracting only text chunks relevant to query |
| Tool | Description |
|---|---|
generate_ui_component | Create interactive HTML/CSS/JS components (buttons, forms, tables) from user descriptions |
render_and_preview_ui | Render components in browser with live editing and hot reload for rapid prototyping |
extract_ui_data | Extract structured data from pages using CSS selectors/XPath returning tabular output |
restore_session_context, 25.09; re-counted in the 28.09 full re-audit: the Session-Index/Project-Registry sub-table lists 9 rows, not 8; +1 read-only ID-first recall tool memory_recall added 03.11)Note (re-audit 28.09): The five memory tools (save_session_summary, get_session_summary, save_memory, get_memory, delete_memory) are registered EXACTLY ONCE β in contextManagementTools.ts under the contextManagement key β and documented here; their former Utilities-section rows were stale duplicates (see Β§Utilities dead-status note).
| Tool | Description |
|---|---|
auto_summarize_context | Analyze session patterns, tool usage frequency, config changes; saves to persistent memory with default 'global' scope (v1.9.1+) |
get_context_memory | Retrieve past entries filtered by type (decision/pattern/config/error/summary) with deterministic heuristic scoring applied β recent + frequently accessed entries surface first (v1.9.1+) |
search_context | Fuzzy text search across titles, content bodies, tags for efficient retrieval and analysis; expired session entries pruned before search (24h TTL, v1.9.1+) |
context_summary | Statistical overview: total entries, type breakdowns, recent activity counts for auditing |
delete_context_entry | Remove specific context entry by unique ID without clearing entire history |
clear_context_memory | Clear all persistent memory entries (β οΈ irreversible; requires confirm=true) |
track_important_event | Manually record events/decisions/milestones with custom tags for categorized retrieval |
save_session_summary | Save structured summary (accomplishments, pending tasks) with zlib compression bypassing 10k SDK limit |
get_session_summary | Retrieve latest session summary with backward-compatible legacy fallback parser for pre-v1.5.15 data |
save_memory | Persist facts to .ai_toolbox_memory.msgpack MessagePack binary for cross-session continuity |
get_memory |
Documented 28.08 β present in contextManagementTools.ts since before the last doc sync.
| Tool | Description |
|---|---|
list_sessions | Browse all saved session summaries with pagination and limit controls |
search_sessions | Keyword search across stored session summaries (newest first) |
clear_session_index | Remove all session index entries (lightweight index only β summaries untouched; requires confirm=true) |
manage_projects | Manage the cross-project registry β mutations AND reads: register / unregister / update / clear_all + info / list / search (single tool for ALL registry operations; destructive actions require confirm=true) |
register_project | [DEPRECATED alias of manage_projects(action="register")] Register or update a project in the cross-project registry by name + working-dir path |
get_project_info | [DEPRECATED alias of manage_projects(action="info")] Retrieve details of one registered project by its working directory path |
list_projects | [DEPRECATED alias of manage_projects(action="list")] List all registered projects with paths, last-accessed time and session counts |
search_projects | [DEPRECATED alias of manage_projects(action="search")] Search registered projects by name or path substring (kept for one release cycle, 12.09) |
switch_context | Switch context storage to another project's working directory (memory/session lookup target) |
Memory System Enhancements (v1.9.1):
global/project/session scope for future isolation filtering(Recency Γ 0.7) + (Frequency Γ 0.3) ensures intelligent orderingCross-Project Registry (v1.9.8+):
search_projects / get_project_info now call _syncFromSessionMemory() before lookup β auto-registers projects discovered from session memory decisions (.ai_toolbox_memory.msgpack) so the registry never returns stale empty results. Lazy pattern: no startup overhead.manage_projects(action="register") is the primary explicit registration method (requires confirmed path; register_project remains a deprecated alias, 12.09). Silent auto-registration was removed in v1.9.8; Step 0.7 keyword detection in surfaces registered projects on mention (confirm-first: banner only β the one-shot CWD switch happens exclusively after an explicit YES/JA reply).| Tool | Description |
|---|---|
restore_session_context | Composite read-only resume bootstrap ("read session mem", single call): latest session summary (RAM first, then file β same priority as get_session_summary) Β· newest persisted plan with per-step status (get_plan selection semantics) Β· all explicit memory facts Β· context entries in full (auto-checkpoint noise collapsed to ONE line: count + date range + peak usage %; expired session-scoped entries skipped locally WITHOUT pruning the store, mirroring CSM read-time TTL) Β· recent sessions index top-8. Output is a Markdown dossier with per-family presence/staleness header (STALE > 3 days flagged), machine counts block, hard max_chars budget (default 16000, marker + omitted-section list when truncated), self-describing absent/legacy sections on fresh or corrupt stores; no writes anywhere (store files asserted byte-identical pre/post in tests). Params: include_sessions_index (default true), max_chars (1000β50000) |
| Tool | Description |
|---|---|
text_transform | Regex substitution with capture groups ($1, $2), line ranges, global/case-insensitive modes; safer than shell sed |
text_extract | Structured data extraction from delimited text (CSV/TSV/custom) with configurable zero-based field indices |
markdown_table_gen | Generate Markdown tables from object arrays with headers, alignment, truncation, and customizable ellipsis |
restore_from_bak, added by the 28.09 re-audit; all registered under the utility config key)| Tool | Description |
|---|---|
create_backup | Compressed ZIP backup of entire working directory stored in .ai_toolbox_backups/; requires confirm=true |
list_backups | List backups sorted by date newest-first with filename, path, size bytes, and creation timestamp |
restore_backup | Restore full working directory from archive (β οΈ overwrites all files; requires confirm=true) |
delete_backup | Remove specific backup file (β οΈ irreversible; validates existence before deletion) |
cleanup_backups | Recursively list and optionally delete .bak edit backups anywhere in the working-dir tree (21.10 fix for missed nested backups; never descends into node_modules / .git / plugin-state dirs; dry-run by default; confirm required to delete) β registered under the utility toggle key (cleanupBackupsTool.ts) |
restore_from_bak | Restore one file from its .bak backup created by a file-modifying tool (named for the original file, without the .bak suffix) β same utility key (restoreFromBak.ts, 28.09 re-audit: previously undocumented here) |
Status: src/tools/gatewayTools.ts has been removed from the codebase (v1.9.10 session, 24.08) β no gateway tool definitions remain anywhere under src/. Direct SDK registration + schema minification is the active approach; this section documents the historical design only.
The direct SDK registration approach (all tools exposed directly to LLM) has proven more effective for usability. Grammar parser compatibility is now handled via schema minification (toolsSchemaMinifier.ts), which compresses descriptions and caps constraints without limiting tool count.
The gateway pattern was originally designed as follows:
explore_toolsDiscovers available tools and their categories without exposing all registered tools at once. Returns category names only to keep schema small.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Optional: Filter by specific category name (e.g., "fileSystem", "webSearch") |
Returns: { success: boolean, categories: string[], message?: string }
execute_gateway_toolExecutes any registered tool by name with built-in validation and error handling. Delegates to the existing ToolRegistry for execution.
| Parameter | Type | Required | Description |
|---|---|---|---|
toolName | string | Yes | Name of the tool to execute (e.g., "read_file", "web_search") |
arguments | Record<string, unknown> | Yes | Tool-specific arguments as key-value pairs |
Returns: Tool execution result or error message
Why Gateway Was Designed: Sending all registered tools directly to llama.cpp's grammar parser caused failed to parse grammar errors due to EBNF recursion limits. The gateway pattern was intended to reduce initial schema payload while maintaining full functionality on-demand via delegation.
utility toggle; 3 further live sibling tools on this key documented below, re-audit 28.09)| Tool | Description |
|---|---|
generate_chart | Create line/bar/pie/scatter/area charts outputting SVG/PNG with customizable colors, labels, legends. Registered via dataVisualizationTools.ts in the utility tools registry. |
utility config key (previously undocumented; re-audit 28.09)| Tool | Description |
|---|---|
list_available_bak_backups | Recursively scan under the working directory for all .bak backups created by file-modifying tools (21.10 fix; paths are working-dir-relative, root-level keeps the bare-filename form) β pairs with restore_from_bak (restoreFromBak.ts) |
markdown_preview | Render a Markdown file to HTML and open it in the default browser (markdownPreviewTools.ts) |
get_repeat_tool_advice | Return current repeat-tool reminder state/nudges for one tool (or a summary across tracked calls) β Loop-Hygiene B advisory surface (repeatToolReminderTools.ts, rev-3x pile, 24.09 arc) |
| Tool | Description |
|---|---|
read_document | Read PDF (pdf-parse), DOCX (mammoth), or TXT files; automatic binary detection prevents corrupt output Β· Budget-Guard (05.11): same M1 pre-read advisory gate as read_file when the projected context budget would be crossed |
| Tool | Description |
|---|---|
http_request | Generic GET/POST/PUT/DELETE/PATCH client with retry logic, timeout config, multipart upload support |
http_get_json | GET requests expecting JSON response with automatic parsing and optional schema validation |
http_post_json | POST requests with JSON payload, content-type auto-handling, auth token support, status code return |
remove_plan, PLAN-REMOVAL arc, 05.10)Requires taskPlanning toggle in settings or God Mode.
Structured multi-step workflow management tools for creating, tracking, and updating execution plans. Tools persist plan data to .ai_toolbox_plans.json using atomic writes with Zod schema validation.
| Tool | Description |
|---|---|
create_plan | Create a new execution plan with goal and ordered steps (1-30 steps, 500 chars max each). Replaces any existing active plan. Returns planId, goal, and stepCount. |
get_plan | Return the active plan details including goal, all step statuses, completion percentage, elapsed time since creation, and timestamps. Returns null if no plan exists. |
update_plan_step | Update a single step's status according to state machine rules (pendingβin_progressβdone, anyβblocked, blockedβpending). Requires note when marking as blocked. Returns completion metrics including completedSteps, totalSteps, and allDone boolean β and auto-removes the plan from the working-state store at natural completion (every step done; blocked/partial plans are never auto-removed, test-pinned). |
remove_plan | Confirm-gated removal of a plan from the working-state store (PLAN-REMOVAL arc, 05.10): dry-run preview by default β set confirm=true to actually remove. Use for unfinished plans; naturally completed plans are already auto-removed at completion by update_plan_step. Terminal response carries full stats + goal as provenance (house rule: no archive layer). |
Example Workflow:
Gated on the updateCheckEnabled config key (default ON). The desktop-toast channel is additionally governed by notificationsEnabled (channel selection, spec A XOR): exactly ONE surface per session β toast when ON, single in-chat line when OFF.
Since 19.10 the plugin performs a quiet β€1/day update check (src/updateChecker.ts). Since the HUB .VERSION arc (owner GO 19.10) it reads the published hub .VERSION file (https://lmstudio.ai/crunch3r/ai-toolbox/files/.VERSION; strict v?x.y.z parse for raw bodies, noise-tolerant HTML-page extraction as fallback) β NOT GitHub releases/latest. State persists in <dataDir>/update-check.json (survives reinstalls); non-fatal by design.
| Tool | Description |
|---|---|
get_update_info | Read-only update-status surface for the LLM: installed version, whether a strictly-newer published version is known (24h-cached check), and the hub marketplace page URL (releaseUrl) when available β render it as a clickable Markdown link in chat. Never throws; zero NEW state writes (the TTL-stamped getUpdateStatus() read is quiet on fresh cache) |
dismiss_update_reminder | Record "not now" for an update-reminder version β <dataDir>/update-check.json dismissed[]; that version stays silent forever, strictly-newer releases still notify. State-only write; non-fatal by construction |
All categories toggleable in LM Studio settings panel. Most dangerous tools disabled by default requiring explicit opt-in through the UI. God Mode enables all categories instantly β use cautiously.
All tools implement multiple security layers:
validatePath()rm -rf, sudo)β οΈ Important: Most dangerous tools disabled by default requiring explicit user opt-in through settings panel. God Mode bypasses all category restrictions.
Doc sync 2026-09-28 (pattern_scan WALK-ABORT walk-phase abort + FULL per-module re-audit with count corrections β see header; version stamp now v1.9.18 / manifest revision 33) Β· reference updated 2026-09-08 (v1.9.17 / manifest rev 29 β Tool Gating Profile shipped: user-level toggle persistence in %USERPROFILE%\.ai_toolbox\tool_gating_profile.json (booleans only, sparse store; auto-capture of non-default toggles, sticky across new chats) Β· previous refresh 08.09 (v1.9.16 / manifest rev 28): version header sync after web_search fix (no tool surface change) Β· earlier refresh 2026-09-04 (v1.9.15 / manifest rev 27): header totals re-grounded against the live i18n locale reference (src/locales/en.ts: 129 registration entries, 127 distinct tool names). Prior sync: 2026-08-24 (v1.9.10): Web Research count 4β3 after duplicate rag_web_content removal (tool served by Vector RAG module since v1.9.10). Earlier baseline: 2026-08-17 (v1.9.8). FULL per-module re-audit completed same day (28.09): every count above re-verified against the toolsProvider.ts registry + per-module name: scans in src/tools/*.ts; outcomes recorded inline (header gap note, Β§Utilities superseded, Image Analysis section removed, Context Management 21β22, Backup & Restore 5β6). insert_at_line read-back drift detection documented with v1.8.8 hard fix. Graphify-Inspired Suite features (v1.9.5): Confidence-Tagged Results, Hub-Exclusion Clustering (83 tests), Project Auto-Detection, Context Tier Provenance, Cluster-Aware Tool Priority.
Five new architectural modules added in v1.9.5 following graphify repository analysis patterns:
src/types/confidenceTypes.ts)Typed confidence metadata attached to all tool execution outputs.
Three confidence levels for result reliability assessment:
Helper functions available for standardized confidence assignment:
src/utils/hubExclusionClustering.ts)Louvain community detection with hub-exclusion for architectural transparency.
Algorithm flow: Build dependency graph β Calculate degrees β Identify hubs (80th percentile) β Louvain clustering on non-hubs β Majority-vote hub reattachment.
Output includes modularity score, cluster density metrics, and hub identification β all running synchronously under 10ms for typical plugin graphs. 83 tests verify correctness across graph construction, hub identification at various percentiles, Louvain convergence, majority-vote reattachment, and edge cases.
Use cases: Architectural visualization, refactoring guidance (identify modules to refactor together), ContextGuard optimization (compress related clusters), tool priority ranking via centrality scoring.
src/projectAutoDetect.ts)Automatic project registration when cross-project registry searches return empty.
Confidence scoring signals: package.json (+0.4), src/ or lib/ (+0.3), .git (+0.1), build configs (+0.2). Name normalization handles hyphenβunderscore variants and scoped packages (@lmstudio/ai-toolbox). β οΈ DEPRECATED (v1.9.8+): initializeProjectDetection() no longer called from index.ts at startup. Registration requires explicitConfirmation=true via register_project tool. See src/index.ts comment: "NO AUTO-REGISTRATION ON STARTUP".
src/contextTiers.ts)Typed provenance markers for tier-scoped context replacement.
Origin types: _origin: 'ast' | 'semantic' distinguishes raw file content from derived AI insights. replaceTier() replaces only changed tiers while preserving unchanged ones β follows graphify's incremental update pattern to prevent silent overwrites of unchanged nodes.
src/tools/toolPriority.ts)Five-tier priority ranking with hub-exclusion clustering integration.
Tiers: CRITICAL (1, file system tools), HIGH (2, web research/execution/git), STANDARD (3, browser/image/RAG), OPTIONAL (4, context management), BACKGROUND (5, backup/cleanup). Centrality scoring computed from module degree Γ hub bonus β used for intelligent tool filtering when grammar parser limits require pruning.
analyze_image tool exists in code, and there is no imageAnalysis config key; (they had been recorded in the 28.09 header gap note). The four LIVE image tools (, , , ) are documented under Image Processing above.Current state: v1.9.24 Β· manifest rev 0 Β· canon 84 suites / 1262 tests Β· 116 tools across the categories (re-counted 07.11:
apply_patchshipped) in the Overview below (two names serve two categories:read_document,rag_web_content). Audited against live code (src/tools/*.ts+toolsProvider.ts): 115 tool definitions across 23 module files, declarative registry pattern; per-module tables last fully re-audited 28.09 and kept current through v1.9.24. Version history:CHANGELOG_v5.md(active) Β·docs/history/(older volumes).
| Category | Count | Default State | Status |
|---|---|---|---|
| File System | 25 | β Enabled | Active |
| Code Refactoring | 1 | β Enabled | Active |
| Web Research | 3 | β Enabled | Active |
| Browser Automation | 5 | β Disabled | Active |
| Git & GitHub | 15 | β Disabled | Active |
| Database | 1 | β Disabled | Active |
| Background Commands | 3 | β Disabled | Active |
| Execution | 5 | β Mixed (JS/Python: enabled) | Active |
| Utilities | 0 live tools in this section (utilityTools.ts removed in the 23.09 cleanup; re-audit 28.09 verified every row below dead β see its β οΈ note) | β Utility toggle | Active |
| Image Processing | 4 | β Enabled | Active |
| Vector RAG | 7 | β Enabled | Active |
| UI Generation | 3 | β Enabled | Active |
| Context Management | 22 (12 core + 9 session-index/project-registry + 1 composite resume restore_session_context, 25.09) | β Enabled | Active |
| Text Processing | 3 | β Enabled | Active |
| Backup & Restore | 6 (incl. restore_from_bak β added by the 28.09 re-audit) | β Utility toggle | Active |
| Data Visualization | 1 | β Utility toggle | Active |
| Document Parsing | 1 | β Enabled | Active |
| HTTP Client | 3 | β Disabled | Active |
| Task Planning | 4 (incl. remove_plan, added by the PLAN-REMOVAL arc, 05.10) | β Enabled | Active |
Note: All tool categories are fully registered in
toolsProvider.tsusing the declarative registry pattern (v1.8.2+). The former gateway-tools file has been removed from the codebase (v1.9.10 session, 24.08) β direct SDK registration is the sole pattern and handles grammar parser compatibility via schema minification.
line_operations folded in from Text Processing, 23.09 Q6; + apply_patch, 07.11)| Tool | Description |
|---|---|
list_directory | List files and directories with optional depth control; supports recursive traversal |
read_file | Read file content with auto-chunking for large files; binary detection prevents corrupt output Β· Budget-Guard (05.11): when the projected context usage would cross the advisory threshold (budgetGuardAdvisoryThresholdPct, default 80 % of the limit), a self-describing budget advisory is returned INSTEAD of the full dump (with controlled re-read hints: small read_file_chunked / ripgrep / pattern_scan); OFF by default β legacy behavior byte-identical |
read_file_chunked | Read files in structured chunks returning start/end indices for streaming control |
save_file | Async atomic write operations via shared atomicWrite utility (src/utils/atomicWrite.ts) β randomized temp filenames prevent collisions, crash-resilient (original intact if interrupted); parent directory auto-creation; batch save support |
| Tool | Description |
|---|---|
replace_text_in_file | Replace text globally or per-occurrence with async atomic write + backup; line-ending preservation, binary protection, crash-resilient temp-file pattern |
insert_at_line | Insert content at specific 1-indexed line number; CRLF/LF detection preserves Windows line endings; async atomic write via shared utility |
append_file | Append text to file end (or create if missing); combined size limit enforcement (existing + new β€ 10MB); async atomic write with crash resilience |
delete_lines_in_file | Delete single or range of lines; default backup=true for irreversible operations; async atomic write via shared utility |
line_operations | Insert/delete/reorder lines using awk-like operations without shell dependencies; atomic writes safety + Three-layer guardrail system (v1.7.0+) (pattern matching, verification, bounds validation) + MD5 post-write integrity verify β folded in from textProcessingTools.ts 23.09 (Q6); full guardrails section at the end of this category |
| apply_patch | Apply unified-diff or binary byte-anchor patches fully in-process (no shell, no git CLI): EOL-preserving byte-accurate anchors with sequential multi-hunk re-anchoring; 64 MiB file / 1 MiB patch caps Β· added 07.11 |
| Tool | Description |
|---|---|
make_directory | Create directory with recursive parent creation; idempotent (succeeds if exists) |
move_file | Move/rename files or directories using async atomic rename with cross-filesystem copy+delete fallback |
copy_file | Copy file to new location with async atomic write and parent directory auto-creation |
delete_files_by_pattern | Delete multiple files in the current directory matching a regex pattern |
All file-modifying tools now use the shared atomicWrite utility (src/utils/atomicWrite.ts) for crash-resilient writes.
All 9 modules converted from sync writes to async atomic pattern:
| Module | Tools | Pattern |
|---|---|---|
lineOperations.ts β REMOVED 23.09 NEXT-REV | delete_lines [deleted]; line_operations already lived in textProcessingTools.ts (prior attribution here was incorrect) | async β atomicWrite |
refactorCodeTools.ts | rename_identifier, move_function, extract_function, unused_import_cleanup | async β atomicWrite + rollback-on-failure |
utilityTools.ts | ~25 tools (backup, chart, etc.) | All async β atomicWrite |
dataVisualizationTools.ts | generate_chart | async β atomicWriteBinaryFile |
imageProcessingTools.ts | attachment temp-file materialization (resolveAttachmentFile) | async β atomicWriteBinaryFile |
markdownPreviewTools.ts | markdown_preview HTML save | async β atomicWrite |
imageProcessingTools.ts | screenshot_desktop PNG/JPEG save | external platform process writes the file directly β no Node-side write |
uiGenerationTools.ts | UI component saves | async β atomicWrite |
recodeEngine.ts (recodeTool/) | AST transformation output | async β atomicWrite + rollback-on-failure |
Note: Zero
writeFileSync/renameSynccalls remain insrc/tools/. All file operations use asyncfs.promiseswith crash-resilient atomic write pattern. |delete_path| Delete file or recursively delete directory with proper error handling | |change_directory| Set working directory for all subsequent file operations; validates path exists and is a directory |
| Tool | Description |
|---|---|
find_files | Recursive filename search with async optimization and configurable depth limit (default: 5) |
fuzzy_find_local_files | Levenshtein-based fuzzy name matching with 60s caching; excludes large directories automatically |
get_file_metadata | Retrieve size, creation/modification/access timestamps via fs.stat(); for files also reports line-ending style (eol=crlf/lf/mixed) and BOM presence β check before editing to avoid EOL/encoding mismatches |
analyze_project | Project-wide analysis: TypeScript diagnostics, circular dependency detection, ESLint, config optimization, import structure (configurable max-imports warning) |
file_diff | Compare two files and return a unified diff with +/β markers and line numbers |
directory_tree | Visualize directory structure in tree format; supports max depth, optional file sizes, automatic exclusion of large directories |
ripgrep | Recursive content search (Rust-regex or literal) across files β standalone tool, 14.09 TOOL SWAP (owner directive): replaces the removed grep_files. The ENTIRE scan (file walk + pattern match) runs natively inside ONE worker-isolated ripgrep process (src/utils/ripgrepEngine.ts) off the host thread; a single wall-clock watchdog at 3 s (, owner directive) terminates wedged workers β + partial-coverage hint returned, plugin host never freezes (13.09 main-thread wedge class dead by construction). Parameters: (Rust regex by default; an invalid pattern auto-retries ONCE as fixed strings, reported via ), (directory , default CWD β relative paths resolve against the working dir), (/), ( β legacy contract; set for exact case), (positive filter glob β when given, the default exclusions are NOT applied), (always appended ON TOP of the defaults), (1ββ; omitted = unbounded). Default directory exclusions (exactly 12: node_modules/.git/dist/build/.next/.nuxt//.cache/vendor/.vscode/.idea/.vs) apply only when no is given. () β long scans settle at the 3 s watchdog with an aborted hint rather than truncating results; matched lines are shaped by the engine default ( chars + ellipsis, aligned to the pattern_scan contract β F2, 18.09). Host abort signal forwarded ( forensics on pre-abort); spawn failures surface as typed errors, never silent-empty. No AST mode (dropped with grep_files); -style case-insensitive matching is the default |
REV-24 (28.08, v1.9.10): Prose alternations with a bare
&(e.g."Backup & Restore|Git & GitHub") now correctly stay in regex mode β&is not a JS regex metacharacter and no longer false-positives the code-signature heuristic. Genuine code-signature patterns are still auto-escaped to literal only when an unescaped*,+or?pairs with a signature indicator; the response then carriespatternMode:"auto_escaped"with a hint string explaining why (no more silent 0-match fallback).
fileSystemTools.ts (folded in from textProcessingTools.ts, 23.09 Q6)Resolved recurring issues where LLMs inserted content at wrong lines due to stale line numbers. Three-layer defense-in-depth:
Find insertion point by searching file content instead of trusting line numbers β works regardless of current position.
| Parameter | Type | Required | Description |
|---|---|---|---|
insert_after_pattern | string | No | Line containing this text β insert AFTER it (max 500 chars) |
insert_before_pattern | string | No | Line containing this text β insert BEFORE it (max 500 chars) |
Example:
Verify expected text exists at target_line before proceeding β blocks operation with error + actual context on mismatch.
| Parameter | Type | Required | Description |
|---|---|---|---|
verify_before_insert | string | No | Content expected at target_line; if mismatch β blocked (max 200 chars) |
Example:
target_line outside valid range (1 to file length + 1)\n into individual array elements (fixed bug where \n became literal characters on single line)replace_text_in_file insteadMD5 hash verification ensures file content was written correctly. After writing content, the tool:
crypto.createHash('md5'))success: false with error showing both hashesTest Results: 9/9 test scenarios passed β zero regressions in existing delete/move operations.
Requires "π§ AST Code Refactoring Tools" toggle in settings or God Mode.
refactor_code)Leverages Babel's Abstract Syntax Tree (AST) parser for safe, syntax-aware code transformations. Replaces fragile line-based string manipulation with proper node traversal and regeneration. Supports TypeScript out-of-the-box.
| Operation | Description |
|---|---|
rename_identifier | Globally rename variables, functions, or class names across a file using AST binding analysis |
move_function | Extract functions (including Arrow Functions & Class Methods) to another file with proper syntax preservation |
extract_function | Pull selected code blocks into new standalone functions via Babel AST parsing |
unused_import_cleanup | Detect and remove dead imports/specifiers using static analysis; TypeScript-aware (import type) |
The src/tools/recodeTool/ module implements a pluggable rule engine for advanced AST-based code analysis. Rules are applied sequentially with dry-run diff output and backup/rollback support.
| Rule File | Purpose | Status |
|---|---|---|
unusedImports.ts | Identifies unused imports via cross-reference analysis against usage patterns | β Implemented (Tier 1) β the only live rule as of v1.9.12 rev 23 |
ποΈ Removed 01.09.2026: The former rules
deadCodeDetection.ts,modulePathNormalization.ts,typeInference.tsandasyncModernizer.ts(documented in v1.9.8-era entries below) were never wired into anyrefactor_codeoperation β removed as audited Tier-1 dead code; see the CHANGELOG_v2.md entry [01.09.2026 ~18:30].
1. Rename Identifiers
2. Move Functions Between Files
3. Extract Code Block into New Function
4. Clean Up Unused Imports
| Tool | Description |
|---|---|
web_search | Multi-engine search (DDG, Google, Bing) with automatic fallback chain configuration |
wikipedia_search | Search Wikipedia summaries supporting multiple languages; returns concise overviews |
fetch_web_content | Clean text extraction from URLs removing ads/navigation; supports custom headers and timeouts |
| Tool | Description |
|---|---|
browser_open_page | Navigate Puppeteer headless browser to URL with optional selector wait and screenshot capture |
browser_session_control | Manage persistent browser session lifecycle including connection state and inactivity timers |
browser_session_close | Gracefully close browser session preventing orphaned Chromium processes |
preview_html | Render raw HTML or existing .html file in default system browser via OS shell command |
open_file | Open files/URLs in system default application (Windows start, macOS open, Linux xdg-open) |
| Tool | Description |
|---|---|
git_status | Repository status: staged/unstaged files, branch info, ahead/behind counts vs remote |
git_diff | Changes between commits/branches/work-tree with stat summary and name-only options |
git_commit | Commit staged changes; supports --amend for modifying last commit and -a for auto-staging |
git_log | Ordered commit history with max-count, date range, author filtering and custom format output |
git_add | Stage files (individual, directory, or all) returning list of staged items with status |
git_checkout | Switch branches, create new (-b), checkout remote tracking; handles merge conflicts gracefully |
| Tool | Description |
|---|---|
git_stash | Manage uncommitted changes: save, pop, drop, and list stashes via native Git CLI fallback (isomorphic-git does not support stash) |
git_blame | Per-line commit history showing author, timestamp, hash; path validation prevents traversal attacks |
| Tool | Description |
|---|---|
gh_create_issue | Create repository issues supporting title, body, labels, assignees, milestones |
gh_list_issues | List issues filtered by state (open/closed), labels, assignees with pagination support |
gh_view_comments | Retrieve issue/PR comment threads with author, timestamp, body, and reaction data |
gh_create_pr | Create PRs from current branch with draft status, reviewers, and label assignment |
gh_list_prs | List pull requests filtered by state, author, base branch for lifecycle tracking |
gh_view_pr_diff | Fetch PR diff/patch showing added/removed lines without requiring local checkout |
gh_push | Push commits to remote via gh CLI with automatic auth and force push option support |
| Tool | Description |
|---|---|
query_database | Read-only SQLite queries with SQL injection prevention; parameterized binding for safe input handling |
| Tool | Description |
|---|---|
run_background_command | Start long-running process continuing independently without blocking the event loop |
check_background_command | Monitor status, stdout, stderr of running/completed background processes with exit codes |
cancel_background_command | Terminate running background command gracefully by PID or session reference |
| Tool | Description |
|---|---|
run_javascript | Execute JS in isolated VM context; blocks eval, require, child_process with 5s timeout default |
run_python | Execute Python in controlled environment; blocks os/subprocess/sys imports with 10s timeout default |
| Tool | Description |
|---|---|
execute_command | Run shell commands with multi-layer sanitization: dangerous pattern blocking and pipe limits |
run_in_terminal | Launch OS-native terminal window (cmd/PowerShell/zsh/bash) with env vars and visibility options |
run_tests | Auto-detect test framework from package.json scripts; supports Jest, Mocha, Vitest runners |
β οΈ DEAD-STATUS NOTE (verified against
src/tools/+toolsProvider.ts, 28.09): none of the tools in this former ~29-row Utilities section is registered anywhere in current code β zero hits per name insrc/tools/*.tsand no registry entry for any of them (the old host moduleutilityTools.tswas removed in the 23.09 cleanup, after the last full audit on 28.08). Of its former rows, FIVE memory tools are LIVE β but registered under Context Management (src/tools/contextManagementTools.ts):save_memory,get_memory,delete_memory,save_session_summary,get_session_summary. Everything else listed below is DEAD (names retained for traceability; locale entries may still reference some of them, e.g.findLMStudioHomeβ see the header gap note). The residualpackageManageconfig toggle exists inconfig.tsbut gates NO registered tool (stale config residue).Former rows: Memory & Context β , , , , , Β· System & Environment β , , , , Β· Clipboard & Notifications β , , Β· File & Data Utilities β , , , , , , , , , , .
| Tool | Description |
|---|---|
image_to_text | Tesseract.js OCR extracting text with confidence score, language detection, bounding boxes (50MB max) |
describe_image | Get image metadata: dimensions, format, size, timestamps for PNG/JPG/BMP/GIF/WebP/TIFF |
screenshot_desktop | Cross-platform desktop capture via PowerShell (.NET GDI+), macOS screencapture, or ImageMagick import |
compare_images | Byte-level similarity comparison with dimension checking; pixel-level requires sharp/jimp library |
| Tool | Description |
|---|---|
rag_index_pdf | Extract PDF text via pdf-parse, chunk by page boundary with page_number metadata; bounded ~300 words/chunk for OOM safety; traceable results per page number |
rag_index_docx | Extract DOCX raw text via mammoth library, word-bounded chunks (default 300 words, 50 overlap); same embedding pipeline as PDF |
rag_index_xlsx | Extract all sheets as row arrays via xlsx package; chunks by rows (default 100), optional sheet-name prefix for traceability; includeSheetNames parameter controls prefix behavior |
| Tool | Description |
|---|---|
rag_index_files | Index files for semantic search supporting TS/JS/MD/JSON/YAML/text formats with batch processing |
rag_query_vector | Cosine similarity query returning top-k results (default 5, max 20) with chunk content and scores |
rag_clear_index | Clear entire vector index requiring confirm=true for safety; useful before full reindexing |
rag_web_content | RAG pipeline fetching URL content then extracting only text chunks relevant to query |
| Tool | Description |
|---|---|
generate_ui_component | Create interactive HTML/CSS/JS components (buttons, forms, tables) from user descriptions |
render_and_preview_ui | Render components in browser with live editing and hot reload for rapid prototyping |
extract_ui_data | Extract structured data from pages using CSS selectors/XPath returning tabular output |
restore_session_context, 25.09; re-counted in the 28.09 full re-audit: the Session-Index/Project-Registry sub-table lists 9 rows, not 8; +1 read-only ID-first recall tool memory_recall added 03.11)Note (re-audit 28.09): The five memory tools (save_session_summary, get_session_summary, save_memory, get_memory, delete_memory) are registered EXACTLY ONCE β in contextManagementTools.ts under the contextManagement key β and documented here; their former Utilities-section rows were stale duplicates (see Β§Utilities dead-status note).
| Tool | Description |
|---|---|
auto_summarize_context | Analyze session patterns, tool usage frequency, config changes; saves to persistent memory with default 'global' scope (v1.9.1+) |
get_context_memory | Retrieve past entries filtered by type (decision/pattern/config/error/summary) with deterministic heuristic scoring applied β recent + frequently accessed entries surface first (v1.9.1+) |
search_context | Fuzzy text search across titles, content bodies, tags for efficient retrieval and analysis; expired session entries pruned before search (24h TTL, v1.9.1+) |
context_summary | Statistical overview: total entries, type breakdowns, recent activity counts for auditing |
delete_context_entry | Remove specific context entry by unique ID without clearing entire history |
clear_context_memory | Clear all persistent memory entries (β οΈ irreversible; requires confirm=true) |
track_important_event | Manually record events/decisions/milestones with custom tags for categorized retrieval |
save_session_summary | Save structured summary (accomplishments, pending tasks) with zlib compression bypassing 10k SDK limit |
get_session_summary | Retrieve latest session summary with backward-compatible legacy fallback parser for pre-v1.5.15 data |
save_memory | Persist facts to .ai_toolbox_memory.msgpack MessagePack binary for cross-session continuity |
get_memory |
Documented 28.08 β present in contextManagementTools.ts since before the last doc sync.
| Tool | Description |
|---|---|
list_sessions | Browse all saved session summaries with pagination and limit controls |
search_sessions | Keyword search across stored session summaries (newest first) |
clear_session_index | Remove all session index entries (lightweight index only β summaries untouched; requires confirm=true) |
manage_projects | Manage the cross-project registry β mutations AND reads: register / unregister / update / clear_all + info / list / search (single tool for ALL registry operations; destructive actions require confirm=true) |
register_project | [DEPRECATED alias of manage_projects(action="register")] Register or update a project in the cross-project registry by name + working-dir path |
get_project_info | [DEPRECATED alias of manage_projects(action="info")] Retrieve details of one registered project by its working directory path |
list_projects | [DEPRECATED alias of manage_projects(action="list")] List all registered projects with paths, last-accessed time and session counts |
search_projects | [DEPRECATED alias of manage_projects(action="search")] Search registered projects by name or path substring (kept for one release cycle, 12.09) |
switch_context | Switch context storage to another project's working directory (memory/session lookup target) |
Memory System Enhancements (v1.9.1):
global/project/session scope for future isolation filtering(Recency Γ 0.7) + (Frequency Γ 0.3) ensures intelligent orderingCross-Project Registry (v1.9.8+):
search_projects / get_project_info now call _syncFromSessionMemory() before lookup β auto-registers projects discovered from session memory decisions (.ai_toolbox_memory.msgpack) so the registry never returns stale empty results. Lazy pattern: no startup overhead.manage_projects(action="register") is the primary explicit registration method (requires confirmed path; register_project remains a deprecated alias, 12.09). Silent auto-registration was removed in v1.9.8; Step 0.7 keyword detection in surfaces registered projects on mention (confirm-first: banner only β the one-shot CWD switch happens exclusively after an explicit YES/JA reply).| Tool | Description |
|---|---|
restore_session_context | Composite read-only resume bootstrap ("read session mem", single call): latest session summary (RAM first, then file β same priority as get_session_summary) Β· newest persisted plan with per-step status (get_plan selection semantics) Β· all explicit memory facts Β· context entries in full (auto-checkpoint noise collapsed to ONE line: count + date range + peak usage %; expired session-scoped entries skipped locally WITHOUT pruning the store, mirroring CSM read-time TTL) Β· recent sessions index top-8. Output is a Markdown dossier with per-family presence/staleness header (STALE > 3 days flagged), machine counts block, hard max_chars budget (default 16000, marker + omitted-section list when truncated), self-describing absent/legacy sections on fresh or corrupt stores; no writes anywhere (store files asserted byte-identical pre/post in tests). Params: include_sessions_index (default true), max_chars (1000β50000) |
| Tool | Description |
|---|---|
text_transform | Regex substitution with capture groups ($1, $2), line ranges, global/case-insensitive modes; safer than shell sed |
text_extract | Structured data extraction from delimited text (CSV/TSV/custom) with configurable zero-based field indices |
markdown_table_gen | Generate Markdown tables from object arrays with headers, alignment, truncation, and customizable ellipsis |
restore_from_bak, added by the 28.09 re-audit; all registered under the utility config key)| Tool | Description |
|---|---|
create_backup | Compressed ZIP backup of entire working directory stored in .ai_toolbox_backups/; requires confirm=true |
list_backups | List backups sorted by date newest-first with filename, path, size bytes, and creation timestamp |
restore_backup | Restore full working directory from archive (β οΈ overwrites all files; requires confirm=true) |
delete_backup | Remove specific backup file (β οΈ irreversible; validates existence before deletion) |
cleanup_backups | Recursively list and optionally delete .bak edit backups anywhere in the working-dir tree (21.10 fix for missed nested backups; never descends into node_modules / .git / plugin-state dirs; dry-run by default; confirm required to delete) β registered under the utility toggle key (cleanupBackupsTool.ts) |
restore_from_bak | Restore one file from its .bak backup created by a file-modifying tool (named for the original file, without the .bak suffix) β same utility key (restoreFromBak.ts, 28.09 re-audit: previously undocumented here) |
Status: src/tools/gatewayTools.ts has been removed from the codebase (v1.9.10 session, 24.08) β no gateway tool definitions remain anywhere under src/. Direct SDK registration + schema minification is the active approach; this section documents the historical design only.
The direct SDK registration approach (all tools exposed directly to LLM) has proven more effective for usability. Grammar parser compatibility is now handled via schema minification (toolsSchemaMinifier.ts), which compresses descriptions and caps constraints without limiting tool count.
The gateway pattern was originally designed as follows:
explore_toolsDiscovers available tools and their categories without exposing all registered tools at once. Returns category names only to keep schema small.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Optional: Filter by specific category name (e.g., "fileSystem", "webSearch") |
Returns: { success: boolean, categories: string[], message?: string }
execute_gateway_toolExecutes any registered tool by name with built-in validation and error handling. Delegates to the existing ToolRegistry for execution.
| Parameter | Type | Required | Description |
|---|---|---|---|
toolName | string | Yes | Name of the tool to execute (e.g., "read_file", "web_search") |
arguments | Record<string, unknown> | Yes | Tool-specific arguments as key-value pairs |
Returns: Tool execution result or error message
Why Gateway Was Designed: Sending all registered tools directly to llama.cpp's grammar parser caused failed to parse grammar errors due to EBNF recursion limits. The gateway pattern was intended to reduce initial schema payload while maintaining full functionality on-demand via delegation.
utility toggle; 3 further live sibling tools on this key documented below, re-audit 28.09)| Tool | Description |
|---|---|
generate_chart | Create line/bar/pie/scatter/area charts outputting SVG/PNG with customizable colors, labels, legends. Registered via dataVisualizationTools.ts in the utility tools registry. |
utility config key (previously undocumented; re-audit 28.09)| Tool | Description |
|---|---|
list_available_bak_backups | Recursively scan under the working directory for all .bak backups created by file-modifying tools (21.10 fix; paths are working-dir-relative, root-level keeps the bare-filename form) β pairs with restore_from_bak (restoreFromBak.ts) |
markdown_preview | Render a Markdown file to HTML and open it in the default browser (markdownPreviewTools.ts) |
get_repeat_tool_advice | Return current repeat-tool reminder state/nudges for one tool (or a summary across tracked calls) β Loop-Hygiene B advisory surface (repeatToolReminderTools.ts, rev-3x pile, 24.09 arc) |
| Tool | Description |
|---|---|
read_document | Read PDF (pdf-parse), DOCX (mammoth), or TXT files; automatic binary detection prevents corrupt output Β· Budget-Guard (05.11): same M1 pre-read advisory gate as read_file when the projected context budget would be crossed |
| Tool | Description |
|---|---|
http_request | Generic GET/POST/PUT/DELETE/PATCH client with retry logic, timeout config, multipart upload support |
http_get_json | GET requests expecting JSON response with automatic parsing and optional schema validation |
http_post_json | POST requests with JSON payload, content-type auto-handling, auth token support, status code return |
remove_plan, PLAN-REMOVAL arc, 05.10)Requires taskPlanning toggle in settings or God Mode.
Structured multi-step workflow management tools for creating, tracking, and updating execution plans. Tools persist plan data to .ai_toolbox_plans.json using atomic writes with Zod schema validation.
| Tool | Description |
|---|---|
create_plan | Create a new execution plan with goal and ordered steps (1-30 steps, 500 chars max each). Replaces any existing active plan. Returns planId, goal, and stepCount. |
get_plan | Return the active plan details including goal, all step statuses, completion percentage, elapsed time since creation, and timestamps. Returns null if no plan exists. |
update_plan_step | Update a single step's status according to state machine rules (pendingβin_progressβdone, anyβblocked, blockedβpending). Requires note when marking as blocked. Returns completion metrics including completedSteps, totalSteps, and allDone boolean β and auto-removes the plan from the working-state store at natural completion (every step done; blocked/partial plans are never auto-removed, test-pinned). |
remove_plan | Confirm-gated removal of a plan from the working-state store (PLAN-REMOVAL arc, 05.10): dry-run preview by default β set confirm=true to actually remove. Use for unfinished plans; naturally completed plans are already auto-removed at completion by update_plan_step. Terminal response carries full stats + goal as provenance (house rule: no archive layer). |
Example Workflow:
Gated on the updateCheckEnabled config key (default ON). The desktop-toast channel is additionally governed by notificationsEnabled (channel selection, spec A XOR): exactly ONE surface per session β toast when ON, single in-chat line when OFF.
Since 19.10 the plugin performs a quiet β€1/day update check (src/updateChecker.ts). Since the HUB .VERSION arc (owner GO 19.10) it reads the published hub .VERSION file (https://lmstudio.ai/crunch3r/ai-toolbox/files/.VERSION; strict v?x.y.z parse for raw bodies, noise-tolerant HTML-page extraction as fallback) β NOT GitHub releases/latest. State persists in <dataDir>/update-check.json (survives reinstalls); non-fatal by design.
| Tool | Description |
|---|---|
get_update_info | Read-only update-status surface for the LLM: installed version, whether a strictly-newer published version is known (24h-cached check), and the hub marketplace page URL (releaseUrl) when available β render it as a clickable Markdown link in chat. Never throws; zero NEW state writes (the TTL-stamped getUpdateStatus() read is quiet on fresh cache) |
dismiss_update_reminder | Record "not now" for an update-reminder version β <dataDir>/update-check.json dismissed[]; that version stays silent forever, strictly-newer releases still notify. State-only write; non-fatal by construction |
All categories toggleable in LM Studio settings panel. Most dangerous tools disabled by default requiring explicit opt-in through the UI. God Mode enables all categories instantly β use cautiously.
All tools implement multiple security layers:
validatePath()rm -rf, sudo)β οΈ Important: Most dangerous tools disabled by default requiring explicit user opt-in through settings panel. God Mode bypasses all category restrictions.
Doc sync 2026-09-28 (pattern_scan WALK-ABORT walk-phase abort + FULL per-module re-audit with count corrections β see header; version stamp now v1.9.18 / manifest revision 33) Β· reference updated 2026-09-08 (v1.9.17 / manifest rev 29 β Tool Gating Profile shipped: user-level toggle persistence in %USERPROFILE%\.ai_toolbox\tool_gating_profile.json (booleans only, sparse store; auto-capture of non-default toggles, sticky across new chats) Β· previous refresh 08.09 (v1.9.16 / manifest rev 28): version header sync after web_search fix (no tool surface change) Β· earlier refresh 2026-09-04 (v1.9.15 / manifest rev 27): header totals re-grounded against the live i18n locale reference (src/locales/en.ts: 129 registration entries, 127 distinct tool names). Prior sync: 2026-08-24 (v1.9.10): Web Research count 4β3 after duplicate rag_web_content removal (tool served by Vector RAG module since v1.9.10). Earlier baseline: 2026-08-17 (v1.9.8). FULL per-module re-audit completed same day (28.09): every count above re-verified against the toolsProvider.ts registry + per-module name: scans in src/tools/*.ts; outcomes recorded inline (header gap note, Β§Utilities superseded, Image Analysis section removed, Context Management 21β22, Backup & Restore 5β6). insert_at_line read-back drift detection documented with v1.8.8 hard fix. Graphify-Inspired Suite features (v1.9.5): Confidence-Tagged Results, Hub-Exclusion Clustering (83 tests), Project Auto-Detection, Context Tier Provenance, Cluster-Aware Tool Priority.
Five new architectural modules added in v1.9.5 following graphify repository analysis patterns:
src/types/confidenceTypes.ts)Typed confidence metadata attached to all tool execution outputs.
Three confidence levels for result reliability assessment:
Helper functions available for standardized confidence assignment:
src/utils/hubExclusionClustering.ts)Louvain community detection with hub-exclusion for architectural transparency.
Algorithm flow: Build dependency graph β Calculate degrees β Identify hubs (80th percentile) β Louvain clustering on non-hubs β Majority-vote hub reattachment.
Output includes modularity score, cluster density metrics, and hub identification β all running synchronously under 10ms for typical plugin graphs. 83 tests verify correctness across graph construction, hub identification at various percentiles, Louvain convergence, majority-vote reattachment, and edge cases.
Use cases: Architectural visualization, refactoring guidance (identify modules to refactor together), ContextGuard optimization (compress related clusters), tool priority ranking via centrality scoring.
src/projectAutoDetect.ts)Automatic project registration when cross-project registry searches return empty.
Confidence scoring signals: package.json (+0.4), src/ or lib/ (+0.3), .git (+0.1), build configs (+0.2). Name normalization handles hyphenβunderscore variants and scoped packages (@lmstudio/ai-toolbox). β οΈ DEPRECATED (v1.9.8+): initializeProjectDetection() no longer called from index.ts at startup. Registration requires explicitConfirmation=true via register_project tool. See src/index.ts comment: "NO AUTO-REGISTRATION ON STARTUP".
src/contextTiers.ts)Typed provenance markers for tier-scoped context replacement.
Origin types: _origin: 'ast' | 'semantic' distinguishes raw file content from derived AI insights. replaceTier() replaces only changed tiers while preserving unchanged ones β follows graphify's incremental update pattern to prevent silent overwrites of unchanged nodes.
src/tools/toolPriority.ts)Five-tier priority ranking with hub-exclusion clustering integration.
Tiers: CRITICAL (1, file system tools), HIGH (2, web research/execution/git), STANDARD (3, browser/image/RAG), OPTIONAL (4, context management), BACKGROUND (5, backup/cleanup). Centrality scoring computed from module degree Γ hub bonus β used for intelligent tool filtering when grammar parser limits require pruning.
analyze_image tool exists in code, and there is no imageAnalysis config key; (they had been recorded in the 28.09 header gap note). The four LIVE image tools (, , , ) are documented under Image Processing above.| Update Check | 2 (get_update_info + dismiss_update_reminder; both gated on the updateCheckEnabled toggle β default ON; first documented in the 21.10 sync) | β Enabled (default on) | Active (added 19.10) |
crypto.randomBytes(9) (72-bit entropy) β collision probability ~1/2^72 even under rapid concurrent writesatomicWriteBinaryFile() uses raw buffer writes for image attachment temp files and chart generation β no encoding corruptionrefactorCodeTools and recodeEngine automatically restore from .bak backup if atomic write fails during AST transformationsGREP_FILES_MAX_RUN_MS=3000aborted: truepatternpattern_mode="fixed-strings"pathmoderegexliteralcase_insensitivetrue-ifalseinclude_globexclude_globsmax_depthinclude_globmaxMatches = Number.MAX_SAFE_INTEGERaborted-in Nms-ifind_replace_all | Regex search & replace across multiple files with dry-run preview, .bak backups, file-extension filter; max_depth enforcement (default 10, range 1β50) + MAX_LINES_PER_FILE=5000 hang prevention (v1.9.8+) |
pattern_scan | Recursive content search returning matching lines as {file, line, content} (post-v1.9.11, 30.β31.08 β engine in clean-room module src/tools/patternScan.ts, tool registered in fileSystemTools.ts). Regex by default; unsafe or syntactically invalid regexes fail fast and are auto-demoted to literal mode (reported via demoted_to_literal), unlike grep_files which force-escapes with a hint. Fully async with bounded concurrency (concurrency 1β16, default 4). Resource caps: per-file size gate maxFileSizeBytes (default 256 KB), line-cap gate maxFileLines (default 10,000) β oversize/over-line files reported in skipped[], never scanned; per-file match cap maxMatchesPerFile (default 50); global cap maxTotalMatches (default 200) with stats.truncated=true when hit. Options: root (directory or single file, relative paths resolve against the plugin working directory), mode (regex/literal), caseSensitive (default true), includeGlobs/excludeGlobs (a matching exclude dir is pruned whole), maxDepth (1β50, default 10), matchLineLength truncation (default 300 chars + ellipsis). Directories node_modules, .git, dist, build, out, .next, .nuxt, __pycache__, .venv, coverage are always pruned. Ripgrep phase-1 candidate prefilter (B', 02.09): REMOVED in FIX-34a (13.09) β its rg-WASM search ran synchronously on the main thread (await wasi.start(); all WASI syscalls are sync fs), so while it ran no event-loop turn occurred and NO timer-based hang guard could fire (live host-wedge repro 13.09); pattern_scan now always runs the full JS walk above.** DE-STRAngle arc completed 17.09: wall clock (PATTERN_SCAN_MAX_RUN_MS=3000) REMOVED (RE-ARMED 24.09 per owner order "abort after 3 seconds" β see RE-ARM note below) β deterministic size bounds replace time-based watchdogs (fully-async pipeline since FIX-34a; inline host-thread eval; maxEvalLineLength default 10,000 chars); RE-ARM 24.09 (owner order "abort after 3 seconds"): the wall clock IS armed again β createGrepGuard(hostSignal, PATTERN_SCAN_MAX_RUN_MS=3_000); firing is cooperative at file boundaries β PARTIAL results + aborted: true + cap warn, host-signal abort unchanged; WALK-ABORT 28.09: the BFS walk phase itself now checks this same guard at every directory boundary (walkDirectory signal param β before, only file boundaries checked it, so a slow-FS / deep-tree walk ran unbounded past the deadline), an aborted walk returns PARTIAL targets + aborted: true; regression suites Γ2: , (deterministic size bounds kept alongside). Case-sensitivity is honored per call (caseSensitive, default true) |
.ts/.tsx natively with typescript plugin enabled.import { used, unused } from 'lib') by removing only dead specifiers while preserving formatting..bak backup before any file modification.save_memoryget_memorysearch_memorydelete_memorysave_session_summaryget_session_summaryget_system_infosystem_monitorprocess_listenv_inspectdetect_os_environmentread_clipboardwrite_clipboardsend_notificationfindLMStudioHomeget_enabled_toolshash_filetoken_countconvert_formatsecret_scanport_checkpackage_managejson_queryenv_updateget_current_working_directory| Retrieve all saved memory entries with optional type filtering and result limits |
delete_memory | Remove specific memory entry by unique ID returned during save operations |
memory_recall | READ-ONLY, ID-first recall over the memory layer (added 03.11): mode="index" lists compact {id, kind, type, titleβ€80, date, age_days, est_detail_chars} rows across context entries + memory facts + sessions index; mode="fetch" returns full records for β€10 ids with self-describing misses (not_found.reason β no_such_entry / expired_session_ttl / summary_never_persisted β the last is EXPECTED by design: only the LATEST session summary persists, P0-FIX) |
promptPreprocessor.tsrequire()eval()child_processimage_to_textdescribe_imagescreenshot_desktopcompare_images// Atomic write pattern: Write to temp β atomic rename β delete temp on failure
const tempFile = `${originalPath}.${crypto.randomBytes(9).toString('hex')}.tmp`; // 72-bit entropy
await fs.writeFile(tempFile, content); // Write to randomized temp
await fs.rename(tempFile, originalPath); // Atomic rename (survives crashes)
// If interrupted: temp file orphaned but original intact
// Pattern-based β works regardless of current line number:
line_operations(
file_name,
operation: "insert",
insert_after_pattern: "if (width <= 0 || height <= 0)",
content: "// fix"
)
β Finds line containing pattern β inserts after it β works correctly even if file changed
// Verification-based β catches drift errors before corruption:
line_operations(
file_name,
operation: "insert",
target_line: 84,
content: "// fix",
verify_before_insert: "return;" // Content expected at line 84
)
β Checks if line 84 contains "return;" β If no β BLOCKS with error + context shown (Β±3 lines)
// Renames 'oldVar' to 'newVar' across the entire file
{
"file_path": "./src/index.ts",
"operation": "rename_identifier",
"old_name": "oldVar",
"new_name": "newVar"
}
// Moves 'calculateTotal' from src.ts to utils.ts
{
"file_path": "./src/operations.ts",
"operation": "move_function",
"old_name": "placeholder", // required by schema, ignored for this operation
"function_name": "calculateTotal",
"target_path": "./src/utils.ts"
}
// Extracts the provided code block into a function named 'processData'
{
"file_path": "./src/handler.ts",
"operation": "extract_function",
"old_name": "const result = value * 2;\nconsole.log(result);", // raw code to extract
"new_name": "processData"
}
// Scans file for dead imports and removes them automatically
{
"file_path": "./src/module.ts",
"operation": "unused_import_cleanup"
}
pending β in_progress β done (terminal)
any β blocked β blocked β pending (retry)
// 1. Create plan with goal and steps
create_plan({
goal: "Refactor authentication module",
steps: [
"Read current auth.ts file",
"Identify refactoring opportunities",
"Implement changes to separate concerns",
"Run tests to verify functionality"
]
})
// 2. Track progress as you work
update_plan_step({ planId: "...", index: 0, status: "done" })
update_plan_step({ planId: "...", index: 1, status: "in_progress" })
// 3. Check current state
get_plan() // Returns full plan with progress metrics
// 4. Handle blockers if needed
update_plan_step({ planId: "...", index: 2, status: "blocked", note: "Need API documentation for new auth flow" })
determineConfidence(operationType: 'extraction'|'inference'|'execution'|'search', success: boolean, fallbackUsed?: boolean): Confidence;
createToolResult<T>(data: T, confidence: Confidence, options?: {provenance?: string; note?: string}): { success: true; data: T & ToolResultMetadata };
createErrorResult(message: string, provenance?: string): { success: false; error: string; data: ToolResultMetadata };
| Update Check | 2 (get_update_info + dismiss_update_reminder; both gated on the updateCheckEnabled toggle β default ON; first documented in the 21.10 sync) | β Enabled (default on) | Active (added 19.10) |
crypto.randomBytes(9) (72-bit entropy) β collision probability ~1/2^72 even under rapid concurrent writesatomicWriteBinaryFile() uses raw buffer writes for image attachment temp files and chart generation β no encoding corruptionrefactorCodeTools and recodeEngine automatically restore from .bak backup if atomic write fails during AST transformationsGREP_FILES_MAX_RUN_MS=3000aborted: truepatternpattern_mode="fixed-strings"pathmoderegexliteralcase_insensitivetrue-ifalseinclude_globexclude_globsmax_depthinclude_globmaxMatches = Number.MAX_SAFE_INTEGERaborted-in Nms-ifind_replace_all | Regex search & replace across multiple files with dry-run preview, .bak backups, file-extension filter; max_depth enforcement (default 10, range 1β50) + MAX_LINES_PER_FILE=5000 hang prevention (v1.9.8+) |
pattern_scan | Recursive content search returning matching lines as {file, line, content} (post-v1.9.11, 30.β31.08 β engine in clean-room module src/tools/patternScan.ts, tool registered in fileSystemTools.ts). Regex by default; unsafe or syntactically invalid regexes fail fast and are auto-demoted to literal mode (reported via demoted_to_literal), unlike grep_files which force-escapes with a hint. Fully async with bounded concurrency (concurrency 1β16, default 4). Resource caps: per-file size gate maxFileSizeBytes (default 256 KB), line-cap gate maxFileLines (default 10,000) β oversize/over-line files reported in skipped[], never scanned; per-file match cap maxMatchesPerFile (default 50); global cap maxTotalMatches (default 200) with stats.truncated=true when hit. Options: root (directory or single file, relative paths resolve against the plugin working directory), mode (regex/literal), caseSensitive (default true), includeGlobs/excludeGlobs (a matching exclude dir is pruned whole), maxDepth (1β50, default 10), matchLineLength truncation (default 300 chars + ellipsis). Directories node_modules, .git, dist, build, out, .next, .nuxt, __pycache__, .venv, coverage are always pruned. Ripgrep phase-1 candidate prefilter (B', 02.09): REMOVED in FIX-34a (13.09) β its rg-WASM search ran synchronously on the main thread (await wasi.start(); all WASI syscalls are sync fs), so while it ran no event-loop turn occurred and NO timer-based hang guard could fire (live host-wedge repro 13.09); pattern_scan now always runs the full JS walk above.** DE-STRAngle arc completed 17.09: wall clock (PATTERN_SCAN_MAX_RUN_MS=3000) REMOVED (RE-ARMED 24.09 per owner order "abort after 3 seconds" β see RE-ARM note below) β deterministic size bounds replace time-based watchdogs (fully-async pipeline since FIX-34a; inline host-thread eval; maxEvalLineLength default 10,000 chars); RE-ARM 24.09 (owner order "abort after 3 seconds"): the wall clock IS armed again β createGrepGuard(hostSignal, PATTERN_SCAN_MAX_RUN_MS=3_000); firing is cooperative at file boundaries β PARTIAL results + aborted: true + cap warn, host-signal abort unchanged; WALK-ABORT 28.09: the BFS walk phase itself now checks this same guard at every directory boundary (walkDirectory signal param β before, only file boundaries checked it, so a slow-FS / deep-tree walk ran unbounded past the deadline), an aborted walk returns PARTIAL targets + aborted: true; regression suites Γ2: , (deterministic size bounds kept alongside). Case-sensitivity is honored per call (caseSensitive, default true) |
.ts/.tsx natively with typescript plugin enabled.import { used, unused } from 'lib') by removing only dead specifiers while preserving formatting..bak backup before any file modification.save_memoryget_memorysearch_memorydelete_memorysave_session_summaryget_session_summaryget_system_infosystem_monitorprocess_listenv_inspectdetect_os_environmentread_clipboardwrite_clipboardsend_notificationfindLMStudioHomeget_enabled_toolshash_filetoken_countconvert_formatsecret_scanport_checkpackage_managejson_queryenv_updateget_current_working_directory| Retrieve all saved memory entries with optional type filtering and result limits |
delete_memory | Remove specific memory entry by unique ID returned during save operations |
memory_recall | READ-ONLY, ID-first recall over the memory layer (added 03.11): mode="index" lists compact {id, kind, type, titleβ€80, date, age_days, est_detail_chars} rows across context entries + memory facts + sessions index; mode="fetch" returns full records for β€10 ids with self-describing misses (not_found.reason β no_such_entry / expired_session_ttl / summary_never_persisted β the last is EXPECTED by design: only the LATEST session summary persists, P0-FIX) |
promptPreprocessor.tsrequire()eval()child_processimage_to_textdescribe_imagescreenshot_desktopcompare_images// Atomic write pattern: Write to temp β atomic rename β delete temp on failure
const tempFile = `${originalPath}.${crypto.randomBytes(9).toString('hex')}.tmp`; // 72-bit entropy
await fs.writeFile(tempFile, content); // Write to randomized temp
await fs.rename(tempFile, originalPath); // Atomic rename (survives crashes)
// If interrupted: temp file orphaned but original intact
// Pattern-based β works regardless of current line number:
line_operations(
file_name,
operation: "insert",
insert_after_pattern: "if (width <= 0 || height <= 0)",
content: "// fix"
)
β Finds line containing pattern β inserts after it β works correctly even if file changed
// Verification-based β catches drift errors before corruption:
line_operations(
file_name,
operation: "insert",
target_line: 84,
content: "// fix",
verify_before_insert: "return;" // Content expected at line 84
)
β Checks if line 84 contains "return;" β If no β BLOCKS with error + context shown (Β±3 lines)
// Renames 'oldVar' to 'newVar' across the entire file
{
"file_path": "./src/index.ts",
"operation": "rename_identifier",
"old_name": "oldVar",
"new_name": "newVar"
}
// Moves 'calculateTotal' from src.ts to utils.ts
{
"file_path": "./src/operations.ts",
"operation": "move_function",
"old_name": "placeholder", // required by schema, ignored for this operation
"function_name": "calculateTotal",
"target_path": "./src/utils.ts"
}
// Extracts the provided code block into a function named 'processData'
{
"file_path": "./src/handler.ts",
"operation": "extract_function",
"old_name": "const result = value * 2;\nconsole.log(result);", // raw code to extract
"new_name": "processData"
}
// Scans file for dead imports and removes them automatically
{
"file_path": "./src/module.ts",
"operation": "unused_import_cleanup"
}
pending β in_progress β done (terminal)
any β blocked β blocked β pending (retry)
// 1. Create plan with goal and steps
create_plan({
goal: "Refactor authentication module",
steps: [
"Read current auth.ts file",
"Identify refactoring opportunities",
"Implement changes to separate concerns",
"Run tests to verify functionality"
]
})
// 2. Track progress as you work
update_plan_step({ planId: "...", index: 0, status: "done" })
update_plan_step({ planId: "...", index: 1, status: "in_progress" })
// 3. Check current state
get_plan() // Returns full plan with progress metrics
// 4. Handle blockers if needed
update_plan_step({ planId: "...", index: 2, status: "blocked", note: "Need API documentation for new auth flow" })
determineConfidence(operationType: 'extraction'|'inference'|'execution'|'search', success: boolean, fallbackUsed?: boolean): Confidence;
createToolResult<T>(data: T, confidence: Confidence, options?: {provenance?: string; note?: string}): { success: true; data: T & ToolResultMetadata };
createErrorResult(message: string, provenance?: string): { success: false; error: string; data: ToolResultMetadata };
tests/patternScanWalkAbort.test.tstests/patternScanWalkAbortSlowTree.test.tstests/patternScanWalkAbort.test.tstests/patternScanWalkAbortSlowTree.test.ts