Ai Sessions MCP

🚀 AI Sessions MCP Server

An MCP server that makes sessions from Claude Code, OpenAI Codex, Gemini CLI and opencode available to any MCP compatible client.

This server allows AI agents to access and interact with your previous local coding sessions from multiple CLI coding agents, providing valuable insights and the ability to resume interrupted work.

🚀 Quick Start

The AI Sessions MCP Server enables AI agents to search, list, and read your previous local coding sessions from various CLI coding agents. It's useful for finding past solutions, reviewing recent work, learning from previous conversations, and resuming interrupted tasks.

✨ Features

• Session Access: Allows AI agents to access local coding sessions from multiple CLI agents.
• Search and List: Enables searching and listing of previous coding sessions.
• Resume Interrupted Work: Facilitates resuming interrupted coding sessions.
• Learning from Past Conversations: Helps in learning from previous interactions with AI agents.

📦 Installation

Quick Install

macOS, Linux, and Windows (Git Bash/WSL):

curl -fsSL https://aisessions.dev/install.sh | bash

This command installs the binary to ~/.aisessions/bin. Follow the on - screen instructions to add it to your PATH.

Custom installation directory:

INSTALL_DIR=/custom/path curl -fsSL https://aisessions.dev/install.sh | bash

Manual Download

You can download pre - built binaries from GitHub Releases.

Build from Source

Prerequisites: Go 1.25 or later

go build -o bin/aisessions ./cmd/ai-sessions

Setup

After installation, configure your MCP client to use the binary:

Claude Code

claude mcp add ai-sessions ~/.aisessions/bin/aisessions

Or if using a custom install location:

claude mcp add ai-sessions /path/to/aisessions

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.ai_sessions]
command = "~/.aisessions/bin/aisessions"

Claude Desktop

Add to your config file (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ai-sessions": {
      "command": "/Users/YOUR_USERNAME/.aisessions/bin/aisessions"
    }
  }
}

Replace YOUR_USERNAME with your actual username, or use your custom install path.

Restart Claude Desktop to activate.

💻 Usage Examples

CLI Upload

The ai-sessions binary includes a CLI tool for uploading Claude Code transcripts to aisessions.dev for sharing.

Authentication

aisessions login

This command opens your browser to generate a CLI token. The token is saved locally in ~/.aisessions/config.json.

Uploading Sessions

Interactive mode (no file argument):

aisessions upload

This displays a searchable list of your recent Claude Code sessions. Use the arrow keys to navigate and select a session to upload.

Direct mode (with file path):

aisessions upload /path/to/session.jsonl
aisessions upload /path/to/session.jsonl --title "Custom Title"

Options

• --title <title> - Set a custom title for the uploaded transcript

MCP Usage

Once configured as an MCP server, you can ask questions like:

• "Let's continue my latest sesion from Claude Code"
• "Show me my recent Codex sessions"
• "Search my sessions for authentication bugs"
• "How many times did Claude tell me I was absolutely right yesterday?"

🔧 Technical Details

The server reads session files stored locally by various CLI coding agents:

• Claude Code: ~/.claude/projects/[PROJECT_DIR]/*.jsonl
• Gemini CLI: ~/.gemini/tmp/[PROJECT_HASH]/chats/session-*.json
• OpenAI Codex: ~/.codex/sessions/ and ~/.codex/archived_sessions/
• opencode: ~/.local/share/opencode/storage/

When you ask your AI agent to list or search sessions, it automatically uses these agents to access your session history.

Available Tools

list_available_sources

Shows which AI CLI coding agents have sessions on your system.

list_sessions

Lists recent sessions from all projects (newest first).

Arguments:

• source (optional): Filter by claude, gemini, codex, or opencode
• project_path (optional): Filter by specific project directory
• limit (optional): Max results (default: 10)

Example: {"source": "claude", "limit": 20}

search_sessions

Searches session content using BM25 ranking. Returns results sorted by relevance score with contextual snippets.

Arguments:

• query (required): Search term (supports multiple keywords)
• source (optional): Filter by source
• project_path (optional): Filter by project
• limit (optional): Max results (default: 10)

Example: {"query": "authentication bug"}

Returns: Each match includes:

• session: Session metadata (ID, source, project, timestamp)
• score: Relevance score (higher = more relevant)
• snippet: Contextual excerpt (~300 chars) showing where the match occurred

get_session

Retrieves full session content with pagination.

Arguments:

• session_id (required): Session ID from list results
• source (required): Which coding agent created it
• page (optional): Page number (default: 0)
• page_size (optional): Messages per page (default: 20)

📚 Documentation

Development

To keep formatting consistent and catch regressions early:

• Install pre-commit and run pre-commit install to enable hooks (gofmt, go vet, go test).
• All pushes and pull requests run the GitHub Actions workflow (.github/workflows/build.yml), which checks formatting, runs go vet, builds the binary, and executes go test -cover ./....

📄 License

This project is licensed under the MIT license.