Quickstart

Time: Under 2 minutes. Prerequisites: Python 3.10+

1. Install

pip install sessionfs

This installs two commands: sfs (CLI) and sfsd (daemon).

2. Initialize

sfs init

The interactive wizard auto-detects which AI tools you have installed, sets up the daemon, and optionally configures cloud sync. You can also skip this and configure manually.

3. Start the Daemon

sfs daemon start

The daemon watches your AI tools in the background using filesystem events (not polling). Negligible CPU overhead.

It automatically detects and captures sessions from all eight supported tools:

• Claude Code
• Codex CLI
• Gemini CLI
• Copilot CLI
• Cursor IDE
• Amp
• Cline
• Roo Code

4. Use Your Tools Normally

No behavior change required. Just use your AI coding tools the way you always do. SessionFS captures sessions silently in the background.

5. Browse Your Sessions

sfs list

                     Sessions (12)
┌──────────────┬─────────────┬────────┬──────────┬───────────────────────┐
│ ID           │ Tool        │ Model  │ Messages │ Title                 │
├──────────────┼─────────────┼────────┼──────────┼───────────────────────┤
│ ses_a1b2c3d4 │ claude-code │ opus-4 │       47 │ Debug auth flow       │
│ ses_e5f6a7b8 │ gemini-cli  │ gem-2  │       23 │ Add rate limiting     │
│ ses_c9d0e1f2 │ codex-cli   │ codex  │       31 │ Refactor DB schema    │
│ ses_g3h4i5j6 │ cursor      │ son4.5 │        8 │ Fix CI pipeline       │
└──────────────┴─────────────┴────────┴──────────┴───────────────────────┘

Filter and sort:

sfs list --since 24h
sfs list --tool claude-code --sort tokens

6. Resume a Session

Resume in the same tool or a different one:

# Resume in Claude Code (default)
sfs resume ses_a1b2c3d4

# Resume a Cursor session in Codex
sfs resume ses_g3h4i5j6 --in codex

# Resume any session in Gemini CLI
sfs resume ses_e5f6a7b8 --in gemini

Four tools support resume: Claude Code, Codex, Gemini CLI, and Copilot CLI. Sessions from capture-only tools (Cursor, Amp, Cline, Roo Code) can be resumed in any of the four bidirectional tools. See Installation for details on supported tools.

---

Troubleshooting

Run the health check first:

sfs doctor

This runs 8 diagnostic checks and auto-repairs common issues (broken indexes, stale locks, permission problems).

“No sessions found” after sfs list

Make sure the daemon is running and at least one AI tool has been used:

sfs daemon status

If the daemon shows 0 sessions, try importing existing sessions:

sfs import --from claude-code

Daemon won’t start

Check the logs:

sfs daemon logs

Common causes:

• Another sfsd process is already running (ps aux | grep sfsd)
• The ~/.sessionfs/ directory doesn’t exist or isn’t writable

Daemon is running but not detecting sessions

sfs daemon status

If a watcher shows degraded or broken, check sfs daemon logs --lines 100.

What’s Next

Once you’re capturing sessions, explore these features:

# Search across all sessions
sfs search "rate limiting"

# Get a quick summary of any session
sfs summary ses_abc

# Audit a session for hallucinations
sfs audit ses_abc --model gpt-4o

# Set up project knowledge base and wiki
sfs project init
sfs project edit

# Install MCP server (22 tools) so AI agents
# can search sessions, query the knowledge base, and read wiki pages
sfs mcp install --for claude-code

# Enable automatic cloud sync
sfs auth login
sfs sync auto --mode all

# Hand off a session to a teammate
sfs handoff ses_abc --to colleague@company.com

See the full CLI Reference for all commands and options.