Session Buddy

Provides local, privacy-preserving session management for Claude Code sessions with automated lifecycle controls and memory.

python

1

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "lesleslie-session-buddy": {
      "command": "python",
      "args": [
        "-m",
        "session_buddy.server"
      ],
      "env": {
        "PYTHONPATH": "${PWD}"
      }
    }
  }
}

Session Buddy is a dedicated MCP server that provides comprehensive, local session management for Claude Code sessions. It automates lifecycle handling, memory persistence, and quality checkpoints so you can focus on productive development without juggling manual setup steps.

How to use

You interact with Session Buddy through an MCP client inside your Claude Code environment. Start a session to initialize project context, dependencies, and memory. Use checkpoints to assess quality and optimize workflows mid-session, then end the session to perform cleanup and capture learning for future reuse. Shortcuts are auto-generated after you start a session, giving you quick access to common actions across all projects.

How to install

Prerequisites you need before installing Session Buddy are Python 3.13+ and a working Claude Code environment. You also need a runnable MCP client to connect to the server.

From source, you can install the server with development dependencies or minimal production dependencies. Use either of the following workflows.

# Clone the repository
git clone https://github.com/lesleslie/session-buddy.git
cd session-buddy

# Install with all dependencies (development + testing)
uv sync --group dev

# Or install minimal production dependencies only
uv sync

# Or use pip (for production only)
pip install session-buddy

Configuration and starting the server

Configure the MCP client to target Session Buddy by providing a standard MCP configuration file in your project. You can run Session Buddy either from source with the Python module or via the script entry point if installed by pip.

{
  "mcpServers": {
    "session-buddy": {
      "command": "python",
      "args": ["-m", "session_buddy.server"],
      "cwd": "/path/to/session-buddy",
      "env": {
        "PYTHONPATH": "/path/to/session-buddy"
      }
    }
  }
}

Alternative script entry point

If you installed via pip, you can also use the script entry point to run Session Buddy directly.

{
  "mcpServers": {
    "session-buddy": {
      "command": "session-buddy",
      "args": [],
      "env": {}
    }
  }
}

Available tools

start

Comprehensive session initialization with project analysis and memory setup

checkpoint

Mid-session quality assessment with workflow analysis

end

Complete session cleanup with learning capture

status

Current session overview with health checks

store_reflection

Store insights with tagging and embeddings

quick_search

Fast overview search with count and top results

search_summary

Aggregated insights without individual result details

get_more_results

Pagination support for large result sets

search_by_file

Find conversations tied to a specific file

search_by_concept

Semantic search by concept with optional file context

search_code

Search code-related conversations

search_errors

Search error and failure discussions

search_temporal

Search using time expressions

reflection_stats

Stats about the reflection database