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服务器