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 0.4.1 includes a local MCP server with 21 tools, 8 resources, and 5 prompts. The skills tools discover reusable instructions, an optional proposal tool saves pending skills for human review, and MCP prompts provide ready-made briefing, failure-review, risk-check, and session-summary requests. See Shared Skills for native sync. This guide introduces a selection of capabilities; see the full reference for current capabilities. A connected client can query recorded history and may send returned data to its AI provider under its own settings.

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

Alongside tools, Suvadu exposes resources that compatible clients can read. The five examples below are part of the current seven-resource interface. Whether and when a resource is included in model context depends on your client.

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.

A client can read these resources to retrieve recent terminal context. Suvadu does not force resources into every conversation or guarantee automatic loading at session start.

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 the 21 tools, 8 resources, and 5 prompts become available to the client.

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.

For clients that use an mcpServers configuration object, the server entry looks like this. Use suv init claude-code for Suvadu's supported Claude Code setup:

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

Illustrative 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?"

When resuming work, a compatible client can read suvadu://history/recent for recent commands or call recent_commands with an after filter. The result reflects activity recorded by the configured integrations.

// 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: destructive
// Reason: Force push

An agent can call this tool before proposing a command. This is rule-based classification; it does not enforce a permission check or block execution.

Privacy and Security

The MCP server runs locally over stdin/stdout and uses read-only connections for history and skill queries. An optional propose_skill tool uses a separate write connection to save pending proposals for human review. It does not open a network port or provide a cloud history-sync service.

Local storage does not determine what a connected client does with returned data. History, prompts, notes, and other captured context can contain sensitive information, and the client may send results to its model provider. Review the client's access and data-handling settings before connecting it. Suvadu's configured redaction rules can miss secret formats.

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. Install the binary, enable shell recording, and try your first search. Suvadu supports Zsh and Bash on macOS and Linux.

For an overview of what the MCP server can do, see the MCP Server page. For the full reference including all tool parameters and resource schemas, see the MCP Server documentation.