Atuin Integration for Claude Code

Bidirectional bash history integration between Claude Code and atuin.

Problem

• Claude Code runs bash commands but they don't appear in your shell history
• Claude Code can't learn from your command patterns

Architecture

Write: Hook

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

MCP server → Claude can 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

Benefits

• Persistent history: Rerun commands Claude executed from your terminal
• Context awareness: Claude can learn from your command patterns and workflow
• Rich metadata: Timestamps, working directory, exit codes, and duration
• Cross-machine sync: History syncs across machines (if atuin sync is enabled)

Setup

Prerequisites

• atuin installed and configured
• Bun installed

Write Hook Installation

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 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:

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

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

{
  "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:

atuin history last

You should see the commands Claude executed.

How It Works

After each bash command Claude executes:

1. Hook receives JSON with command and exit code via stdin
2. Calls atuin history start "$COMMAND" to get an entry ID
3. Calls atuin history end --exit $EXIT --duration 0 $ID
4. 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

MCP Server Installation

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 to ~/.claude/settings.json:

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

Available Tools:

• 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)

OpenCode Plugin Installation

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

bun pm cache rm

Add to your opencode config:

Edit your opencode.json (either in ~/.config/opencode/ or project root) and add:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["bash-history-mcp"]
}

The plugin will automatically log all bash commands executed by opencode to your atuin history.

Implementation Status

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