ccfolio (Hippensteel)

ccfolio

索引、搜索和归档您的Claude Code对话。跟踪成本、导出到黑曜石，并允许您在不丢失上下文的情况下恢复过去的会话。

它的作用

Claude Code将每个对话存储为JSONL文件 ~/.claude/projects/.cfolio将它们索引到本地SQLite数据库中，并为您提供：

• 全文搜索 在所有对话中，包括子代理内容
• 成本跟踪 --每日、每月、按型号、按项目
• 黑曜石出口 与Dataview/Bases兼容的frontmatter
• 自动生成的标题 从项目上下文和第一提示关键字
• 会话恢复 --直接移交给 claude --resume 按索引、slug或ID前缀
• MCP服务器 --从活动的Claude Code对话中搜索过去的会话
• 子代理链接 --与父会话链接的代理工件，未作为噪声索引

安装

pip install ccfolio

# With MCP server support
pip install ccfolio[mcp]

然后运行安装程序：

ccfolio config init

这将设置您的黑曜石保管库路径并配置自动同步挂钩。

自动同步

将此添加到您的 ~/.zshrc 在每次Claude Code会话后自动同步：

claude() {
    command claude "$@"
    ccfolio update --quiet
}

之后，每次退出时，ccfolio都会悄无声息地运行 claude 会议。

命令

浏览

ccfolio list                     # All sessions, newest first
ccfolio list --recent 20         # Last 20
ccfolio list --sort cost         # Most expensive first
ccfolio list --sort messages     # Most messages first
ccfolio list --favorites         # Only favorites
ccfolio list --model opus        # Filter by model
ccfolio list --after 2026-02-01  # After a date

搜索

ccfolio search "tailscale"
ccfolio search "hypothesis engine"
ccfolio search "CLAUDE.md"

搜索用户消息、助理响应、摘要、文件路径和子代理内容。支持部分单词-- ccfolio search "folio" 查找包含“ccfolio”的会话。

# Find sessions that touched a specific file
ccfolio files "CLAUDE.md"
ccfolio files "fetch_daily.py"

视图

ccfolio show #1                  # By list index
ccfolio show giggly-pondering    # By slug (partial match works)
ccfolio show 0c560d              # By ID prefix
ccfolio show #1 --raw            # Raw JSON record

简历

ccfolio resume #1                # Resume most recent session
ccfolio resume giggly-pondering  # Resume by slug
ccfolio resume #3 --fork         # Fork into a new session

结束会议并移交给 claude --resume。永远不要失去背景。

成本

ccfolio cost                     # Daily breakdown
ccfolio cost --monthly           # Monthly breakdown
ccfolio cost --model             # By model
ccfolio cost --project           # By project directory
ccfolio cost --after 2026-02-01  # Date range

显示估计的API成本以及您的使用情况。即使在Max订阅中，也有助于了解代币的去向。

统计

ccfolio stats                    # Overview: sessions, messages, tokens, cost
ccfolio stats --tools            # Tool usage breakdown

组织

ccfolio fav #3                   # Toggle favorite
ccfolio tag #3 infrastructure    # Add tags
ccfolio untag #3 infrastructure  # Remove tags
ccfolio rename #3 "My Title"     # Set custom title

出口到黑曜石

ccfolio export #3                # Export single session
ccfolio export --all             # Export all un-exported sessions
ccfolio export --all --force     # Re-export everything
ccfolio export --all --redact-paths  # Strip username from file paths

导出通过以下方式自动发生 ccfolio update。手动导出可一次性使用。

MCP服务器

ccfolio可以作为MCP服务器运行，让Claude在活动对话中搜索过去的会话。

增添 ~/.claude.json 在您的项目路径下：

{
  "projects": {
    "/Users/yourname": {
      "mcpServers": {
        "ccfolio": {
          "command": "/path/to/.venv/bin/ccfolio",
          "args": ["mcp"]
        }
      }
    }
  }
}

可用工具： search_sessions, list_recent_sessions, find_sessions_for_file, get_session_details, get_cost_summary.

会话ID快捷方式

您永远不需要键入完整的UUID：

黑曜石输出

导出的会话将通过frontmatter放置在您配置的vault路径中：

type: Claude-Session
session_id: "0c560d4a-..."
slug: giggly-pondering-gem
date: 2026-02-14
model: claude-opus-4-6
messages: 159
tool_calls: 50
cost_usd: 11.95
favorite: false
tags: [Claude-Session, Opus]

工具调用呈现为可折叠的标注。vault笔记的文件路径变为维基链接。使用子代理的会话会得到一个链接的子代理部分。

汽车标题

没有自定义的会话 /rename title在同步过程中自动获取基于主题的名称。ccfolio从项目目录、最常接触的文件路径和第一个提示关键字中提取主题。

格式： Topic1 + Topic2 + Topic3 （最多4个主题）。没有LLM调用，没有API成本。

需求

• Python 3.10+
• 克劳德代码(claude CLI）
• 黑曜石（可选，用于vault导出）

配置

ccfolio config show    # View current settings
ccfolio config init    # Interactive setup

配置文件： ~/.config/ccfolio/config.toml 数据库： ~/.config/ccfolio/ccfolio.db

许可证

麻省理工学院