Mantra

English

简体中文

English

简体中文

Appearance

How to Search and Manage Claude Code Session History ​

You've been coding with Claude Code for weeks. The tool is powerful — it reads your entire repo, understands architecture, and produces high-quality code changes. But then comes the moment: you need that OAuth token refresh logic you solved last Tuesday, and you can't find it.

This article covers where Claude Code stores sessions, the limitations of built-in features, and practical approaches to managing your session history.

Where Claude Code Stores Sessions ​

Claude Code stores all session data locally in JSON files. The default location is:

~/.claude/projects/<project-hash>/

Each project gets a unique hash based on the project path. Inside, you'll find .jsonl files — one per session. These files contain:

  • Every message (user and assistant)
  • Tool calls and their results
  • File read/write operations
  • Timestamps for each interaction

The data is human-readable. You can open any .jsonl file in a text editor and browse through the conversation.

The Limitations of Built-in Features ​

Claude Code provides --resume to continue your last session. But this has significant limitations:

1. Only the last session

--resume continues your most recent conversation. If you had a breakthrough solution three sessions ago, you're out of luck.

2. No search functionality

There's no way to search across sessions. If you remember solving an OAuth issue but can't remember which session it was in, you'll need to manually browse through files.

3. No cross-project indexing

Each project's sessions are isolated. If you solved a similar problem in another project last month, there's no way to find it from your current project.

4. No code state context

The session files contain the conversation, but not the code state at the time of the conversation. You can see what the AI suggested, but not what the codebase looked like when it made that suggestion.

Practical Approaches to Session Management ​

Approach 1: Manual File Browsing ​

The most straightforward approach is to browse the session files directly:

bash
# List all sessions for a project
ls ~/.claude/projects/<project-hash>/

# Search for a keyword across all sessions
grep -r "OAuth" ~/.claude/projects/

# View a specific session
cat ~/.claude/projects/<project-hash>/session-123.jsonl | jq .

Pros: No additional tools required, full access to raw data.

Cons: Time-consuming, no indexing, no code state correlation.

Approach 2: grep + Shell Scripts ​

You can create shell aliases to speed up common searches:

bash
# Add to .bashrc or .zshrc
alias cch-search='grep -r'
alias cch-list='ls ~/.claude/projects/ | head -20'

Pros: Faster than manual browsing, scriptable.

Cons: Still no indexing, results can be overwhelming with many sessions.

Approach 3: Dedicated Session Management Tools ​

Several tools have emerged to address this gap. They typically offer:

  • Full-text search across all sessions
  • Cross-project session indexing
  • Timeline visualization
  • Code state correlation

One such tool is Mantra, which provides:

  • Universal Search: Search across Claude Code, Cursor, Gemini CLI, and Codex sessions simultaneously
  • Time Travel: See the code state at the time of each conversation
  • Local-first: All data stays on your machine, zero network requests
  • Free: Core features are permanently free, no registration required

Best Practices for Session Management ​

Regardless of which approach you choose, here are some practices that help:

1. Use descriptive commit messages

When Claude Code makes changes, commit with a message that references the problem being solved. This creates a link between the session and the code change.

2. Keep a decision log

For significant architectural decisions, note them in a separate file (like DECISIONS.md) with a reference to the session where the decision was made.

3. Export important sessions

For particularly valuable sessions, export them to Markdown or a note-taking app. This ensures they're accessible even if the session files are lost.

4. Regular backups

The session files in ~/.claude/projects/ should be included in your backup strategy. They contain valuable knowledge that took significant time to generate.

The Bigger Picture: Session Management as a First-Class Concern ​

As AI coding tools become more central to development workflows, session management is evolving from an afterthought to a core concern.

The conversations you have with AI are not disposable — they're a record of your debugging process, architectural reasoning, and problem-solving approaches. Losing them means losing accumulated knowledge.

Whether you use manual methods, shell scripts, or dedicated tools, the key is to treat your AI coding sessions as valuable assets worth preserving and making searchable.

Mantra is a local-first AI coding session viewer that supports Claude Code, Cursor, Gemini CLI, and Codex. Core features are permanently free. Download from mantra.gonewx.com.