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.

*Mostly written using Claude Code.*

What It Does

Allow AI agents to search, list, and read your previous local coding sessions from multiple CLI coding agents. Useful for:

• Finding past solutions to similar problems
• Reviewing what you worked on recently
• Learning from previous conversations
• Resuming interrupted work

Demo

Resuming a Claude Code session in Codex CLI.

Installation

Quick Install

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

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

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

Custom installation directory:

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

Manual Download

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.

CLI Upload

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

Authentication

aisessions login

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

Displays a searchable list of your recent Claude Code sessions. Use 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 - Set a custom title for the uploaded transcript

MCP Usage

Once configured as an MCP server, you can ask:

• "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?"

How It Works

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)

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

MIT