CliRecall

CliRecall is an AI-powered terminal command history and memory assistant for VS Code. It automatically captures, explains, and recalls terminal commands you execute in your workspace, keeping them private to you while utilizing MongoDB Atlas and LLM models.

Features

• Automated Command Logging: Silently tracks commands run in your VS Code terminals, automatically masking credentials/secrets (tokens, passwords, API keys).
• Private-by-Default: Each command is tied to your local VS Code installation, ensuring your history remains entirely private, even when using a shared MongoDB database.
• AI-Generated Summaries: Automatically generates natural language explanations for your executed commands.
• Quick Search: Instantly look up past commands by keyword, description, or project name via the VS Code Command Palette.
• Ask AI Assistant: Chat with CliRecall AI directly from the sidebar webview. It uses your project context and command history to suggest the exact commands you need.

Development Intelligence (2.0)

CliRecall also builds a local development graph of your project: files, symbols, dependencies, git history, and the full history of every command you run. It is built by deterministic engines — the language server, an import scanner, git plumbing, and stack-trace parsing — not by asking an LLM. Every relationship CliRecall shows is labelled:

• Verified — produced by a compiler, git, or a recorded execution.
• Inferred — produced by a heuristic (lexical import scan, naming convention).

What the foundation records today:

• File & symbol index — incremental, hash-gated, watcher-driven. Unchanged files cost one stat.
• Dependency graph — imports, requires, dynamic imports and re-exports, resolved through tsconfig path aliases.
• Git history — commits, per-file line counts, churn, and co-change relationships.
• Execution history — every terminal run with its exit code, duration and output, rather than only a "last run" counter.
• Error graph — stack traces and compiler diagnostics parsed out of failed commands and linked back to the source files they name.

IDE intelligence

• Why is this code here? — hover any symbol. CliRecall runs git log -L over that exact line range, so it names the commit that introduced the code, not just the last one to touch it, alongside change types, dependents and any recorded failures. The card is suppressed when there is nothing worth saying.
• What breaks if I change this? — CliRecall: Analyze Impact. Direct callers come from the language server's call hierarchy (Verified); transitive dependents from the import graph (Inferred); API consumers from route detection. Risk is scored by a deterministic model whose full arithmetic is shown — the LLM interprets those numbers and never produces them.
• Explain this module — the relationship tree (called by / depends on / routes / database / events / tests), every node clickable.
• Code GPS — CliRecall: Where Am I? places the current file in the route → controller → service → repository → database chain.
• Trace execution — walks callers upward to an entry point and callees downward to the datastore. Each hop is labelled Verified (language server resolved it) or Inferred (a route decorator or naming convention suggested it), and ambiguous forks are listed rather than hidden.

Historical intelligence

• Code Archaeology — CliRecall: Show Evolution. Scoped to the symbol under the cursor when there is one (git log -L), otherwise the whole file (git log --follow, so renames don't truncate it). Commits are ranked by a deterministic significance score — churn against the file's own median, commit category, files touched, issue references — and the Evolution strip (v1 → v2 → … → CURRENT) opens any past revision read-only or diffs it against your working tree.
• This code has caused problems before — CliRecall: Investigate Failures In This File lists the failure signatures whose stack traces name this file, grouped into episodes.
• How it was fixed — selecting a failure reconstructs the episode from the execution log: problem → failed attempts → what succeeded in between → commits in the window → result, with time-to-fix and prior episodes of the same signature. The suggested fix is labelled Inferred — it is temporal correlation, explicitly not proven causation.
• Code → Terminal — CliRecall: Show Related Terminal Activity ranks commands by how they relate to the file: a stack trace naming it is Verified; command text, working directory, timing and toolchain overlap are Inferred. Also shows the last known-good command sequence and per-command run/failure/duration stats.
• Development Timeline — a tree view in the CliRecall sidebar that reconstructs working sessions from the execution log, splitting on inactivity gaps and marking sessions that ended while still failing. Clicking an entry opens the captured output, the commit, or the failure investigation.

Architecture and change intelligence

• Architecture Map — CliRecall: Show Architecture draws the project from actual evidence: the import graph supplies the edges, naming conventions the layers, imported packages the datastore nodes. Files are grouped into modules so a large repo stays readable. The layout is computed deterministically (layered, with barycenter crossing reduction), so the same project always draws the same picture. Supports zoom, pan, search, filtering and focus mode; clicking a node shows its files, routes and failure count, and opens the source.
• Project Brain — CliRecall: Show Project Brain is one unified model: stack, modules and their roles, API surface, package scripts, commands actually run (from the execution log, not just what package.json declares), mined workflows, and the project's recurring problems. It also lists what it could not determine, rather than guessing.
• Change Intelligence — CliRecall: Analyze Change Impact reads your uncommitted diff, maps each hunk onto the indexed symbol ranges it touches, then reports dependents, API consumers, affected tests and past failures per file, ranked by risk. Lexical signature signals (removed export, changed parameter list, removed field) flag suspected breaking changes — labelled Inferred, never asserted.

Investigate — the universal entry point

CliRecall: Investigate gathers the current context automatically — the failing command, its exit code and captured output, the parsed error, the stack frames, the git branch, everything changed since that command last succeeded, and every prior occurrence of the same failure. It then runs a fixed checklist and ranks candidate causes deterministically: a dependency change, a source change (weighted higher when a changed file also appears in the stack trace), a config change, an unreachable service, a local environment problem, a known recurrence, or a flaky command. Each candidate lists its supporting evidence, the evidence against it, and a concrete next step. The model writes the conclusion from that ranking — it is explicitly forbidden from reordering it.

AI intelligence

• Code Smell Radar — CliRecall: Analyze Code Health measures cyclomatic complexity, source lines, nesting, parameters, fan-in/out, recorded failures, churn, and the measured average duration of related commands. Every finding cites both the measurement and the threshold rule that produced it. The LLM interprets; it never produces a number.
• Smart TODO — CliRecall: Show Smart TODOs finds markers across comment syntaxes, resolves the enclosing symbol, and attaches the errors recorded against that file, the tests covering it, and an effort estimate. The suggested plan is a suggestion: CliRecall never edits your source.
• Learning Path — CliRecall: Generate Learning Path orders real dependency-graph files top-down through the architecture, with a per-step reason and a reading estimate. Start guided tour walks the files at your pace.

Commands

All of these are also on the editor right-click menu under CliRecall. The status-bar entry shows indexing activity; hover it for index counts.

How the AI is used

The LLM never sees your repository. Each explanation is built from a bounded evidence packet — a structured list of facts that deterministic engines already established, each tagged VERIFIED or INFERRED, with hard caps on rows and total size. The model is instructed to reason only over that packet, to hedge on inferred facts, and to say when the evidence is insufficient. Every panel renders its full analysis before the model is consulted, so CliRecall works with no API key configured — you simply lose the prose.

Privacy

The development graph is local only — it lives in a SQLite database inside the extension's storage folder and is never synchronised to MongoDB. Captured terminal output is masked for credentials (tokens, passwords, JWTs, connection strings, private keys, Authorization headers, sensitive environment variables) before it is written to disk. Use clirecall.privacy.excludeGlobs and clirecall.privacy.ignoreCommandPatterns to exclude paths and commands entirely, or set clirecall.capture.output to false to disable output capture.

Extension Settings

Configure CliRecall by opening your VS Code settings and searching for:

• commandMemory.mongodbUri: Optional MongoDB connection string (e.g., MongoDB Atlas) for cloud synchronization across machines. If left blank, CliRecall will automatically use a local, private SQLite database.
• commandMemory.llmApiKey: API Key for your LLM provider (e.g. Gemini, NVIDIA NIM, OpenAI, DeepSeek).
• commandMemory.llmBaseUrl: Base URL for the OpenAI-compatible AI API (defaults to https://integrate.api.nvidia.com/v1).
• commandMemory.llmModel: The AI Model to use for generating summaries and answering questions (defaults to meta/llama-3.1-8b-instruct).
• clirecall.intelligence.enabled: Build the local development graph (default true).
• clirecall.intelligence.indexSymbols: Extract symbols via VS Code's language servers (default true).
• clirecall.intelligence.maxFiles / clirecall.intelligence.maxFileBytes: Indexing bounds for large repositories.
• clirecall.intelligence.gitHistoryDepth: Commits to ingest on the first pass (default 500); later passes are incremental.
• clirecall.capture.output / clirecall.capture.maxOutputBytes: Terminal output capture for failed commands.
• clirecall.privacy.excludeGlobs / clirecall.privacy.ignoreCommandPatterns: Paths and commands to never index or record.

Development

npm install
npm run package   # build dist/extension.js
npm test          # compile + run the deterministic unit tests

Tests cover the deterministic engines only — masking, project detection, import scanning, module resolution, stack-trace parsing, git parsing, and the storage/migration layer. LLM output is never treated as a passing test.

Usage

1. View and Search in the Sidebar

Click on the CliRecall icon in the Activity Bar to open the sidebar. Here, you can:

• Ask AI: Input a natural language prompt (e.g., "how do I run tests on this project") to receive context-aware command suggestions.
• Search: Start typing in the search bar to query your past command history.
• Recent History: View, copy, or click to run recent commands.

2. Search via Command Palette

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) and run:

• Command Memory: Search - Performs a fuzzy search of your commands and allows you to copy or execute them directly.
• Command Memory: Ask - Prompt the AI assistant from a quick input box.

Example Configurations

Google Gemini (AI Studio)

• Base URL: https://generativelanguage.googleapis.com/v1beta/openai/
• API Key: Your Gemini API Key from Google AI Studio
• Model: gemini-1.5-flash or gemini-2.5-flash

OpenAI

• Base URL: https://api.openai.com/v1
• API Key: sk-proj-...
• Model: gpt-4o-mini

Local Ollama

• Base URL: http://localhost:11434/v1
• API Key: ollama (any non-empty placeholder string)
• Model: llama3 (or your downloaded model name)