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

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 <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