Metadata-Version: 2.4
Name: sessionfs
Version: 0.1.0
Summary: Capture, sync, and resume AI coding sessions across Claude Code, Codex, Gemini CLI, and Cursor.
Project-URL: Homepage, https://sessionfs.dev
Project-URL: Repository, https://github.com/sessionfs/sessionfs
Project-URL: Documentation, https://sessionfs.dev/docs
Project-URL: Issues, https://github.com/sessionfs/sessionfs/issues
Author: SessionFS Contributors
License: Apache-2.0
Keywords: agents,ai,claude,codex,cursor,gemini,sessions,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: jsonschema<5.0,>=4.20
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: rich<14.0,>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: watchdog<6.0,>=4.0
Provides-Extra: dev
Requires-Dist: aiosqlite<1.0,>=0.20; extra == 'dev'
Requires-Dist: alembic<2.0,>=1.13; extra == 'dev'
Requires-Dist: asyncpg<1.0,>=0.29; extra == 'dev'
Requires-Dist: boto3<2.0,>=1.34; extra == 'dev'
Requires-Dist: build<2.0,>=1.0; extra == 'dev'
Requires-Dist: fastapi<1.0,>=0.110; extra == 'dev'
Requires-Dist: httpx<1.0,>=0.27; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.8; extra == 'dev'
Requires-Dist: pydantic-settings<3.0,>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
Requires-Dist: python-multipart>=0.0.9; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.3; extra == 'dev'
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0; extra == 'dev'
Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == 'dev'
Provides-Extra: server
Requires-Dist: alembic<2.0,>=1.13; extra == 'server'
Requires-Dist: asyncpg<1.0,>=0.29; extra == 'server'
Requires-Dist: boto3<2.0,>=1.34; extra == 'server'
Requires-Dist: fastapi<1.0,>=0.110; extra == 'server'
Requires-Dist: pydantic-settings<3.0,>=2.0; extra == 'server'
Requires-Dist: python-multipart>=0.0.9; extra == 'server'
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0; extra == 'server'
Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == 'server'
Description-Content-Type: text/markdown

# SessionFS

**Stop re-prompting. Start resuming.**

SessionFS captures your AI coding sessions and makes them portable across tools and teammates.

Start a session in Claude Code, resume it in Codex. Push a session to the cloud, your teammate pulls it with full context — conversation history, workspace state, tool configs, and token usage. No copy-pasting. No re-explaining.

## Supported Tools

| Tool | Capture | Resume |
|------|---------|--------|
| Claude Code | Yes | Yes |
| Codex CLI | Yes | Yes |
| Gemini CLI | Yes | Yes |
| Cursor IDE | Yes | Capture-only |

## Quick Install

```bash
pip install sessionfs
```

Requires Python 3.10+. Installs two commands: `sfs` (CLI) and `sfsd` (daemon).

## Quick Start

```bash
# Start the daemon — it watches your tools automatically
sfs daemon start

# Use Claude Code, Codex, Gemini, or Cursor normally
# Sessions are captured in the background

# List captured sessions across all tools
sfs list

# Resume a Claude Code session in Codex
sfs resume ses_abc123 --in codex

# Or hand it off to a teammate
sfs push ses_abc123
```

See the full [Quickstart Guide](docs/quickstart.md) for detailed steps.

## How It Works

The `sfsd` daemon uses filesystem events (fsevents on macOS, inotify on Linux) to watch native AI tool session storage. When it detects new or updated sessions, it converts them into the `.sfs` format — a portable directory containing `manifest.json`, `messages.jsonl`, `workspace.json`, and `tools.json`.

Each tool has its own watcher:
- **Claude Code** — watches `~/.claude/projects/` JSONL files
- **Codex CLI** — watches `~/.codex/sessions/` rollout files, reads SQLite index
- **Gemini CLI** — watches `~/.gemini/tmp/*/chats/` JSON sessions
- **Cursor IDE** — reads `state.vscdb` SQLite database (capture-only, no write-back)

Sessions are indexed locally for fast browsing via the CLI. Cloud sync is opt-in; the daemon defaults to local-only.

## Commands

| Command | Description |
|---------|-------------|
| `sfs list` | List captured sessions with filtering and sorting |
| `sfs show <id>` | Show session details, messages, and cost estimates |
| `sfs resume <id> [--in TOOL]` | Resume a session in any supported tool |
| `sfs fork <id>` | Fork a session into a new independent session |
| `sfs checkpoint <id>` | Create a named checkpoint of a session |
| `sfs export <id>` | Export as `.sfs`, markdown, or Claude Code format |
| `sfs import` | Import sessions from any supported tool |
| `sfs push <id>` | Push a session to the cloud |
| `sfs pull <id>` | Pull a session from the cloud |
| `sfs daemon start\|stop\|status\|logs` | Manage the background daemon |
| `sfs config show\|set` | Manage configuration |
| `sfs admin reindex` | Re-extract metadata for all cloud sessions |

See the full [CLI Reference](docs/cli-reference.md) for options and examples.

## Cross-Tool Resume

```bash
# Start in Claude Code, resume in Codex
sfs resume ses_abc123 --in codex

# Start in Gemini, resume in Claude Code
sfs resume ses_def456 --in claude-code

# Cursor sessions can be resumed in any other tool
sfs resume ses_ghi789 --in gemini
```

SessionFS converts between native formats automatically — message roles, tool calls, thinking blocks, and workspace state are mapped across tools.

## Cloud Sync (Optional)

```bash
# Create an account
sfs auth signup --url https://api.sessionfs.dev

# Push a session
sfs push <session_id>

# Pull on another machine
sfs pull <session_id>
sfs resume <session_id>
```

See the [Sync Guide](docs/sync-guide.md) for setup, conflict handling, and self-hosted options.

## Self-Hosted Server

```bash
docker compose up -d
```

Starts the SessionFS API server, PostgreSQL, and web dashboard. See the [Sync Guide](docs/sync-guide.md#self-hosted) for full configuration.

## Web Dashboard

A browser-based interface for browsing and managing synced sessions. Accessible at `http://localhost:8000` when running the self-hosted server.

## Session Format

Sessions are stored as `.sfs` directories:
- `manifest.json` — identity, provenance, model info, stats
- `messages.jsonl` — conversation history with content blocks
- `workspace.json` — git state, files, environment
- `tools.json` — tool definitions and shell context

All file paths are relative to workspace root. Sessions are append-only — conflict resolution appends both sides rather than merging.

## Status

**v0.1.0 — Public Beta.** 429 tests passing.

What works today:
- Four-tool session capture (Claude Code, Codex, Gemini, Cursor)
- Cross-tool resume between Claude Code, Codex, and Gemini
- Browse, inspect, export, fork, and checkpoint sessions
- Cloud sync with push/pull and ETag conflict detection
- Self-hosted API server with auth, PostgreSQL, and S3/local storage
- Web dashboard for session management
- 12 security controls including secret detection, path traversal protection, and audit logging

On the roadmap:
- Team handoff workflows with notifications
- VS Code extension
- Additional tool watchers

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## License

Apache 2.0
