How AI Agents Query Your Shell History via MCP

AI coding agents are getting good at writing code, but they still operate with a blind spot: they have no idea what you did in your terminal five minutes ago. They can't see which commands failed, what you changed, or whether you've already tried the thing they're about to suggest.

Suvadu fixes this. Starting with version 0.2.0, Suvadu includes a built-in MCP server that exposes 11 tools and 5 auto-injected resources, giving AI agents direct, queryable access to your shell history — entirely locally, with no network calls.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents interact with external tools and data sources. Instead of agents only seeing what's inside their context window, MCP lets them reach out to external systems, query structured data, and get results back — all through a well-defined JSON-RPC interface.

Think of it as a plugin system for AI agents. The agent discovers what tools are available, understands their schemas, and calls them when needed. No custom integration code required on the agent side.

Suvadu's MCP server turns your shell history into one of those queryable systems. When an agent like Claude Code or Cursor is connected to Suvadu via MCP, it can search your command history, check what failed, assess risk before running something destructive, and understand what you've been working on — without you having to explain any of it.

Why Give AI Agents Access to Shell History?

At first, the idea of giving an AI agent access to your shell history might seem unusual. But once you see what it enables, it becomes hard to go back.

• Context. The agent can see what commands you've been running, what failed, and what changed. Instead of starting from zero, it picks up where you are.
• Continuity. Close your terminal, reboot your machine, come back tomorrow — the agent can still see your full history and pick up where you left off across sessions.
• Safety. Before the agent suggests running rm -rf or git push --force, it can check the risk level first and decide whether to warn you or take a safer path.
• Debugging. When something breaks, the agent doesn't just see the last error message. It can see the full execution history: what was tried, what the exit codes were, and which prompt triggered each command.

The key insight is that your shell history is a rich, structured record of everything that's happened in your development environment. Suvadu already captures all of it — commands, exit codes, durations, directories, executors, timestamps. The MCP server simply makes that data available to agents that can use it.

Available Tools

The MCP server exposes 11 tools that agents can call on demand. Each tool accepts structured parameters and returns formatted results.

Tool	Description
search_commands	Search history by text pattern, directory, executor, exit code, and date range. The workhorse for finding specific commands.
recent_commands	Get the most recent commands in a directory. Useful for understanding what just happened in a project.
command_status	Check if a specific command has been run before and what happened — exit code, when, where, and how often. Helps the agent avoid repeating known failures.
get_prompts	Browse prompts sent to AI agents and see which commands each prompt triggered. Useful for understanding the chain of actions behind a task.
session_history	Get the full command history of a specific session in chronological order. Good for replaying or understanding a work session.
get_stats	Aggregate statistics: command counts, success rates, top commands, activity patterns. Gives the agent a high-level view of your workflow.
list_sessions	Browse recent sessions with metadata: start time, command count, directory, executor. Helps the agent find the right session to investigate.
what_changed	Find file-modifying operations that ran recently — writes, deletes, moves, installs, and config changes. Critical for understanding what's different now.
what_failed	Find commands that failed (non-zero exit code) and, when available, which prompt caused them. The first thing an agent should check when debugging.
suggest_next	Predict the next commands you're likely to run based on frecency (frequency + recency) analysis. Helps the agent anticipate your intent.
assess_risk	Pre-execution safety check. Pass a command and get its risk level (Safe, Low, Medium, High, or Critical) before running it. A guard rail for destructive operations.

Every tool accepts optional filters like directory, executor, and date ranges, so agents can scope their queries precisely. Results include exit codes, timestamps, durations, and working directories — everything the agent needs to reason about what happened.

Available Resources

In addition to tools (which agents call on demand), the MCP server provides 5 resources that are automatically injected into the agent's context at the start of each session. These give the agent immediate awareness of your recent terminal activity without it needing to make any tool calls first.

Resource URI	What It Provides
suvadu://history/recent	Your last 20 commands with exit codes, timestamps, directories, and executors
suvadu://failures/recent	Recent failed commands from the last 24 hours, grouped by the prompt that caused them
suvadu://stats/today	Today's shell statistics: total command count, success rate, top commands, and most active directories
suvadu://risk/summary	Risk assessment summary of recent commands, broken down by severity level (Critical, High, Medium, Low, Safe)
suvadu://agents/activity	Per-agent breakdown of recent activity: which agents ran what, how many commands, and their success rates

The resource URIs also support a session template — suvadu://history/session/{session_id} — so agents can fetch the full command history of any specific session.

Because resources are auto-injected, the agent starts every conversation already knowing your recent context. It doesn't need to ask "what have you been working on?" — it can see your last 20 commands, any recent failures, and today's activity patterns right from the first message.

Setup

Getting the MCP server connected to your AI agent takes one command.

Claude Code

suv init claude-code

This adds Suvadu as an MCP server in Claude Code's configuration file. Once configured, Claude Code will automatically start the MCP server as a subprocess when it launches, and all 11 tools and 5 resources become available immediately.

Cursor

suv init cursor

Same idea — Suvadu registers itself as an MCP server in Cursor's configuration.

Manual Setup

If you need to configure things manually, the MCP server is started with:

suv mcp-serve

This starts a JSON-RPC server over stdin/stdout. The server runs as a subprocess of the AI agent — it does not open any network ports. You can add it to any MCP-compatible agent by pointing the agent's MCP configuration to the suv mcp-serve command.

A typical configuration entry in Claude Code's settings.json looks like this:

{
  "mcpServers": {
    "suvadu": {
      "command": "suv",
      "args": ["mcp-serve"]
    }
  }
}

Real-World Examples

Here are three concrete scenarios where the MCP server changes how you work with an AI agent.

1. "What went wrong?"

You're debugging a failing build. Instead of pasting error output into the agent's chat, the agent calls what_failed scoped to your project directory. It gets back every failed command from the last 24 hours: the exact command, its exit code, when it ran, and which prompt triggered it (if it was agent-initiated). The agent can then trace the chain of failures to understand root causes, not just symptoms.

// Agent calls what_failed with:
{
  "directory": "/Users/you/projects/api",
  "hours": 4
}

// Gets back:
// exit 1 | cargo test -- --test-threads=1 | 14:23:05
// exit 2 | cargo build --release | 14:20:11
//   prompt: "build the project in release mode"
// exit 1 | npm run lint | 13:55:42

2. "What did I do yesterday?"

You're starting a new work session and need to pick up where you left off. The agent doesn't need to ask. The auto-injected suvadu://history/recent resource already gives it your last 20 commands. If it needs more context, it calls recent_commands with an after filter set to "yesterday". It now knows which directories you were active in, which tests you ran, what you installed, and what the outcomes were.

// Agent calls recent_commands with:
{
  "after": "yesterday",
  "directory": "/Users/you/projects/api",
  "limit": 30
}

3. "Is this safe?"

The agent is about to suggest a destructive command — say, dropping a database table or force-pushing to a branch. Before suggesting it, the agent calls assess_risk with the command text. Suvadu's risk engine analyzes the command and returns a severity level. If the result comes back as "Critical" or "High", the agent can warn you, suggest a safer alternative, or add confirmation steps.

// Agent calls assess_risk with:
{
  "command": "git push --force origin main"
}

// Gets back:
// Risk: Critical
// Category: version-control
// Reason: Force push to main can overwrite collaborators' work

This is particularly valuable because the risk check happens before the agent presents the command to you, not after. The agent can self-correct before you ever see a dangerous suggestion.

Privacy and Security

This is the part people care about most, and the answer is straightforward: everything stays on your machine.

• 100% local. The MCP server runs as a local subprocess, communicating over stdin/stdout only. There are no network calls, no API keys, no cloud services involved.
• No network ports. The server does not listen on any TCP or UDP ports. It is not reachable from the network.
• No external data transmission. Your shell history never leaves your machine through the MCP server. The data stays in the same local SQLite database that powers all other Suvadu commands.
• Same data, same permissions. The MCP server reads from the same database as suv search and other Suvadu CLI commands. It opens the database in read-only mode. It cannot modify your history.
• Scoped access. The agent only sees your shell history. It does not get access to your filesystem, environment variables, credentials, or anything else.

The MCP server is just a structured interface on top of data you already have locally. If you're comfortable using suv search in your terminal, the MCP server exposes the same data through the same database, just in a format that AI agents can query programmatically.

Getting Started

If you already have Suvadu installed, the MCP server is built in — there's nothing extra to install. Run suv init claude-code or suv init cursor to connect it to your agent, and the next time you start a session, the agent will have full access to your shell history.

If you're new to Suvadu, start with the installation guide. It takes about 30 seconds, runs entirely locally, and works with Zsh on macOS and Linux.

For the full MCP server reference, including all tool parameters and resource schemas, see the MCP Server documentation.