AI Sessions MCP Server

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

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

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 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 ` - Set a custom title for the uploaded transcript
• `--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