context-forge-cli 0.4.14__tar.gz → 0.4.16__tar.gz

{context_forge_cli-0.4.14 → context_forge_cli-0.4.16}/AGENTS.md

@@ -5,15 +5,15 @@ safely and effectively on this repository.
 
 ## Project Overview
 
-ContextForge is a Python CLI/TUI tool. Entry point: `contextforge/cli.py` (command: `cf`).
+ContextForge is a Python CLI/TUI tool. Entry point: `contextforge/cli.py` (command: `cforge` / `cfg`).
 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
+uv sync                  # install all dependencies
+uv run pytest            # run the test suite
+uv run cforge --help     # run the CLI locally
 ```
 
 ## Hard Invariants — Never Violate These

{context_forge_cli-0.4.14 → context_forge_cli-0.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: context-forge-cli
-Version: 0.4.14
+Version: 0.4.16
 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
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Utilities
 Requires-Python: >=3.13
 Requires-Dist: anthropic>=0.89.0
-Requires-Dist: mcp>=1.9.0
+Requires-Dist: mcp<2,>=1.9.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: rich>=14.3.3
 Requires-Dist: sqlite-utils>=3.39
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 **Session manager and context bridge for agentic CLI tools.**
 
-ContextForge (`cf`) tracks sessions from Claude Code, Claude Desktop, Codex, Gemini, altimate-code, and other
+ContextForge (`cforge` / `cfg`) tracks sessions from Claude Code, Claude Desktop, Codex, Gemini, 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.
@@ -67,79 +67,81 @@ pipx install context-forge-cli
 git clone https://github.com/emmver/contextforge.git
 cd contextforge
 uv sync
-uv run cf --help
+uv run cforge --help
 ```
 
 ### Verify installation
 ```bash
-cf --help      # Should show the CLI with all commands
-cf config      # Show or edit configuration
+cforge --help      # Should show the CLI with all commands
+cforge config      # Show or edit configuration
 ```
 
+> **Note**: `cforge`, `cfg`, and `contextforge` are all installed as entrypoints. You can use whichever prefix you prefer (`cforge` or `cfg`).
+
 ## Quick Start
 
 ### 1. Scan for sessions
 ```bash
-cf scan              # discover and index sessions from all installed tools
+cforge 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
+cforge ls                # list all recent sessions (with summaries if available)
+cforge ls --format json  # machine-readable output
+cforge 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)
+cforge summarize --all                 # generate summaries for all unsummarized sessions
+cforge summarize <id>                  # refresh summary for a single session
+cforge 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
+cforge dashboard         # interactive TUI with live session browser
 ```
 
 ### 5. Transfer context to a new session
 ```bash
 # Preview the context bundle
-cf compact <session-id>
+cforge compact <session-id>
 
 # Inject context into a new Claude Code session
-cf transfer <session-id> --to claude_code --execute
+cforge transfer <session-id> --to claude_code --execute
 
 # Inject into Codex with richer context
-cf transfer <session-id> --to codex --strategy key_messages --execute
+cforge 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>
+cforge compact <session-id>
 
 # Save a bundle to the DB for later reuse
-cf compact <session-id> --save
+cforge compact <session-id> --save
 
 # Preview: show the exact command that would inject context into a new Codex session
-cf transfer <session-id> --to codex
+cforge transfer <session-id> --to codex
 
 # Execute: launch a new Codex session with context injected
-cf transfer <session-id> --to codex --execute
+cforge 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
+cforge 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
+cforge transfer <id> --to claude_code --session <existing-session-id> --execute
 
 # Machine-readable output
-cf transfer <id> --to codex --format json
+cforge transfer <id> --to codex --format json
 ```
 
 ### Injection methods
@@ -180,7 +182,10 @@ Notes:
 - **Sub-agent tracking** — sessions spawned by sub-agents are tracked and cross-linked: Pi
   (`pi-subagents`) child transcripts get `subagent` + `parent:<session-id>` tags naming the
   parent session; the datatzis harness's orchestrator tasks (one per user prompt) get
-  `subagent` + `workspace:<session-id>` tags.
+  `subagent` + `workspace:<session-id>` tags. Surfaces are parent-first: `cforge ls` shows only
+  main sessions unless `--all` is passed, and in the TUI dashboard sub-agents stay hidden
+  until you select their parent row, which nests them underneath as an indented `↳` list —
+  selecting the parent again collapses them.
 - **datatzis discovery** — per-repo storage: ContextForge scans repository roots for
   `*/.datatzis/workspaces/` (up to two levels deep). Configure roots via the
   `DATATZIS_SEARCH_ROOTS` environment variable (colon-separated; default `~/Documents/Github`).
@@ -192,12 +197,12 @@ Notes:
 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
+cforge summarize <id>        # generate or refresh summary for one session
+cforge summarize --all       # bulk-generate summaries for all sessions
+cforge summarize --all --force  # regenerate even existing ones
 
 # Scan + summarize in one step
-cf scan --summarize
+cforge scan --summarize
 ```
 
 **How summaries work:**
@@ -205,7 +210,7 @@ cf scan --summarize
 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`.
+Summaries are cached in the local SQLite index and shown in `cforge ls` and `cforge show`.
 
 ## Configuration
 
@@ -213,9 +218,9 @@ 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
+cforge config show         # display current config
+cforge config set llm.api_key sk-ant-...
+cforge config set compactor.default_strategy key_messages
 ```
 
 ### Full reference
@@ -249,9 +254,9 @@ It **never modifies** tool-native storage. All source files are read-only.
 All structured commands support `--format json`:
 
 ```bash
-cf ls --format json
-cf show <id> --format json
-cf compact <id> --format json
+cforge ls --format json
+cforge show <id> --format json
+cforge compact <id> --format json
 ```
 
 See [AGENTS.md](AGENTS.md) for contribution guidelines and [PLAN.md](PLAN.md) for development status.
@@ -259,7 +264,7 @@ See [AGENTS.md](AGENTS.md) for contribution guidelines and [PLAN.md](PLAN.md) fo
 ## TUI Dashboard
 
 ```bash
-cf dashboard
+cforge dashboard
 ```
 
 A full-screen Textual dashboard with live session browsing, filtering, and analytics.
@@ -329,7 +334,7 @@ ContextForge ships a [Model Context Protocol](https://modelcontextprotocol.io) s
 
 ```bash
 # Run directly (after installation)
-cf-mcp
+cforge-mcp   # or the legacy alias: cf-mcp
 
 # From source
 uv run python -m contextforge.mcp_server
@@ -387,22 +392,49 @@ Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
 }
 ```
 
+#### pi
+
+```bash
+pi mcp add contextforge -- cforge-mcp
+pi mcp list   # → contextforge: connected, 7 tools
+```
+
+Or add to `~/.pi/agent/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cforge-mcp"
+    }
+  }
+}
+```
+
 #### Antigravity
 
-Add to `mcp_servers.json` in your project root:
+```bash
+agy mcp add contextforge cforge-mcp
+agy mcp list
+```
+
+This writes to `~/.gemini/config/mcp_config.json`. Equivalently, in a project-level `mcp_servers.json`:
 ```json
 {
   "servers": [
     {
       "name": "contextforge",
       "transport": "stdio",
-      "command": "cf-mcp",
+      "command": "cforge-mcp",
       "enabled": true
     }
   ]
 }
 ```
 
+> **Note:** the server uses the `FastMCP` API from `mcp` 1.x, so `pyproject.toml` pins `mcp>=1.9.0,<2`.
+> If an existing install fails with `ModuleNotFoundError: mcp.server.fastmcp`, reinstall with
+> `uv tool install --force --editable .`.
+
 ### Tools
 
 | Tool | Description |
@@ -428,36 +460,36 @@ All tools are **read-only** and accept a `window` parameter of `7d`, `30d`, `6m`
 
 ## Troubleshooting
 
-### `command not found: cf`
+### `command not found: cforge`
 - **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`
+### `RuntimeError: no sessions found` or empty `cforge 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
+- **Fix**: Run `cforge 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
+- **Fix**: Set it via `cforge 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
+- **Fix**: Run `cforge scan` again to reindex all tools
 
-### `cf dashboard` crashes or displays incorrectly
+### `cforge 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
+- **Cause**: Two `cforge` commands running at once
+- **Fix**: Wait for the first command to finish, or delete `~/.contextforge/contextforge.db` and run `cforge scan` again
 
 ## Development
 
 ```bash
 uv sync              # install all dependencies including dev
 uv run pytest        # run tests
-uv run cf --help     # run CLI locally
+uv run cforge --help     # run CLI locally
 uv tool install . --force  # test local installation
 ```

{context_forge_cli-0.4.14 → context_forge_cli-0.4.16}/README.md

@@ -2,7 +2,7 @@
 
 **Session manager and context bridge for agentic CLI tools.**
 
-ContextForge (`cf`) tracks sessions from Claude Code, Claude Desktop, Codex, Gemini, altimate-code, and other
+ContextForge (`cforge` / `cfg`) tracks sessions from Claude Code, Claude Desktop, Codex, Gemini, 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.
@@ -38,79 +38,81 @@ pipx install context-forge-cli
 git clone https://github.com/emmver/contextforge.git
 cd contextforge
 uv sync
-uv run cf --help
+uv run cforge --help
 ```
 
 ### Verify installation
 ```bash
-cf --help      # Should show the CLI with all commands
-cf config      # Show or edit configuration
+cforge --help      # Should show the CLI with all commands
+cforge config      # Show or edit configuration
 ```
 
+> **Note**: `cforge`, `cfg`, and `contextforge` are all installed as entrypoints. You can use whichever prefix you prefer (`cforge` or `cfg`).
+
 ## Quick Start
 
 ### 1. Scan for sessions
 ```bash
-cf scan              # discover and index sessions from all installed tools
+cforge 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
+cforge ls                # list all recent sessions (with summaries if available)
+cforge ls --format json  # machine-readable output
+cforge 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)
+cforge summarize --all                 # generate summaries for all unsummarized sessions
+cforge summarize <id>                  # refresh summary for a single session
+cforge 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
+cforge dashboard         # interactive TUI with live session browser
 ```
 
 ### 5. Transfer context to a new session
 ```bash
 # Preview the context bundle
-cf compact <session-id>
+cforge compact <session-id>
 
 # Inject context into a new Claude Code session
-cf transfer <session-id> --to claude_code --execute
+cforge transfer <session-id> --to claude_code --execute
 
 # Inject into Codex with richer context
-cf transfer <session-id> --to codex --strategy key_messages --execute
+cforge 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>
+cforge compact <session-id>
 
 # Save a bundle to the DB for later reuse
-cf compact <session-id> --save
+cforge compact <session-id> --save
 
 # Preview: show the exact command that would inject context into a new Codex session
-cf transfer <session-id> --to codex
+cforge transfer <session-id> --to codex
 
 # Execute: launch a new Codex session with context injected
-cf transfer <session-id> --to codex --execute
+cforge 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
+cforge 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
+cforge transfer <id> --to claude_code --session <existing-session-id> --execute
 
 # Machine-readable output
-cf transfer <id> --to codex --format json
+cforge transfer <id> --to codex --format json
 ```
 
 ### Injection methods
@@ -151,7 +153,10 @@ Notes:
 - **Sub-agent tracking** — sessions spawned by sub-agents are tracked and cross-linked: Pi
   (`pi-subagents`) child transcripts get `subagent` + `parent:<session-id>` tags naming the
   parent session; the datatzis harness's orchestrator tasks (one per user prompt) get
-  `subagent` + `workspace:<session-id>` tags.
+  `subagent` + `workspace:<session-id>` tags. Surfaces are parent-first: `cforge ls` shows only
+  main sessions unless `--all` is passed, and in the TUI dashboard sub-agents stay hidden
+  until you select their parent row, which nests them underneath as an indented `↳` list —
+  selecting the parent again collapses them.
 - **datatzis discovery** — per-repo storage: ContextForge scans repository roots for
   `*/.datatzis/workspaces/` (up to two levels deep). Configure roots via the
   `DATATZIS_SEARCH_ROOTS` environment variable (colon-separated; default `~/Documents/Github`).
@@ -163,12 +168,12 @@ Notes:
 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
+cforge summarize <id>        # generate or refresh summary for one session
+cforge summarize --all       # bulk-generate summaries for all sessions
+cforge summarize --all --force  # regenerate even existing ones
 
 # Scan + summarize in one step
-cf scan --summarize
+cforge scan --summarize
 ```
 
 **How summaries work:**
@@ -176,7 +181,7 @@ cf scan --summarize
 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`.
+Summaries are cached in the local SQLite index and shown in `cforge ls` and `cforge show`.
 
 ## Configuration
 
@@ -184,9 +189,9 @@ 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
+cforge config show         # display current config
+cforge config set llm.api_key sk-ant-...
+cforge config set compactor.default_strategy key_messages
 ```
 
 ### Full reference
@@ -220,9 +225,9 @@ It **never modifies** tool-native storage. All source files are read-only.
 All structured commands support `--format json`:
 
 ```bash
-cf ls --format json
-cf show <id> --format json
-cf compact <id> --format json
+cforge ls --format json
+cforge show <id> --format json
+cforge compact <id> --format json
 ```
 
 See [AGENTS.md](AGENTS.md) for contribution guidelines and [PLAN.md](PLAN.md) for development status.
@@ -230,7 +235,7 @@ See [AGENTS.md](AGENTS.md) for contribution guidelines and [PLAN.md](PLAN.md) fo
 ## TUI Dashboard
 
 ```bash
-cf dashboard
+cforge dashboard
 ```
 
 A full-screen Textual dashboard with live session browsing, filtering, and analytics.
@@ -300,7 +305,7 @@ ContextForge ships a [Model Context Protocol](https://modelcontextprotocol.io) s
 
 ```bash
 # Run directly (after installation)
-cf-mcp
+cforge-mcp   # or the legacy alias: cf-mcp
 
 # From source
 uv run python -m contextforge.mcp_server
@@ -358,22 +363,49 @@ Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
 }
 ```
 
+#### pi
+
+```bash
+pi mcp add contextforge -- cforge-mcp
+pi mcp list   # → contextforge: connected, 7 tools
+```
+
+Or add to `~/.pi/agent/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cforge-mcp"
+    }
+  }
+}
+```
+
 #### Antigravity
 
-Add to `mcp_servers.json` in your project root:
+```bash
+agy mcp add contextforge cforge-mcp
+agy mcp list
+```
+
+This writes to `~/.gemini/config/mcp_config.json`. Equivalently, in a project-level `mcp_servers.json`:
 ```json
 {
   "servers": [
     {
       "name": "contextforge",
       "transport": "stdio",
-      "command": "cf-mcp",
+      "command": "cforge-mcp",
       "enabled": true
     }
   ]
 }
 ```
 
+> **Note:** the server uses the `FastMCP` API from `mcp` 1.x, so `pyproject.toml` pins `mcp>=1.9.0,<2`.
+> If an existing install fails with `ModuleNotFoundError: mcp.server.fastmcp`, reinstall with
+> `uv tool install --force --editable .`.
+
 ### Tools
 
 | Tool | Description |
@@ -399,36 +431,36 @@ All tools are **read-only** and accept a `window` parameter of `7d`, `30d`, `6m`
 
 ## Troubleshooting
 
-### `command not found: cf`
+### `command not found: cforge`
 - **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`
+### `RuntimeError: no sessions found` or empty `cforge 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
+- **Fix**: Run `cforge 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
+- **Fix**: Set it via `cforge 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
+- **Fix**: Run `cforge scan` again to reindex all tools
 
-### `cf dashboard` crashes or displays incorrectly
+### `cforge 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
+- **Cause**: Two `cforge` commands running at once
+- **Fix**: Wait for the first command to finish, or delete `~/.contextforge/contextforge.db` and run `cforge scan` again
 
 ## Development
 
 ```bash
 uv sync              # install all dependencies including dev
 uv run pytest        # run tests
-uv run cf --help     # run CLI locally
+uv run cforge --help     # run CLI locally
 uv tool install . --force  # test local installation
 ```