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

contextforge/core/scanner.py

@@ -0,0 +1,72 @@
+"""Session discovery and indexing across all registered adapters."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import sqlite_utils
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from contextforge.adapters.registry import get_available_adapters
+from contextforge.core.db import upsert_session
+from contextforge.models.session import Session
+
+
+@dataclass
+class ScanResult:
+    new: int = 0
+    updated: int = 0
+    unchanged: int = 0
+    errors: list[str] = field(default_factory=list)
+    sessions: list[Session] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return self.new + self.updated + self.unchanged
+
+
+def scan(db: sqlite_utils.Database, quiet: bool = False) -> ScanResult:
+    result = ScanResult()
+    adapters = get_available_adapters()
+
+    if not adapters:
+        result.errors.append("No supported agentic tools found on this machine.")
+        return result
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        disable=quiet,
+    ) as progress:
+        for adapter in adapters:
+            task = progress.add_task(f"Scanning {adapter.tool_name}...", total=None)
+            try:
+                sessions = adapter.discover_sessions()
+            except Exception as exc:
+                result.errors.append(f"{adapter.tool_name}: {exc}")
+                progress.remove_task(task)
+                continue
+
+            for session in sessions:
+                try:
+                    existing = list(
+                        db["sessions"].rows_where("id = ?", [session.id])
+                    )
+                    before_count = len(existing)
+                    upsert_session(db, session)
+                    after = list(db["sessions"].rows_where("id = ?", [session.id]))
+
+                    if before_count == 0:
+                        result.new += 1
+                    elif existing[0]["updated_at"] < int(session.updated_at.timestamp() * 1000):
+                        result.updated += 1
+                    else:
+                        result.unchanged += 1
+                    result.sessions.append(session)
+                except Exception as exc:
+                    result.errors.append(f"{session.id}: {exc}")
+
+            progress.update(task, description=f"[green]{adapter.tool_name}: {len(sessions)} sessions")
+            progress.remove_task(task)
+
+    return result

contextforge/core/summarizer.py

@@ -0,0 +1,155 @@
+"""LLM-based session summarization with caching."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+import sqlite_utils
+
+from contextforge.adapters.registry import get_adapter
+from contextforge.core.db import get_session, get_sessions, update_summary
+from contextforge.models.config import ForgeConfig
+from contextforge.utils.tokens import count_tokens, truncate_to_budget
+
+_SUMMARY_PROMPT = """\
+You are summarizing a coding session for a developer. Read the conversation below and
+write a 3–5 sentence summary covering:
+- What was being built or investigated
+- Key decisions made or problems solved
+- Files and components touched
+- Current state / what remains to be done
+
+Be concise. Under 150 words. Plain prose, no bullet points.
+
+--- SESSION ---
+{transcript}
+--- END SESSION ---
+
+Summary:"""
+
+
+@dataclass
+class BatchSummaryResult:
+    summarized: int = 0
+    skipped: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+def summarize_session(
+    db: sqlite_utils.Database,
+    session_id: str,
+    config: ForgeConfig,
+    force: bool = False,
+) -> str | None:
+    """Generate (or return cached) summary for a single session.
+
+    Priority order:
+    1. Cached summary in DB (unless force=True)
+    2. Tool-native rollup summary (e.g. Codex stage1_outputs) — zero LLM cost
+    3. LLM-generated summary (requires ANTHROPIC_API_KEY)
+    4. Graceful degradation: first user message preview
+    """
+    row = get_session(db, session_id)
+    if row is None:
+        return None
+
+    # Return cached summary unless force-refresh
+    if row.get("summary") and not force:
+        return row["summary"]
+
+    # Check for tool-native rollup summary first (e.g. Codex pre-computed)
+    try:
+        adapter = get_adapter(row["tool"])
+        rollup = adapter.get_rollup_summary(session_id)
+        if rollup:
+            update_summary(db, session_id, rollup)
+            return rollup
+    except Exception:
+        pass
+
+    # Load messages for LLM path
+    try:
+        messages = adapter.load_messages(session_id)
+    except Exception:
+        messages = []
+
+    if not messages:
+        return None
+
+    # Build transcript
+    lines = []
+    for m in messages:
+        prefix = "User" if m.role == "user" else "Assistant"
+        lines.append(f"{prefix}: {m.content}")
+    transcript = "\n\n".join(lines)
+
+    # Respect input token budget
+    max_input = config.llm.max_input_tokens
+    prompt_overhead = count_tokens(_SUMMARY_PROMPT.format(transcript=""))
+    transcript = truncate_to_budget(transcript, max_input - prompt_overhead - 200)
+
+    api_key = config.llm.api_key or os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        # Graceful degradation: return first user message as preview
+        for m in messages:
+            if m.role == "user":
+                preview = m.content[:200]
+                update_summary(db, session_id, preview)
+                return preview
+        return None
+
+    try:
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=api_key)
+        prompt = _SUMMARY_PROMPT.format(transcript=transcript)
+        response = client.messages.create(
+            model=config.llm.model,
+            max_tokens=300,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        summary = response.content[0].text.strip()
+    except Exception:
+        return None
+
+    update_summary(db, session_id, summary)
+    return summary
+
+
+def batch_summarize(
+    db: sqlite_utils.Database,
+    config: ForgeConfig,
+    session_ids: list[str] | None = None,
+    force: bool = False,
+    on_progress: "Callable[[str, str | None], None] | None" = None,
+) -> BatchSummaryResult:
+    """Summarize multiple sessions.
+
+    If session_ids is None, summarizes all sessions without a cached summary
+    (or all sessions if force=True).
+
+    on_progress(session_id, summary_or_None) is called after each session.
+    """
+    result = BatchSummaryResult()
+
+    if session_ids is None:
+        rows = get_sessions(db, limit=10_000)
+        if not force:
+            rows = [r for r in rows if not r.get("summary")]
+        session_ids = [r["id"] for r in rows]
+
+    for sid in session_ids:
+        try:
+            summary = summarize_session(db, sid, config, force=force)
+            if summary:
+                result.summarized += 1
+            else:
+                result.skipped += 1
+            if on_progress:
+                on_progress(sid, summary)
+        except Exception as exc:
+            result.errors.append(f"{sid}: {exc}")
+            if on_progress:
+                on_progress(sid, None)
+
+    return result

contextforge/core/token_analyzer.py

@@ -0,0 +1,91 @@
+"""Per-turn token analysis for a session."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import sqlite_utils
+
+from contextforge.adapters.registry import get_adapter
+from contextforge.core.db import get_session
+from contextforge.models.session import Message
+from contextforge.utils.tokens import count_tokens
+
+
+@dataclass
+class TurnStats:
+    turn: int
+    role: str
+    tokens: int
+    content_preview: str  # first 80 chars, single line
+    cumulative: int = 0
+
+
+@dataclass
+class SessionTokenReport:
+    session_id: str
+    tool: str
+    title: str
+    turns: list[TurnStats] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return sum(t.tokens for t in self.turns)
+
+    @property
+    def user_total(self) -> int:
+        return sum(t.tokens for t in self.turns if t.role == "user")
+
+    @property
+    def assistant_total(self) -> int:
+        return sum(t.tokens for t in self.turns if t.role == "assistant")
+
+    @property
+    def turn_count(self) -> int:
+        return len(self.turns)
+
+    @property
+    def avg_user(self) -> float:
+        user = [t.tokens for t in self.turns if t.role == "user"]
+        return sum(user) / len(user) if user else 0.0
+
+    @property
+    def avg_assistant(self) -> float:
+        asst = [t.tokens for t in self.turns if t.role == "assistant"]
+        return sum(asst) / len(asst) if asst else 0.0
+
+    @property
+    def max_turn(self) -> TurnStats | None:
+        return max(self.turns, key=lambda t: t.tokens) if self.turns else None
+
+
+def analyze_tokens(
+    db: sqlite_utils.Database,
+    session_id: str,
+) -> SessionTokenReport | None:
+    row = get_session(db, session_id)
+    if row is None:
+        return None
+
+    adapter = get_adapter(row["tool"])
+    messages = adapter.load_messages(session_id)
+
+    turns: list[TurnStats] = []
+    cumulative = 0
+    for i, msg in enumerate(messages, 1):
+        tokens = count_tokens(msg.content)
+        cumulative += tokens
+        preview = msg.content.replace("\n", " ").strip()[:80]
+        turns.append(TurnStats(
+            turn=i,
+            role=msg.role,
+            tokens=tokens,
+            content_preview=preview,
+            cumulative=cumulative,
+        ))
+
+    return SessionTokenReport(
+        session_id=session_id,
+        tool=row["tool"],
+        title=row.get("title") or session_id[:16],
+        turns=turns,
+    )

contextforge/models/__init__.py

@@ -0,0 +1,4 @@
+from .session import ContextBundle, Message, Session
+from .config import ForgeConfig
+
+__all__ = ["Session", "Message", "ContextBundle", "ForgeConfig"]

contextforge/models/config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class LLMConfig(BaseModel):
+    api_key: str | None = None
+    model: str = "claude-haiku-4-5-20251001"
+    max_input_tokens: int = 60_000
+
+
+class ScannerConfig(BaseModel):
+    max_sessions_per_tool: int = 200
+
+
+class CompactorConfig(BaseModel):
+    default_strategy: str = "summary_only"
+    default_token_budget: int = 4096
+    file_injection_token_budget: int = 32_768
+
+
+class ToolConfig(BaseModel):
+    enabled: bool = True
+    custom_path: str | None = None
+
+
+class ForgeConfig(BaseModel):
+    db_path: Path = Field(default_factory=lambda: Path.home() / ".contextforge" / "contextforge.db")
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    scanner: ScannerConfig = Field(default_factory=ScannerConfig)
+    compactor: CompactorConfig = Field(default_factory=CompactorConfig)
+    tools: dict[str, ToolConfig] = Field(default_factory=dict)

contextforge/models/session.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Message(BaseModel):
+    role: Literal["user", "assistant", "tool", "system"]
+    content: str
+    timestamp: datetime | None = None
+    token_count: int | None = None
+
+
+class Session(BaseModel):
+    id: str
+    tool: str
+    title: str | None = None
+    cwd: str | None = None
+    created_at: datetime
+    updated_at: datetime
+    messages: list[Message] = Field(default_factory=list)
+    token_count: int | None = None
+    raw_path: str | None = None
+    status: str = "unknown"
+    summary: str | None = None
+    tags: list[str] = Field(default_factory=list)
+
+
+class ContextBundle(BaseModel):
+    name: str
+    source_sessions: list[str]
+    compacted_text: str
+    token_count: int
+    strategy: str
+    target_tool: str | None = None

contextforge/tui/app.py

@@ -0,0 +1,204 @@
+"""ContextForge TUI — full Textual dashboard."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Footer, Header
+
+from contextforge.tui.widgets.session_detail import SessionDetail
+from contextforge.tui.widgets.session_table import SessionTable
+from contextforge.tui.widgets.status_bar import StatusBar
+from contextforge.tui.widgets.tokens_panel import TokensPanel
+from contextforge.tui.widgets.transfer_panel import TransferPanel
+
+
+class ContextForgeApp(App):
+    """ContextForge dashboard — manage agentic CLI sessions."""
+
+    TITLE = "ContextForge"
+    CSS_PATH = "styles.tcss"
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("r", "rescan", "Rescan"),
+        Binding("s", "summarize", "Summarize"),
+        Binding("t", "transfer", "Transfer"),
+        Binding("c", "compact", "Compact"),
+        Binding("x", "tokens", "Tokens"),
+        Binding("a", "analytics", "Analytics"),
+        Binding("/", "filter", "Filter"),
+    ]
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        super().__init__()
+        from contextforge.models.config import ForgeConfig
+        cfg = ForgeConfig()
+        self.db_path: Path = db_path or cfg.db_path
+
+    # ── Layout ────────────────────────────────────────────────────────────────
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal(id="main-horizontal"):
+            yield SessionTable(id="session-table")
+            yield SessionDetail(id="session-detail")
+        yield StatusBar(id="status-bar")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(StatusBar).refresh_stats()
+
+    # ── Session selection ──────────────────────────────────────────────────────
+
+    def on_session_table_row_selected(self, message: SessionTable.RowSelected) -> None:
+        self.query_one(SessionDetail).load(message.session_id)
+        self._current_session_id = message.session_id
+        self._current_tool = message.tool
+
+    def on_session_table_filter_changed(self, message: SessionTable.FilterChanged) -> None:
+        self.query_one(StatusBar).set_filter_indicator(
+            message.text, message.tool, message.match_count
+        )
+
+    # ── Actions ───────────────────────────────────────────────────────────────
+
+    def action_rescan(self) -> None:
+        """Re-scan all tools and refresh the table."""
+        from contextforge.core.db import get_db
+        from contextforge.core.scanner import scan
+
+        db = get_db(self.db_path)
+        result = scan(db, quiet=True)
+        self.query_one(SessionTable).reload()
+        self.query_one(StatusBar).refresh_stats()
+        self.notify(
+            f"Scan complete: {result.new} new, {result.updated} updated",
+            title="Rescan",
+            severity="information",
+        )
+
+    def action_summarize(self) -> None:
+        """Generate/refresh summary for the selected session."""
+        sid = getattr(self, "_current_session_id", None)
+        if sid is None:
+            self.notify("Select a session first.", severity="warning")
+            return
+
+        from contextforge.core.db import get_db
+        from contextforge.core.summarizer import summarize_session
+        from contextforge.models.config import ForgeConfig
+
+        db = get_db(self.db_path)
+        summary = summarize_session(db, sid, ForgeConfig())
+        if summary:
+            self.query_one(SessionDetail)._current_id = None  # bust cache
+            self.query_one(SessionDetail).load(sid)
+            self.notify("Summary generated.", title="Summarize")
+        else:
+            self.notify(
+                "Could not generate summary (no messages or no API key).",
+                severity="warning",
+            )
+
+    def action_transfer(self) -> None:
+        """Open the transfer panel for the selected session."""
+        sid = getattr(self, "_current_session_id", None)
+        if sid is None:
+            self.notify("Select a session first.", severity="warning")
+            return
+
+        from contextforge.core.db import get_db, get_session
+        db = get_db(self.db_path)
+        row = get_session(db, sid)
+        title = (row.get("title") or sid[:16]) if row else sid[:16]
+
+        def on_dismiss(result) -> None:
+            if result is None:
+                return
+            self._run_transfer(
+                session_id=sid,
+                target_tool=result["tool"],
+                strategy=result["strategy"],
+                execute=result["execute"],
+            )
+
+        self.push_screen(TransferPanel(sid, title), callback=on_dismiss)
+
+    def _run_transfer(
+        self,
+        session_id: str,
+        target_tool: str,
+        strategy: str,
+        execute: bool,
+    ) -> None:
+        from contextforge.core.compactor import compact
+        from contextforge.core.db import get_db, save_bundle
+        from contextforge.core.injector import build_inject_command, execute_transfer
+
+        db = get_db(self.db_path)
+        bundle = compact(
+            db=db,
+            session_ids=[session_id],
+            strategy=strategy,
+            token_budget=4096,
+            target_tool=target_tool,
+        )
+        cmd, method = build_inject_command(bundle, target_tool)
+
+        if execute:
+            bundle_id = save_bundle(db, bundle)
+            execute_transfer(
+                db=db,
+                bundle=bundle,
+                bundle_id=bundle_id,
+                target_tool=target_tool,
+            )
+            self.notify(
+                f"Launched {target_tool} with {bundle.token_count} tokens of context.",
+                title="Transfer executed",
+            )
+        else:
+            self.notify(
+                f"[cyan]{cmd}[/cyan]",
+                title=f"Preview → {target_tool} ({method})",
+                timeout=12,
+            )
+
+    def action_compact(self) -> None:
+        """Compact the selected session and show the bundle."""
+        sid = getattr(self, "_current_session_id", None)
+        if sid is None:
+            self.notify("Select a session first.", severity="warning")
+            return
+
+        from contextforge.core.compactor import compact
+        from contextforge.core.db import get_db
+
+        db = get_db(self.db_path)
+        bundle = compact(db=db, session_ids=[sid], strategy="summary_only", token_budget=4096)
+        self.notify(
+            f"Bundle: {bundle.token_count} tokens ({bundle.strategy})\n"
+            f"{bundle.compacted_text[:200]}…",
+            title="Compact",
+            timeout=10,
+        )
+
+    def action_tokens(self) -> None:
+        """Open the token analysis modal for the selected session."""
+        sid = getattr(self, "_current_session_id", None)
+        if sid is None:
+            self.notify("Select a session first.", severity="warning")
+            return
+        self.push_screen(TokensPanel(session_id=sid, db_path=self.db_path))
+
+    def action_analytics(self) -> None:
+        """Open the analytics dashboard modal."""
+        from contextforge.tui.widgets.stats_panel import StatsPanel
+        self.push_screen(StatsPanel())
+
+    def action_filter(self) -> None:
+        """Toggle the filter bar in the session table."""
+        self.query_one(SessionTable).toggle_filter()

contextforge/tui/styles.tcss

@@ -0,0 +1,50 @@
+/* ContextForge TUI Styles */
+
+/* ── Layout ─────────────────────────────────────────────── */
+
+Screen {
+    layout: vertical;
+}
+
+#main-horizontal {
+    height: 1fr;
+    layout: horizontal;
+}
+
+/* ── Transfer modal ─────────────────────────────────────── */
+
+TransferPanel {
+    align: center middle;
+}
+
+TransferPanel > Vertical {
+    width: 64;
+    height: auto;
+    max-height: 38;
+    border: thick $primary;
+    background: $surface;
+    padding: 1 2;
+}
+
+#panel-title {
+    text-style: bold;
+    color: $accent;
+    margin-bottom: 1;
+}
+
+.section-label {
+    text-style: bold;
+    margin-top: 1;
+    color: $text-muted;
+}
+
+#btn-row {
+    margin-top: 2;
+    height: auto;
+    layout: horizontal;
+    align: right middle;
+}
+
+#btn-row Button {
+    margin-left: 1;
+}