Bash History MCP

🚀 Claude Code的Atuin集成

Claude Code與atuin之間實現了雙向的Bash歷史記錄集成，解決了Claude Code運行Bash命令但不記錄在Shell歷史記錄，以及無法從用戶命令模式中學習的問題。

🚀 快速開始

本集成方案可實現Claude Code與atuin的雙向Bash歷史記錄集成，讓Claude Code運行的命令能記錄在atuin中，同時Claude Code也能查詢atuin歷史記錄，帶來持久歷史記錄、上下文感知、豐富元數據和跨機器同步等好處。

✨ 主要特性

• 持久歷史記錄：可在終端中重新運行Claude執行過的命令。
• 上下文感知：Claude能從用戶的命令模式和工作流程中學習。
• 豐富元數據：包含時間戳、工作目錄、退出代碼和持續時間等信息。
• 跨機器同步：如果啟用了atuin同步，歷史記錄可在多臺機器間同步。

📦 安裝指南

前提條件

• 已安裝並配置好atuin。
• 已安裝Bun。

寫入鉤子安裝

注意：如果之前安裝過此包並要更新到新版本，請先清除Bun的緩存：

bun pm cache rm

步驟1：定位設置文件 Claude Code的設置文件位於~/.claude/settings.json。如果該文件不存在，請創建它：

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

步驟2：添加鉤子配置 編輯~/.claude/settings.json並添加以下內容：

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

如果已經配置了鉤子，請與現有配置合併：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bunx github:nitsanavni/bash-history-mcp hook"
          }
        ]
      },
      // ... 您的其他PostToolUse鉤子
    ]
    // ... 您的其他鉤子類型（PreToolUse等）
  }
}

步驟3：重啟Claude Code 鉤子將在您的下一個Claude Code會話中激活。

步驟4：驗證是否正常工作 Claude運行一些Bash命令後，執行以下命令：

atuin history last

您應該能看到Claude執行的命令。

MCP服務器安裝

注意：如果之前安裝過此包並要更新到新版本，請先清除Bun的緩存：

bun pm cache rm

配置Claude Code使用MCP服務器：

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

或者手動添加到~/.claude/settings.json：

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

💻 使用示例

基礎用法

# 搜索匹配模式的命令
search_history("git commit", 5)
# 獲取最近的命令
get_recent_history(10)

📚 詳細文檔

架構

寫入：鉤子

Claude Code鉤子 → Claude執行每個Bash命令後，將命令寫入atuin。

# 執行Bash命令後的鉤子調用：
id=$(atuin history start "$COMMAND")
atuin history end --exit "$EXIT_CODE" --duration 0 "$id"

讀取：MCP服務器

MCP服務器 → Claude可以查詢您的atuin歷史記錄。 工具：

• search_history(query, limit?) - 查找匹配模式的命令
• get_recent_history(limit?) - 獲取帶有時間戳和退出代碼的最近命令

工作原理

Claude執行每個Bash命令後：

1. 鉤子通過標準輸入接收包含命令和退出代碼的JSON。
2. 調用atuin history start "$COMMAND"獲取一個條目ID。
3. 調用atuin history end --exit $EXIT --duration 0 $ID。
4. 如果atuin不可用，則靜默失敗。

故障排除

鉤子未運行？

# 檢查鉤子是否已註冊
claude --debug
# 在Claude中運行一個命令並查找鉤子執行日誌

命令未出現在atuin中？

# 手動測試atuin
atuin history start "test command"
atuin history last

🔧 技術細節

實現狀態

1. ✅ 與atuin集成的寫入鉤子
2. ✅ 測試鉤子集成
3. ✅ 具有隻讀atuin訪問權限的MCP服務器