Bash History MCP

🚀 Atuin Integration for Claude Code

Achieve bidirectional bash history integration between Claude Code and atuin.

🚀 Quick Start

This project enables bidirectional bash history integration between Claude Code and atuin. It allows Claude Code to write commands to atuin's history and query the history, providing persistent history, context awareness, rich metadata, and cross - machine sync.

✨ Features

• Persistent history: You can rerun commands that Claude executed directly from your terminal.
• Context awareness: Claude can learn from your command patterns and workflow.
• Rich metadata: History records include timestamps, working directory, exit codes, and duration.
• Cross - machine sync: If atuin sync is enabled, the history can be synced across multiple machines.

📦 Installation

Prerequisites

• Install and configure atuin.
• Install Bun.

Write Hook Installation

⚠️ Important Note

If you've previously installed this package and are updating to a new version, clear Bun's cache first:

bun pm cache rm

Step 1: Locate your settings file Claude Code settings are stored in ~/.claude/settings.json. Create it if it doesn't exist:

mkdir -p ~/.claude
touch ~/.claude/settings.json

Step 2: Add the hook configuration Edit ~/.claude/settings.json and add the following content:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bunx github:nitsanavni/bash-history-mcp hook"
          }
        ]
      }
    ]
  }
}

If you already have hooks configured, merge the above configuration with your existing one:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bunx github:nitsanavni/bash-history-mcp hook"
          }
        ]
      },
      // ... your other PostToolUse hooks
    ]
    // ... your other hook types (PreToolUse, etc.)
  }
}

Step 3: Restart Claude Code The hook will be active in your next Claude Code session.

Step 4: Verify it's working After Claude runs some bash commands, execute the following command:

atuin history last

You should see the commands that Claude executed.

MCP Server Installation

⚠️ Important Note

If you've previously installed this package and are updating to a new version, clear Bun's cache first:

bun pm cache rm

Configure Claude Code to use the MCP server:

claude mcp add -s user bash-history bunx -- github:nitsanavni/bash-history-mcp mcp

Or manually add the following to ~/.claude/settings.json:

{
  "mcpServers": {
    "bash-history": {
      "command": "bunx",
      "args": ["github:nitsanavni/bash-history-mcp", "mcp"]
    }
  }
}

💻 Usage Examples

Basic Usage

The available tools for querying atuin history are as follows:

• search_history(query, limit?): Search for commands matching a pattern.

  Example: search_history("git commit", 5)
  

• get_recent_history(limit?): Get recent commands.

  Example: get_recent_history(10)
  

🔧 Technical Details

Architecture

Write: Hook

The Claude Code hook writes commands to atuin after Claude executes each bash command.

# Post-bash-execution hook calls:
id=$(atuin history start "$COMMAND")
atuin history end --exit "$EXIT_CODE" --duration 0 "$id"

Read: MCP Server

The MCP server allows Claude to query your atuin history. Tools:

• search_history(query, limit?) - Find commands matching a pattern
• get_recent_history(limit?) - Get recent commands with timestamps and exit codes

How It Works

After each bash command Claude executes:

1. The hook receives JSON with the command and exit code via stdin.
2. It calls atuin history start "$COMMAND" to get an entry ID.
3. It calls atuin history end --exit $EXIT --duration 0 $ID.
4. It fails silently if atuin is unavailable.

Troubleshooting

Hook not running?

# Check if hook is registered
claude --debug
# Run a command in Claude and look for hook execution logs

Commands not appearing in atuin?

# Test atuin manually
atuin history start "test command"
atuin history last

📚 Documentation

Implementation Status

1. ✅ Write hook with atuin integration
2. ✅ Test hook integration
3. ✅ MCP server with read - only atuin access