GitHub - yoavf/ai-sessions-mcp: MCP server for searching and accessing your AI coding sessions from Claude Code, Gemini CLI, opencode, and OpenAI Codex. Also an uploader for aisessions.dev

GitHub

5 min read Original article ↗

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

Mostly written using Claude Code.

What It Does

Allows 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

AI Sessions MCP demo
Resuming a Claude Code session in Codex CLI.

Installation

Quick Install

macOS (Intel and Apple Silicon), Linux (amd64 and arm64, including WSL), and Windows amd64 (Git Bash):

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:

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

Manual Download

Download pre-built binaries from GitHub Releases.

Build from Source

Prerequisites: Go 1.25.13 or later

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

Setup

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

Claude Code CLI

claude mcp add --scope user --transport stdio ai-sessions -- ~/.aisessions/bin/aisessions

Or if using a custom install location:

claude mcp add --scope user --transport stdio ai-sessions -- /path/to/aisessions

Verify the connection with claude mcp get ai-sessions.

Codex CLI and ChatGPT desktop app

Add the server from the CLI:

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

Codex CLI and the ChatGPT desktop app share ~/.codex/config.toml, so the server is available in both after you restart the desktop app. In ChatGPT, open Settings → MCP servers to check its status, or type /mcp in the composer.

For manual configuration, use an absolute path (the command is launched directly, without shell expansion):

[mcp_servers.ai_sessions]
command = "/Users/YOUR_USERNAME/.aisessions/bin/aisessions"

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

Claude Desktop

Add to the config file opened from 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, then open Developer settings or + → Connectors in a conversation to check the connection. Claude Desktop also supports packaged .mcpb extensions, but direct configuration remains useful for a standalone downloaded binary.

CLI Upload

The aisessions binary includes a CLI tool for uploading supported local agent transcripts to aisessions.dev for sharing.

Authentication

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

Uploading Sessions

Interactive mode (no file argument):

Displays a searchable list of recent upload-compatible sessions from Claude Code, Codex, Gemini CLI, Mistral Vibe, and GitHub Copilot CLI. Use arrow keys to navigate and select a session to upload. opencode sessions remain available through the MCP server but are omitted from the upload picker because its current store is a shared SQLite database rather than one transcript file per session.

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
  • --url <url> - Override the API URL (https://aisessions.dev or a local development server)

MCP Usage

Once configured as an MCP server, you can ask:

  • "Let's continue my latest session 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-*.jsonl (plus legacy .json recordings)
  • OpenAI Codex: ~/.codex/sessions/ and ~/.codex/archived_sessions/
  • opencode: ~/.local/share/opencode/opencode.db (plus the legacy storage/ JSON tree)
  • Mistral Vibe: ~/.vibe/logs/session/
  • GitHub Copilot CLI: ~/.copilot/session-state/[SESSION_ID]/events.jsonl (plus legacy flat JSONL files)

When you ask your AI agent to list or search sessions, the server reads these local stores through source-specific adapters; it does not launch the agent CLIs.

Available Tools

list_available_sources

Shows which AI CLI source adapters are available from the running server.

list_sessions

Lists recent sessions from all projects (newest first).

Arguments:

  • source (optional): Filter by claude, gemini, codex, opencode, mistral, or copilot
  • 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).
  • Pushes to main and pull requests targeting main 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