ccfolio

ccfolio

Index, search, and archive your Claude Code conversations. Tracks cost, exports to Obsidian, and lets you resume past sessions without losing context.

What It Does

Claude Code stores every conversation as JSONL files in ~/.claude/projects/. ccfolio indexes them into a local SQLite database and gives you:

• Full-text search across all conversations, including subagent content
• Cost tracking — daily, monthly, by model, by project
• Obsidian export with Dataview/Bases-compatible frontmatter
• Auto-generated titles from project context and first prompt keywords
• Session resume — hand off directly to claude --resume by index, slug, or ID prefix
• MCP server — search past sessions from within an active Claude Code conversation
• Subagent linking — agent artifacts linked to parent sessions, not indexed as noise

Install

pip install ccfolio

# With MCP server support
pip install ccfolio[mcp]

Then run setup:

ccfolio config init

This sets your Obsidian vault path and configures the auto-sync hook.

Auto-Sync

Add this to your ~/.zshrc to auto-sync after every Claude Code session:

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

After that, ccfolio runs silently every time you exit a claude session.

Commands

Browse

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

Search

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

Searches user messages, assistant responses, summaries, file paths, and subagent content. Supports partial words — ccfolio search "folio" finds sessions containing "ccfolio".

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

View

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

Resume

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

Resolves the session and hands off to claude --resume. Never loses context.

Cost

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

Shows estimated API cost alongside your usage. Useful for understanding where tokens go even on a Max subscription.

Stats

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

Organize

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

Export to Obsidian

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

Exports happen automatically via ccfolio update. Manual export available for one-offs.

MCP Server

ccfolio can run as an MCP server, letting Claude search past sessions from within an active conversation.

Add to ~/.claude.json under your project path:

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

Available tools: search_sessions, list_recent_sessions, find_sessions_for_file, get_session_details, get_cost_summary.

Session ID Shortcuts

You never need to type a full UUID:

| Format | Example | |--------|---------| | Index from last list | #1, #12 | | Slug (partial) | giggly, giggly-pondering | | ID prefix | 0c560d |

Obsidian Output

Exported sessions land in your configured vault path with frontmatter:

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]

Tool calls render as collapsible callouts. File paths to vault notes become wikilinks. Sessions that used subagents get a linked Subagents section.

Auto-Titles

Sessions without a custom /rename title get automatic topic-based names during sync. ccfolio extracts topics from the project directory, most-touched file paths, and first prompt keywords.

Format: Topic1 + Topic2 + Topic3 (max 4 topics). No LLM calls, no API cost.

Requirements

• Python 3.10+
• Claude Code (claude CLI)
• Obsidian (optional, for vault export)

Configuration

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

Config file: ~/.config/ccfolio/config.toml Database: ~/.config/ccfolio/ccfolio.db

License

MIT