context-forge-cli 0.1.0__py3-none-any.whl

context_forge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: context-forge-cli
+Version: 0.1.0
+Summary: Session manager and context bridge for agentic CLI tools
+Project-URL: Homepage, https://github.com/emmver/contextforge
+Project-URL: Repository, https://github.com/emmver/contextforge
+Project-URL: Bug Tracker, https://github.com/emmver/contextforge/issues
+Author-email: emmver <emmvereroudakis@gmail.com>
+License: MIT
+Keywords: ai,claude,cli,codex,context,sessions,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: anthropic>=0.89.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: rich>=14.3.3
+Requires-Dist: sqlite-utils>=3.39
+Requires-Dist: textual>=8.2.2
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# ContextForge
+
+**Session manager and context bridge for agentic CLI tools.**
+
+ContextForge (`cf`) tracks sessions from Claude Code, Codex, altimate-code, and other
+agentic CLI tools. It generates plain-English summaries of each session and can compact
+and transfer context from one or more sessions into a new session — within the same tool
+or across different tools.
+
+## What it does
+
+- **Discovers sessions** from Claude Code (`~/.claude/projects/`), Codex (`~/.codex/state_5.sqlite`), and altimate-code (`~/.local/share/altimate-code/`)
+- **Generates summaries** of what each session accomplished (with optional Claude API integration)
+- **Compacts context** intelligently, reducing multi-turn conversations to a token-efficient ContextBundle
+- **Transfers context** across tools and sessions (Claude Code → Codex, Codex → altimate-code, etc.)
+- **Provides a TUI dashboard** to browse and manage sessions interactively
+
+## Prerequisites
+
+- **Python 3.13+** (ContextForge requires Python 3.13 or later)
+- **uv** or **pipx** (for installation as a tool)
+- At least one of: Claude Code, Codex, or altimate-code installed and with session history
+
+## Install
+
+### Using `uv` (recommended)
+```bash
+uv tool install context-forge-cli
+```
+
+### Using `pipx`
+```bash
+pipx install context-forge-cli
+```
+
+### From source (development)
+```bash
+git clone https://github.com/emmver/contextforge.git
+cd contextforge
+uv sync
+uv run cf --help
+```
+
+### Verify installation
+```bash
+cf --help      # Should show the CLI with all commands
+cf config      # Show or edit configuration
+```
+
+## Quick Start
+
+### 1. Scan for sessions
+```bash
+cf scan              # discover and index sessions from all installed tools
+```
+This reads tool-native storage and builds a local SQLite index at `~/.contextforge/contextforge.db`.
+First run typically takes a few seconds depending on session count.
+
+### 2. List and explore sessions
+```bash
+cf ls                # list all recent sessions (with summaries if available)
+cf ls --format json  # machine-readable output
+cf show <id>         # show full detail + summary for a specific session
+```
+
+### 3. Generate summaries (optional)
+```bash
+cf summarize --all                 # generate summaries for all unsummarized sessions
+cf summarize <id>                  # refresh summary for a single session
+cf summarize --all --force         # regenerate all summaries (e.g., after config change)
+```
+Summaries require an Anthropic API key (see [Configuration](#configuration) below).
+
+### 4. Launch the dashboard
+```bash
+cf dashboard         # interactive TUI with live session browser
+```
+
+### 5. Transfer context to a new session
+```bash
+# Preview the context bundle
+cf compact <session-id>
+
+# Inject context into a new Claude Code session
+cf transfer <session-id> --to claude_code --execute
+
+# Inject into Codex with richer context
+cf transfer <session-id> --to codex --strategy key_messages --execute
+```
+
+## Context Transfer
+
+```bash
+# Preview: compact a session into a ContextBundle and display it
+cf compact <session-id>
+
+# Save a bundle to the DB for later reuse
+cf compact <session-id> --save
+
+# Preview: show the exact command that would inject context into a new Codex session
+cf transfer <session-id> --to codex
+
+# Execute: launch a new Codex session with context injected
+cf transfer <session-id> --to codex --execute
+
+# Multi-session bundle → altimate-code, richer key_messages strategy
+cf transfer <id1> <id2> --to altimate-code --strategy key_messages --execute
+
+# Resume an existing session with injected context
+cf transfer <id> --to claude_code --session <existing-session-id> --execute
+
+# Machine-readable output
+cf transfer <id> --to codex --format json
+```
+
+### Injection methods
+
+| Method | When used | How |
+|---|---|---|
+| `system_prompt` | New session, small context (≤4k tokens) | Passed via `--system-prompt` flag |
+| `resume` | Continuing an existing session | `--resume` / `resume` / `run -s` |
+| `fork` | Branch from existing session | `fork` / `--fork` |
+| `file` | Any context >4k tokens | Writes `CONTEXT.md` to target dir; system prompt references it |
+
+The method is chosen automatically based on token count and whether a target session is specified. Override with `--method`.
+
+## Compaction Strategies
+
+| Strategy | Tokens | Best for |
+|---|---|---|
+| `summary_only` | ~100–300 per session | Default; maximum token efficiency |
+| `key_messages` | 1k–8k | Richer context; scores messages by importance |
+| `full_recent` | Up to budget | Same-tool transfers; preserves recent conversation |
+
+## Supported Tools
+
+| Tool | Discovery | Inject method |
+|---|---|---|
+| Claude Code (CLI) | `~/.claude/projects/` JSONL | `--system-prompt` / `--resume` |
+| Claude Desktop | `~/Library/Application Support/Claude/local-agent-mode-sessions/` | `--system-prompt` |
+| Codex | `~/.codex/state_5.sqlite` | `resume` / `fork` |
+| altimate-code | `~/.local/share/altimate-code/opencode.db` | `run -s` / `import` |
+
+## Session Summaries
+
+ContextForge generates plain-English summaries of what each session accomplished.
+
+```bash
+cf summarize <id>        # generate or refresh summary for one session
+cf summarize --all       # bulk-generate summaries for all sessions
+cf summarize --all --force  # regenerate even existing ones
+
+# Scan + summarize in one step
+cf scan --summarize
+```
+
+**How summaries work:**
+1. **Codex** — reuses pre-computed `stage1_outputs.rollout_summary` when available (zero LLM cost)
+2. **All tools** — calls the Claude API (Haiku model) to produce a 3–5 sentence summary
+3. **No API key** — falls back to showing the first user message as a preview
+
+Summaries are cached in the local SQLite index and shown in `cf ls` and `cf show`.
+
+## Configuration
+
+Config file: `~/.contextforge/config.toml` (created on first run)
+
+### Manage config from CLI
+```bash
+cf config show         # display current config
+cf config set llm.api_key sk-ant-...
+cf config set compactor.default_strategy key_messages
+```
+
+### Full reference
+```toml
+[llm]
+api_key = "sk-ant-..."                    # optional; enables LLM summarization
+model = "claude-haiku-4-5-20251001"       # or any Claude model
+
+[compactor]
+default_strategy = "summary_only"         # summary_only | key_messages | full_recent
+default_token_budget = 4096               # max tokens per compacted session
+
+[scanner]
+max_sessions_per_tool = 200               # limit sessions indexed per tool
+```
+
+### Notes on configuration
+
+- **Without API key**: Summaries fall back to showing the first user message (no LLM cost)
+- **With API key**: Summaries use Claude Haiku via the Anthropic API (~0.30¢ per summary)
+- **Token budget**: Controls how aggressively context is compacted; higher = richer context
+- **Strategies**: See [Compaction Strategies](#compaction-strategies) for details on each
+
+## Storage
+
+ContextForge stores its index at `~/.contextforge/contextforge.db` (SQLite).
+It **never modifies** tool-native storage. All source files are read-only.
+
+## Agent / Machine Usage
+
+All structured commands support `--format json`:
+
+```bash
+cf ls --format json
+cf show <id> --format json
+cf compact <id> --format json
+```
+
+See [AGENTS.md](AGENTS.md) for contribution guidelines and [PLAN.md](PLAN.md) for development status.
+
+## TUI Dashboard
+
+```bash
+cf dashboard
+```
+
+A full-screen Textual dashboard with live session browsing, filtering, and analytics.
+
+```
+┌ Sessions ────────────────┬ Detail ─────────────────────────┐
+│ 🔵 CC    utastar   1.2M  │ utastar_thesis                  │
+│ 🟢 Codex dataset    45k  │                                 │
+│ 🟣 Alt   BigQuery   12k  │ Tool      Claude Code           │
+│ 🔵 CC    jira-mcp  890k  │ CWD       ~/Github/utastar_...  │
+│ ...                      │ Tokens    1.2M                  │
+│                          │ Created   2026-03-10 09:14 UTC  │
+│                          │ Updated   2026-04-03 22:41 UTC  │
+│                          │                                 │
+│                          │ ── Summary ──                   │
+│                          │                                 │
+│                          │ Worked on UTASTAR ensemble      │
+│                          │ pruning framework...            │
+└──────────────────────────┴─────────────────────────────────┘
+ Sessions — CC:12 │ Codex:4 │ Alt:3 │ Total:19 │ 129M tok   14:32:01
+```
+
+### Key bindings
+
+| Key | Action |
+|---|---|
+| `a` | Analytics dashboard (tool charts, activity sparkline, top projects) |
+| `x` | Per-turn token breakdown for selected session |
+| `/` | Toggle live filter bar (text search + tool buttons) |
+| `r` | Rescan all tools |
+| `s` | Summarize selected session |
+| `t` | Open transfer modal (choose tool + strategy) |
+| `c` | Compact selected session and preview bundle |
+| `q` | Quit |
+| `↑↓` | Navigate sessions |
+
+### Analytics modal (`a`)
+
+Shows aggregate stats with configurable time windows:
+
+- **W** = last 7 days, **M** = 30 days, **H** = 6 months, **Y** = 1 year
+- Sessions and token usage per tool (unicode bar charts)
+- Activity sparkline over time
+- Top 5 projects by session count
+
+### Live filter (`/`)
+
+Press `/` to open the filter bar above the session list:
+- Type to filter by title or project path (instant, no DB re-query)
+- Click **All / CC / Codex / Alt** to filter by tool
+- Combine text + tool filters; match count shown in the status bar
+- Press `ESC` to clear and close
+
+### Transfer modal (`t`)
+
+Press `t` on any session to open the transfer panel. Choose:
+- **Target tool** — Claude Code, Codex, or altimate-code
+- **Strategy** — `summary_only`, `key_messages`, or `full_recent`
+- **Preview** — shows the exact shell command (no side effects)
+- **Execute** — builds the bundle and launches the target tool
+
+## Troubleshooting
+
+### `command not found: cf`
+- **Cause**: Tool not in PATH after installation
+- **Fix**: Restart your shell, or reinstall: `uv tool install contextforge --force`
+
+### `RuntimeError: no sessions found` or empty `cf ls`
+- **Cause**: No sessions discovered from installed tools
+- **Fix**: Run `cf scan` first; check that you have Claude Code/Codex/altimate-code with session history
+
+### `ANTHROPIC_API_KEY not set` warning
+- **Cause**: No API key configured for summaries
+- **Fix**: Set it via `cf config set llm.api_key sk-ant-...` or set `ANTHROPIC_API_KEY` env var
+- **Note**: Summaries are optional; you can still use ContextForge without API keys
+
+### Session not appearing after tool update
+- **Cause**: Tool storage location changed or was not yet indexed
+- **Fix**: Run `cf scan` again to reindex all tools
+
+### `cf dashboard` crashes or displays incorrectly
+- **Cause**: Terminal size too small or unsupported terminal type
+- **Fix**: Resize terminal to at least 80x24; try a different terminal emulator
+
+### Database locked / concurrent access error
+- **Cause**: Two `cf` commands running at once
+- **Fix**: Wait for the first command to finish, or delete `~/.contextforge/contextforge.db` and run `cf scan` again
+
+## Development
+
+```bash
+uv sync              # install all dependencies including dev
+uv run pytest        # run tests
+uv run cf --help     # run CLI locally
+uv tool install . --force  # test local installation
+```

context_forge_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+contextforge/__init__.py,sha256=L5NnW7jpnDQrAhnqTWSzW-bk2Bp8TXpFK1-SmQXI2QE,104
+contextforge/cli.py,sha256=OIHjV_pL4fKCvnn-2bQwza8NOUplptSfASPg4yzQmjA,18685
+contextforge/adapters/__init__.py,sha256=HGIFdC_tNpX_QOPrePwU5cEVBhp3Hsh6Sihwb23HdTk,171
+contextforge/adapters/altimate_code.py,sha256=aFo3FvO6XdN8eORnU_F8PbEB7rTTB2quIyU381AHE1E,5967
+contextforge/adapters/base.py,sha256=q3_pn0XoDV_r2GkuSzuRof0SSqynHqiaCAe4piq3tGs,1355
+contextforge/adapters/claude_code.py,sha256=RcFucjQGuDztU_BFVdm-O7mQ12FHFSD6y9AUrYJg4X4,15315
+contextforge/adapters/claude_desktop.py,sha256=uXJgMt2BdbhkwU9DMXhik--kb-RNKqxTdMc4Z9O-9lc,11957
+contextforge/adapters/codex.py,sha256=WhLHOyZZM4KI-G2hEvsqq9PYOjuCyI2Zo8S9ircZtf8,8005
+contextforge/adapters/registry.py,sha256=u0R7SwEHwCwEZBSSDv8zg-49OqRM2Gc7vRvL4kWd9iE,1093
+contextforge/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contextforge/core/analytics.py,sha256=qffm7oqfmosU6XPUftbf68AOvDrylrxBR4rJyLhvoXU,7056
+contextforge/core/compactor.py,sha256=ub1eU31fNLXl9_-hLW_YeoHT9JTyIytB2Nh4HlmU7hA,5482
+contextforge/core/db.py,sha256=1d8HQZEwiEvotByCWWgDyOPJT744lh6vb77XURjscco,5205
+contextforge/core/injector.py,sha256=_4UeJn-hJfs2-cZcqScpJjEBZCOnKc7odcKDYZTj55I,2670
+contextforge/core/scanner.py,sha256=Wbgp4TJ7SmFf-f6ZY6aKlmL_wUTUCFhuMTEjYYPPUhQ,2487
+contextforge/core/summarizer.py,sha256=4qPzBHfLno1C_nyiTGM_It_0vm3alcsYCZKueMQITlA,4631
+contextforge/core/token_analyzer.py,sha256=HKktdSye1Jy8XJ_LktLfVBg2ElYTsaEy9mZb_1vDnTw,2398
+contextforge/models/__init__.py,sha256=abmJPhl_AVrhA526IYpF7NqWTy8MBH5jVSAxwOLzuL4,151
+contextforge/models/config.py,sha256=TbqPaOV_oF3kvVFJDGIADRuJid-9UsGq2QQyb8BP_-g,953
+contextforge/models/session.py,sha256=Q3bT3j6r4LdKgV0Yq7DH1RUJPIu1KF6cyJG3iR7qPss,878
+contextforge/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contextforge/tui/app.py,sha256=-3ETEJjXAsigVvvB65wpXMBt4L4NiqM4Nj8cS1dBFQ8,7774
+contextforge/tui/styles.tcss,sha256=hiSe3g2OJFME8QAHVHbtvgaB8_BNYfwKvQUmZzbWHHc,945
+contextforge/tui/widgets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contextforge/tui/widgets/session_detail.py,sha256=xjnbD67Es7du7S3q960rZR31erwkNjX-KfS0QTFNZLw,6567
+contextforge/tui/widgets/session_table.py,sha256=s-E1j629eY5MgO3IaxOWs03YP6oToaLBXur27h4EV80,9782
+contextforge/tui/widgets/stats_panel.py,sha256=N5rPdrI0_JNsJaggZ30y6eVNGX_eRbHVT40dOm61FiY,12277
+contextforge/tui/widgets/status_bar.py,sha256=uAtgZWA8ah8CynoaEgKqhGYH7MHq6Ih-Nw3_go3-Dkg,3068
+contextforge/tui/widgets/tokens_panel.py,sha256=xsLB-by3ta1zKts9lGSUConAKMHcpVDOyq6BD-utTQk,4669
+contextforge/tui/widgets/transfer_panel.py,sha256=Qrgkt1-MpzRHWuwNyu2ErM26IRl0yaAMdbx3XMS7Lqk,4145
+contextforge/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contextforge/utils/display.py,sha256=bagZgpZ6WGki2THNHA8lfg9ITqM8W0q_M6Os-pgwFHk,3111
+contextforge/utils/tokens.py,sha256=UVGz-vvmCIxMgnRPn1T53v2ZdKMmxKhoJcc1qbmjpDQ,414
+context_forge_cli-0.1.0.dist-info/METADATA,sha256=_3IFKAuY9oSBaEqZXk7-tYOCBBOwWWNIkjOE_TxDCHQ,12600
+context_forge_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+context_forge_cli-0.1.0.dist-info/entry_points.txt,sha256=nPN0PWb85KCPXqFp4opmBsNejdCHyl7rK_cREsu4r7A,44
+context_forge_cli-0.1.0.dist-info/RECORD,,

context_forge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

context_forge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cf = contextforge.cli:app

contextforge/__init__.py

@@ -0,0 +1,3 @@
+"""ContextForge — session manager and context bridge for agentic CLI tools."""
+
+__version__ = "0.1.0"

contextforge/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .registry import get_adapter, get_all_adapters, get_available_adapters, ADAPTERS
+
+__all__ = ["get_adapter", "get_all_adapters", "get_available_adapters", "ADAPTERS"]

contextforge/adapters/altimate_code.py

@@ -0,0 +1,179 @@
+"""Adapter for altimate-code (opencode) sessions."""
+from __future__ import annotations
+
+import json
+import shlex
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+import tiktoken
+
+from contextforge.adapters.base import ToolAdapter
+from contextforge.models.session import Message, Session
+
+_OPENCODE_DB = Path.home() / ".local" / "share" / "altimate-code" / "opencode.db"
+
+
+def _count_tokens(text: str) -> int:
+    """Count tokens in text using tiktoken for Claude models."""
+    try:
+        enc = tiktoken.encoding_for_model("claude-3-5-sonnet-20241022")
+        return len(enc.encode(text))
+    except Exception:
+        # Fallback: rough estimate (~4 chars per token)
+        return len(text) // 4
+
+
+class AltimateCodeAdapter(ToolAdapter):
+    tool_name = "altimate_code"
+    default_paths = [_OPENCODE_DB]
+
+    def discover_sessions(self) -> list[Session]:
+        if not _OPENCODE_DB.exists():
+            return []
+
+        sessions: list[Session] = []
+        try:
+            conn = sqlite3.connect(str(_OPENCODE_DB))
+            conn.row_factory = sqlite3.Row
+            cur = conn.cursor()
+            cur.execute(
+                """
+                SELECT id, title, directory, time_created, time_updated
+                FROM session
+                ORDER BY time_updated DESC
+                """
+            )
+            rows = cur.fetchall()
+            conn.close()
+        except sqlite3.Error:
+            return []
+
+        for row in rows:
+            try:
+                created = datetime.fromtimestamp(row["time_created"] / 1000, tz=timezone.utc)
+                updated = datetime.fromtimestamp(row["time_updated"] / 1000, tz=timezone.utc)
+            except (TypeError, ValueError):
+                now = datetime.now(timezone.utc)
+                created = updated = now
+
+            # Calculate token count from session messages
+            session_id = str(row["id"])
+            token_count = self._count_session_tokens(session_id)
+
+            sessions.append(
+                Session(
+                    id=session_id,
+                    tool=self.tool_name,
+                    title=row["title"] or None,
+                    cwd=row["directory"] or None,
+                    created_at=created,
+                    updated_at=updated,
+                    raw_path=str(_OPENCODE_DB),
+                    status="unknown",
+                    token_count=token_count,
+                )
+            )
+
+        return sessions
+
+    def load_messages(self, session_id: str) -> list[Message]:
+        if not _OPENCODE_DB.exists():
+            return []
+
+        try:
+            conn = sqlite3.connect(str(_OPENCODE_DB))
+            conn.row_factory = sqlite3.Row
+            cur = conn.cursor()
+            # Join message + part to get full content
+            cur.execute(
+                """
+                SELECT m.role, p.type as part_type, p.content, m.time as ts
+                FROM message m
+                LEFT JOIN part p ON p.message_id = m.id
+                WHERE m.session_id = ?
+                ORDER BY m.time ASC, p.id ASC
+                """,
+                (session_id,),
+            )
+            rows = cur.fetchall()
+            conn.close()
+        except sqlite3.Error:
+            return []
+
+        messages: list[Message] = []
+        current_role: str | None = None
+        current_parts: list[str] = []
+        current_ts: datetime | None = None
+
+        def flush():
+            nonlocal current_role, current_parts, current_ts
+            if current_role and current_parts:
+                content = "\n".join(p for p in current_parts if p)
+                if content:
+                    messages.append(
+                        Message(
+                            role=current_role,
+                            content=content,
+                            timestamp=current_ts,
+                        )
+                    )
+            current_role = None
+            current_parts = []
+            current_ts = None
+
+        for row in rows:
+            role = row["role"]
+            if role not in ("user", "assistant"):
+                continue
+
+            if role != current_role:
+                flush()
+                current_role = role
+                try:
+                    current_ts = datetime.fromtimestamp(row["ts"] / 1000, tz=timezone.utc)
+                except (TypeError, ValueError):
+                    current_ts = None
+
+            part_type = row["part_type"] or ""
+            content = row["content"] or ""
+
+            if part_type in ("text", "reasoning") and content:
+                if isinstance(content, str):
+                    try:
+                        parsed = json.loads(content)
+                        if isinstance(parsed, dict):
+                            content = parsed.get("text", str(parsed))
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+                current_parts.append(str(content).strip())
+
+        flush()
+        return messages
+
+    def _count_session_tokens(self, session_id: str) -> int:
+        """Count total tokens in a session."""
+        messages = self.load_messages(session_id)
+        total = 0
+        for msg in messages:
+            total += _count_tokens(msg.content)
+        return total
+
+    def build_inject_command(
+        self,
+        context: str,
+        target_session_id: str | None = None,
+        cwd: str | None = None,
+        method: str = "system_prompt",
+    ) -> str:
+        safe_ctx = shlex.quote(context)
+        if method == "resume" and target_session_id:
+            return f"altimate-code run -s {target_session_id} {safe_ctx}"
+        if method == "fork" and target_session_id:
+            return f"altimate-code run --fork -s {target_session_id} {safe_ctx}"
+        # New session
+        cmd = f"altimate-code run {safe_ctx}"
+        if cwd:
+            cmd = f"cd {shlex.quote(cwd)} && {cmd}"
+        return cmd

contextforge/adapters/base.py

@@ -0,0 +1,44 @@
+"""Abstract base class for all tool adapters."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from contextforge.models.session import Message, Session
+
+
+class ToolAdapter(ABC):
+    tool_name: str
+    default_paths: list[Path]
+
+    @abstractmethod
+    def discover_sessions(self) -> list[Session]:
+        """Return a list of sessions discovered for this tool."""
+        ...
+
+    @abstractmethod
+    def load_messages(self, session_id: str) -> list[Message]:
+        """Return the full message list for a given session ID."""
+        ...
+
+    @abstractmethod
+    def build_inject_command(
+        self,
+        context: str,
+        target_session_id: str | None = None,
+        cwd: str | None = None,
+        method: str = "system_prompt",
+    ) -> str:
+        """Return the shell command to start/continue a session with context injected.
+
+        This method MUST NOT execute anything — it only returns the command string.
+        """
+        ...
+
+    def get_rollup_summary(self, session_id: str) -> str | None:
+        """Return a pre-computed summary if the tool stores one natively, else None."""
+        return None
+
+    def is_available(self) -> bool:
+        """Return True if this tool is installed and its data paths exist."""
+        return any(p.exists() for p in self.default_paths)