context-forge-cli 0.1.0__tar.gz

context_forge_cli-0.1.0/.contextforge.toml

@@ -0,0 +1,12 @@
+# ContextForge project-level config (used when running cf from this repo)
+# Override user-level config at ~/.contextforge/config.toml
+
+[llm]
+# model = "claude-haiku-4-5-20251001"
+
+[compactor]
+default_strategy = "summary_only"
+default_token_budget = 4096
+
+[scanner]
+max_sessions_per_tool = 200

context_forge_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

context_forge_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

context_forge_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

context_forge_cli-0.1.0/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md — Guidelines for Agents Working on ContextForge
+
+This file tells automated agents (Claude Code, Codex, altimate-code, etc.) how to work
+safely and effectively on this repository.
+
+## Project Overview
+
+ContextForge is a Python CLI/TUI tool. Entry point: `contextforge/cli.py` (command: `cf`).
+Core modules: `adapters/`, `core/`, `models/`, `tui/`. Tests: `tests/`.
+
+## Setup
+
+```bash
+uv sync              # install all dependencies
+uv run pytest        # run the test suite
+uv run cf --help     # run the CLI locally
+```
+
+## Hard Invariants — Never Violate These
+
+1. **Adapters are read-only.** No adapter may write to tool-native storage
+   (`~/.claude/`, `~/.codex/`, `~/.local/share/altimate-code/`). This is a hard safety boundary.
+
+2. **`build_inject_command()` returns a string; it does NOT execute it.**
+   Execution happens only in `core/injector.py` when the user passes `--execute`.
+
+3. **Pydantic models in `models/` are the canonical data contract.**
+   Adapters must return valid `Session` and `Message` objects. Never pass raw dicts
+   across module boundaries.
+
+4. **SQLite schema changes require a migration function in `core/db.py`.**
+   Do not ALTER TABLE directly. Add a new migration in `_migrate()` keyed by version integer.
+
+5. **Token budget is a hard cap, not a guideline.**
+   `compactor.py` must never return a bundle exceeding `token_budget`.
+   Use `utils/tokens.py` to verify before returning.
+
+## Adding a New Tool Adapter
+
+1. Create `contextforge/adapters/<tool_name>.py`, subclass `ToolAdapter` from `adapters/base.py`
+2. Implement `discover_sessions()`, `load_messages()`, `build_inject_command()`
+3. Register in `adapters/registry.py`: `ADAPTERS["<tool_name>"] = MyAdapterClass`
+4. Add fixture session data to `tests/fixtures/`
+5. Add tests in `tests/adapters/test_<tool_name>.py`
+6. Update the Supported Tools table in `README.md`
+7. Mark the relevant item `[x]` in `PLAN.md`
+
+## Updating the Plan
+
+- As you complete items, mark them `[x]` in `PLAN.md`
+- When starting a new Phase, update the `Status:` line at the top of `PLAN.md`
+- When completing a phase, update `README.md` to reflect new capabilities
+
+## CLI Conventions
+
+- Every command that produces structured data must support `--format json`
+- Long-running operations (scan, summarize --all) must show a `rich.progress` bar
+- Errors must be printed to stderr; exit code 1 on failure
+
+## Testing
+
+- All adapter tests must work offline (no live tool required). Use fixtures.
+- Summarizer tests must mock the Anthropic client.
+- Run `uv run pytest tests/` before committing.
+- Target >80% coverage on `core/` and `adapters/`.
+
+## Commit Style
+
+```
+feat(adapters): add opencode standalone adapter
+fix(compactor): respect token budget when combining sessions
+docs(readme): add troubleshooting section for Codex SQLite path
+test(core): add scanner integration tests
+```
+
+## Module Ownership
+
+| Area | Module |
+|---|---|
+| Tool discovery | `adapters/<tool>.py` |
+| Session indexing | `core/scanner.py` |
+| DB schema + CRUD | `core/db.py` |
+| Summarization | `core/summarizer.py` |
+| Context compaction | `core/compactor.py` |
+| Shell command building | `core/injector.py` |
+| CLI commands | `contextforge/cli.py` |
+| TUI layout | `tui/app.py` |
+
+## Do Not Touch
+
+- `~/.claude/`, `~/.codex/`, `~/.local/share/altimate-code/` — tool-native storage
+- `uv.lock` — only `uv` should modify this
+- `~/.contextforge/contextforge.db` — only `core/db.py` should modify this

context_forge_cli-0.1.0/PKG-INFO

@@ -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/PLAN.md

@@ -0,0 +1,129 @@
+# ContextForge — Development Plan
+
+Last updated: 2026-04-04
+Status: Phase 4 Complete / Phase 5 Ready
+
+## How to use this file
+
+Agents and contributors: update this file as you work.
+- Mark completed items `[x]`
+- Update `Status:` at the top when starting/completing a phase
+- Update `Last updated:` to today's date when you make changes
+- When completing a phase, also update `README.md` to reflect new capabilities
+
+---
+
+## Phase 1: Foundation [COMPLETE]
+
+- [x] Project scaffold (`uv init`, deps, `pyproject.toml` entry point `cf`)
+- [x] Data models (`models/session.py` — Session, Message, ContextBundle)
+- [x] Config models (`models/config.py` — ForgeConfig)
+- [x] SQLite schema + CRUD (`core/db.py`)
+- [x] Abstract adapter base (`adapters/base.py`)
+- [x] Claude Code adapter (`adapters/claude_code.py`)
+- [x] Codex adapter (`adapters/codex.py`)
+- [x] altimate-code adapter (`adapters/altimate_code.py`)
+- [x] Adapter registry (`adapters/registry.py`)
+- [x] Scanner (`core/scanner.py`)
+- [x] Token utilities (`utils/tokens.py`)
+- [x] Display helpers (`utils/display.py`)
+- [x] CLI: `cf scan`, `cf ls`, `cf show`, `cf tag`, `cf config` (`cli.py`)
+- [x] Tests: Claude Code adapter, db, compactor (13 passing → 22 with Phase 2)
+- [x] README.md, AGENTS.md, PLAN.md
+
+---
+
+## Phase 2: Summarizer [COMPLETE]
+
+- [x] Wire summarizer into `cf scan` via `--summarize` flag (auto-summarizes new sessions)
+- [x] `cf summarize <id>` and `cf summarize --all` commands with rich progress bar
+- [x] Summarizer tests with mocked Anthropic client (`tests/core/test_summarizer.py` — 9 tests)
+- [x] Codex pre-existing `stage1_outputs.rollout_summary` shortcut (zero LLM cost)
+- [x] `batch_summarize()` helper with `on_progress` callback
+- [x] Update README.md with summarizer section
+
+---
+
+## Phase 3: Compaction + Transfer [COMPLETE]
+
+- [x] `cf compact` with `--save` (persists bundle to DB) and `--format json`
+- [x] `cf transfer` cross-tool: Claude Code → Codex, Codex → altimate-code, altimate → Claude Code
+- [x] Multi-session cross-tool bundle transfer tested
+- [x] Large-context file injection (`CONTEXT.md` strategy auto-selected when >4k tokens)
+- [x] `--format json` on both `cf compact` and `cf transfer`
+- [x] 23 injector tests — per-tool commands, file injection, DB recording, cross-tool scenarios (45 total passing)
+
+---
+
+## Phase 4: TUI Dashboard [COMPLETE]
+
+- [x] `textual` moved to runtime deps (removed from dev group)
+- [x] `SessionTable` widget — DataTable with tool emoji, title, updated, tokens, ID
+- [x] `SessionDetail` widget — reactive right panel; title, metadata block, summary text
+- [x] `TransferPanel` widget — `ModalScreen` with RadioSet for tool + strategy, Preview/Execute buttons
+- [x] `StatusBar` widget — per-tool session counts + last refresh time (docked bottom)
+- [x] `tui/styles.tcss` — full layout CSS, panel borders, modal styling
+- [x] `cf dashboard` command fully wired; passes DB path from config; keybindings in docstring
+- [x] App actions: r=rescan, s=summarize, t=transfer modal, c=compact, q=quit
+- [x] Update README.md with dashboard section
+
+---
+
+## Ad-hoc: Token Analysis [COMPLETE]
+
+- [x] `cf tokens <id>` — per-turn breakdown with bar chart, role totals, averages, heaviest turn
+- [x] `cf tokens <id> --top N` — show only the N heaviest turns
+- [x] `cf tokens <id> --format json` — machine-readable output
+- [x] `core/token_analyzer.py` — `SessionTokenReport` dataclass + `analyze_tokens()`
+- [x] 7 tests in `tests/core/test_token_analyzer.py`
+
+---
+
+## Phase 5: Polish [ ]
+
+- [ ] `cf config set` persists to `~/.contextforge/config.toml`
+- [ ] Graceful degradation: missing tools silently skipped with `--verbose` warning
+- [ ] `--format json` on all remaining commands
+- [ ] Install docs: `uv tool install contextforge`
+- [ ] GitHub Actions CI: `uv run pytest --cov=contextforge`
+- [ ] `open-claw` adapter (if/when CLI interface is documented)
+- [ ] Session search: `cf ls --search <query>`
+- [ ] Session archiving: `cf archive <id>`
+
+---
+
+## Architecture Reference
+
+```
+contextforge/
+├── cli.py                    ← Typer root; all commands
+├── tui/
+│   ├── app.py                ← Textual Application
+│   └── widgets/
+├── adapters/
+│   ├── base.py               ← Abstract ToolAdapter
+│   ├── claude_code.py        ← Claude Code (JSONL)
+│   ├── codex.py              ← Codex (SQLite + JSONL)
+│   ├── altimate_code.py      ← altimate-code (SQLite)
+│   └── registry.py           ← ADAPTERS dict + helpers
+├── core/
+│   ├── db.py                 ← SQLite schema + CRUD
+│   ├── scanner.py            ← multi-adapter discovery
+│   ├── summarizer.py         ← LLM summarization + caching
+│   ├── compactor.py          ← 3-strategy context compaction
+│   └── injector.py           ← shell command builder + executor
+├── models/
+│   ├── session.py            ← Session, Message, ContextBundle
+│   └── config.py             ← ForgeConfig
+└── utils/
+    ├── tokens.py             ← tiktoken helpers
+    └── display.py            ← rich helpers
+```
+
+## Key Design Decisions
+
+- **Adapters are always read-only** — ContextForge never writes to tool-native storage
+- **`build_inject_command()` returns a string, never executes** — execution only in `injector.py` with `--execute`
+- **Token budget is a hard cap** — `compactor.py` always truncates to stay within budget
+- **SQLite for index only** — messages re-read from source on demand (no duplication)
+- **LLM API key is optional** — graceful degradation to first-message preview