​
Quick Setup

​
1. Install

npm install -g @sessionbase/cli
This single package provides both the CLI and MCP server.

​
2. Authenticate

sessionbase login
Complete the OAuth flow in your browser with Github or Google. Authentication is shared between the CLI and MCP server automatically.

​
3. Configure Your AI Chat App

SessionBase currently supports Claude Code, Gemini CLI, Amazon Q Chat, and OpenAI Codex CLI.

​
Claude Code

Use the built-in MCP management command: 
claude mcp add sessionbase sessionbase-mcp --scope user

​
Gemini CLI

Add to your Gemini MCP configuration file at ~/.gemini/settings.json: 
{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

​
Amazon Q Chat

Add to your Q Chat MCP configuration at ~/.aws/amazonq/mcp.json: 
{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

​
OpenAI Codex CLI

Add to your Codex configuration at ~/.codex/config.toml: 
[mcp_servers.sessionbase]
command = "sessionbase-mcp"

​
4. Start Using

Once configured, you can use natural language in your AI chat:
  • “Push this to SessionBase”
  • “List my recent Claude code sessions”
  • “Push this session as private with the tags ‘API debugging‘“

​
Custom Slash Commands

Claude Code
mkdir -p ~/.claude/commands
echo "Use the sessionbase push_session tool to upload the current session" > ~/.claude/commands/upload.md
Now from claude you can simply run /upload and Claude will automatically generate metadata and push to SessionBase for you. You can also choose a different alias for your custom slash command by renaming upload.md to another file. For more details on custom slash commands, see the Anthropic docs.
Gemini CLI
mkdir -p ~/.gemini/commands 
touch ~/.gemini/commands/upload.toml
Then add this content to ~/.gemini/commands/upload.toml: 
# ~/.gemini/commands/upload.toml

description="Upload the current session to SessionBase"
prompt= """
Use the sessionbase push_session tool to upload the current session.

If you see a warning that the most recent session is outdated, ask the user to run `/chat save <tag>` to save a new checkpoint, then re-run /upload.
"""
Now you can run /upload from Gemini CLI to automatically push sessions to SessionBase. For more details on Gemini custom slash commands, see the Google Cloud docs. Amazon Q Chat and OpenAI Codex CLI do not currently support custom slash commands. You can still use natural language to push sessions (e.g., “Push this to SessionBase”), or use the CLI directly.

​
Available Commands

The MCP server exposes these tools through natural language:
  • Push Session: Share your current or recent AI coding sessions
  • List Sessions: Browse your local session history
  • Check Status: Verify authentication and connection

​
Troubleshooting

​
”No such file or directory” Error

If you see this error, ensure the package is installed globally: 
npm install -g @sessionbase/cli
which sessionbase-mcp  # Should show the binary path

​
Authentication Issues

Verify you’re logged in: 
sessionbase whoami
If not authenticated, run sessionbase login again.

​
Platform-Specific Session Detection

SessionBase can automatically push your current chat session for Claude Code and Amazon Q Chat. For the Gemini CLI, you must run the /chat save <TAG> command first, then SessionBase can push from there. The table below summarizes some of the platform specific behavior.
PlatformLocal StorageSessionBase Access
Claude CodeStores all session files automaticallyCan push current session or list/choose from directory
Gemini CLIOnly stores if you use /chat saveCan push saved sessions and list/choose from directory
Amazon Q ChatOnly stores most recent session per directory (unless /save <PATH> used)Can detect and push current session automatically
OpenAI Codex CLIStores all session files automaticallyCan push current session or list/choose from directory