AI Sessions

Searching and access your AI coding sessions from Claude Code, Gemini CLI, opencode, and OpenAI Codex.

GitHub
30
Try this MCPSponsored

Documentation

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

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

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