sessionfs 0.1.0__tar.gz

sessionfs-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.eggs/
+
+# Node
+node_modules/
+.next/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# SessionFS local data (never commit user sessions)
+.sessionfs/
+
+# Internal — never commit to main
+docs/security/
+src/spikes/
+.agents/
+DOGFOOD.md

sessionfs-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+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

sessionfs-0.1.0/README.md

@@ -0,0 +1,155 @@
+# 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

sessionfs-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sessionfs"
+version = "0.1.0"
+description = "Capture, sync, and resume AI coding sessions across Claude Code, Codex, Gemini CLI, and Cursor."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [
+    { name = "SessionFS Contributors" },
+]
+keywords = ["ai", "agents", "sessions", "sync", "claude", "codex", "gemini", "cursor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "jsonschema>=4.20,<5.0",
+    "watchdog>=4.0,<6.0",
+    "typer>=0.12,<1.0",
+    "rich>=13.0,<14.0",
+    "httpx>=0.27,<1.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://sessionfs.dev"
+Repository = "https://github.com/sessionfs/sessionfs"
+Documentation = "https://sessionfs.dev/docs"
+Issues = "https://github.com/sessionfs/sessionfs/issues"
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.110,<1.0",
+    "uvicorn[standard]>=0.27,<1.0",
+    "sqlalchemy[asyncio]>=2.0,<3.0",
+    "asyncpg>=0.29,<1.0",
+    "alembic>=1.13,<2.0",
+    "python-multipart>=0.0.9",
+    "boto3>=1.34,<2.0",
+    "pydantic-settings>=2.0,<3.0",
+]
+dev = [
+    "sessionfs[server]",
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.23,<1.0",
+    "httpx>=0.27,<1.0",
+    "aiosqlite>=0.20,<1.0",
+    "ruff>=0.3,<1.0",
+    "mypy>=1.8,<2.0",
+    "build>=1.0,<2.0",
+]
+
+[project.scripts]
+sfs = "sessionfs.cli.main:cli_main"
+sfsd = "sessionfs.daemon.main:cli_main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sessionfs"]
+
+[tool.hatch.build]
+include = [
+    "src/sessionfs/**/*.py",
+    "src/sessionfs/spec/schemas/*.json",
+    "src/sessionfs/spec/examples/**/*",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

sessionfs-0.1.0/src/sessionfs/__init__.py

@@ -0,0 +1,3 @@
+"""SessionFS — Portable AI coding sessions."""
+
+__version__ = "0.1.0"

sessionfs-0.1.0/src/sessionfs/audit.py

@@ -0,0 +1,153 @@
+"""M9: Audit logging module.
+
+Provides structured audit logging to both local file (~/.sessionfs/audit.log)
+and the server audit_events table. All significant events are logged in JSON
+lines format.
+
+IMPORTANT: Never log session content, blob data, or API key values.
+Log metadata only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("sessionfs.audit")
+
+# Event types that can be logged
+EVENT_TYPES = frozenset({
+    "session_captured",
+    "session_synced",
+    "session_pulled",
+    "session_resumed",
+    "session_exported",
+    "session_handoff",
+    "session_deleted",
+    "session_forked",
+    "session_checkpoint_created",
+    "api_key_created",
+    "api_key_revoked",
+    "auth_failed",
+    "auth_success",
+    "sync_conflict",
+    "sync_error",
+})
+
+
+class AuditLogger:
+    """Writes audit events to a JSON lines file."""
+
+    def __init__(self, audit_log_path: Path | None = None) -> None:
+        if audit_log_path is None:
+            audit_log_path = Path.home() / ".sessionfs" / "audit.log"
+        self._path = audit_log_path
+
+    def _ensure_file(self) -> None:
+        """Ensure the audit log file exists with correct permissions."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        if not self._path.exists():
+            self._path.touch()
+            os.chmod(self._path, stat.S_IRUSR | stat.S_IWUSR)  # 0o600
+
+    def log(
+        self,
+        event_type: str,
+        *,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        source_ip: str | None = None,
+    ) -> None:
+        """Write an audit event to the log file.
+
+        Args:
+            event_type: One of the EVENT_TYPES constants.
+            user_id: User who performed the action (None for daemon events).
+            session_id: Session involved (if applicable).
+            details: Additional context (never include secret values).
+            source_ip: Client IP (server-side events only).
+        """
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "event_type": event_type,
+        }
+        if user_id is not None:
+            entry["user_id"] = user_id
+        if session_id is not None:
+            entry["session_id"] = session_id
+        if details:
+            entry["details"] = details
+        if source_ip:
+            entry["source_ip"] = source_ip
+
+        try:
+            self._ensure_file()
+            with open(self._path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, separators=(",", ":")) + "\n")
+        except OSError as e:
+            logger.error("Failed to write audit log: %s", e)
+
+    def read_events(
+        self,
+        event_type: str | None = None,
+        session_id: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Read audit events from the log file with optional filters."""
+        if not self._path.exists():
+            return []
+
+        events: list[dict[str, Any]] = []
+        with open(self._path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if event_type and event.get("event_type") != event_type:
+                    continue
+                if session_id and event.get("session_id") != session_id:
+                    continue
+                events.append(event)
+
+        # Return most recent first, limited
+        return events[-limit:][::-1]
+
+
+# Module-level default instance
+_default_logger: AuditLogger | None = None
+
+
+def get_audit_logger(audit_log_path: Path | None = None) -> AuditLogger:
+    """Get or create the default AuditLogger instance."""
+    global _default_logger
+    if _default_logger is None or audit_log_path is not None:
+        _default_logger = AuditLogger(audit_log_path)
+    return _default_logger
+
+
+def audit_event(
+    event_type: str,
+    *,
+    user_id: str | None = None,
+    session_id: str | None = None,
+    details: dict[str, Any] | None = None,
+    source_ip: str | None = None,
+) -> None:
+    """Convenience function to log an audit event using the default logger."""
+    get_audit_logger().log(
+        event_type,
+        user_id=user_id,
+        session_id=session_id,
+        details=details,
+        source_ip=source_ip,
+    )

sessionfs-0.1.0/src/sessionfs/cli/__init__.py

@@ -0,0 +1 @@
+"""SessionFS CLI."""