ContextForge
Session manager and context bridge for agentic CLI tools.
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.
What it does
- Discovers sessions from Claude Code (
~/.claude/projects/), Claude Desktop, Codex (~/.codex/state_5.sqlite), Gemini (~/.gemini/tmp/<project_hash>/chats/), 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, Claude Desktop, Codex, Gemini, or altimate-code installed and with session history
Install
Using uv (recommended)
uv tool install context-forge-cli
Using pipx
pipx install context-forge-cli
From source (development)
git clone https://github.com/emmver/contextforge.git
cd contextforge
uv sync
uv run cforge --help
Verify installation
cforge --help # Should show the CLI with all commands
cforge config # Show or edit configuration
Note:
cforge,cfg, andcontextforgeare all installed as entrypoints. You can use whichever prefix you prefer (cforgeorcfg).
Quick Start
1. Scan for sessions
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
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)
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 below).
4. Launch the dashboard
cforge dashboard # interactive TUI with live session browser
5. Transfer context to a new session
# Preview the context bundle
cforge compact <session-id>
# Inject context into a new Claude Code session
cforge transfer <session-id> --to claude_code --execute
# Inject into Codex with richer context
cforge transfer <session-id> --to codex --strategy key_messages --execute
Context Transfer
# Preview: compact a session into a ContextBundle and display it
cforge compact <session-id>
# Save a bundle to the DB for later reuse
cforge compact <session-id> --save
# Preview: show the exact command that would inject context into a new Codex session
cforge transfer <session-id> --to codex
# Execute: launch a new Codex session with context injected
cforge transfer <session-id> --to codex --execute
# Multi-session bundle → altimate-code, richer key_messages strategy
cforge transfer <id1> <id2> --to altimate-code --strategy key_messages --execute
# Resume an existing session with injected context
cforge transfer <id> --to claude_code --session <existing-session-id> --execute
# Machine-readable output
cforge 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 |
| Gemini | ~/.gemini/tmp/<project_hash>/chats/ JSON |
New session / /resume |
| Antigravity | ~/.gemini/antigravity-cli/history.jsonl |
-i / --conversation |
| altimate-code | ~/.local/share/altimate-code/opencode.db |
run -s / import |
| Cursor | ~/.config/Cursor/User/globalStorage/state.vscdb |
cursor-agent -p / --resume |
| Pi agent | ~/.pi/agent/sessions/ JSONL |
--system-prompt / --session + --append-system-prompt |
| datatzis harness | <repo>/.datatzis/ JSON (per-repo) |
launch/resume only: datatzis chat --resume (delivered interactively) |
Notes:
- Sub-agent tracking — sessions spawned by sub-agents are tracked and cross-linked: Pi
(
pi-subagents) child transcripts getsubagent+parent:<session-id>tags naming the parent session; the datatzis harness's orchestrator tasks (one per user prompt) getsubagent+workspace:<session-id>tags. Surfaces are parent-first:cforge lsshows only main sessions unless--allis 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 theDATATZIS_SEARCH_ROOTSenvironment variable (colon-separated; default~/Documents/Github). The datatzis CLI is interactive-only, so inject commands open or resume the session rather than passing context as a flag.
Session Summaries
ContextForge generates plain-English summaries of what each session accomplished.
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
cforge scan --summarize
How summaries work:
- Codex — reuses pre-computed
stage1_outputs.rollout_summarywhen available (zero LLM cost) - All tools — calls the Claude API (Haiku model) to produce a 3–5 sentence summary
- 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 cforge ls and cforge show.
Configuration
Config file: ~/.contextforge/config.toml (created on first run)
Manage config from CLI
cforge config show # display current config
cforge config set llm.api_key sk-ant-...
cforge config set compactor.default_strategy key_messages
Full reference
[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 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:
cforge ls --format json
cforge show <id> --format json
cforge compact <id> --format json
See AGENTS.md for contribution guidelines and PLAN.md for development status.
TUI Dashboard
cforge 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 │ Gemini:2 │ Alt:3 │ Total:21 │ 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
ESCto clear and close
Transfer modal (t)
Press t on any session to open the transfer panel. Choose:
- Target tool — Claude Code, Claude Desktop, Codex, Gemini, or altimate-code
- Strategy —
summary_only,key_messages, orfull_recent - Preview — shows the exact shell command (no side effects)
- Execute — builds the bundle and launches the target tool
MCP Server
ContextForge ships a Model Context Protocol server that exposes session data and token analytics to LLM agents.
Setup
# Run directly (after installation)
cforge-mcp # or the legacy alias: cf-mcp
# From source
uv run python -m contextforge.mcp_server
Register the server with your agentic tool of choice:
Claude Code
Add to ~/.claude/claude_desktop_config.json (global) or .claude/mcp.json (project):
{
"mcpServers": {
"contextforge": {
"command": "cf-mcp"
}
}
}
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"contextforge": {
"command": "cf-mcp"
}
}
}
Restart Cursor fully after saving.
Codex CLI
Add to ~/.codex/config.toml (global) or .codex/config.toml (project):
[mcp_servers.contextforge]
command = "cf-mcp"
enabled = true
Gemini CLI
Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):
{
"mcpServers": {
"contextforge": {
"command": "cf-mcp"
}
}
}
pi
pi mcp add contextforge -- cforge-mcp
pi mcp list # → contextforge: connected, 7 tools
Or add to ~/.pi/agent/mcp.json:
{
"mcpServers": {
"contextforge": {
"command": "cforge-mcp"
}
}
}
Antigravity
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:
{
"servers": [
{
"name": "contextforge",
"transport": "stdio",
"command": "cforge-mcp",
"enabled": true
}
]
}
Note: the server uses the
FastMCPAPI frommcp1.x, sopyproject.tomlpinsmcp>=1.9.0,<2. If an existing install fails withModuleNotFoundError: mcp.server.fastmcp, reinstall withuv tool install --force --editable ..
Tools
| Tool | Description |
|---|---|
list_sessions |
List indexed sessions; filter by tool, limit up to 200 |
get_session |
Full detail for a single session by ID |
get_session_tokens |
Per-turn token breakdown; optionally return only the N heaviest turns |
get_token_analytics |
Aggregated token stats across all sessions for a time window |
get_activity_timeline |
Session count and token usage bucketed over time |
get_top_projects |
Top projects by session count within a time window |
compare_sessions |
Side-by-side token comparison for 2–10 sessions |
All tools are read-only and accept a window parameter of 7d, 30d, 6m, or 1y where applicable.
Example usage
# In Claude Code with the MCP server registered:
"Show me token usage for all my Claude Code sessions this month"
"Compare sessions <id1> and <id2> side by side"
"What are my top 5 projects by session count?"
Troubleshooting
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 cforge ls
- Cause: No sessions discovered from installed tools
- Fix: Run
cforge scanfirst; 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
cforge config set llm.api_key sk-ant-...or setANTHROPIC_API_KEYenv 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
cforge scanagain to reindex all tools
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
cforgecommands running at once - Fix: Wait for the first command to finish, or delete
~/.contextforge/contextforge.dband runcforge scanagain
Development
uv sync # install all dependencies including dev
uv run pytest # run tests
uv run cforge --help # run CLI locally
uv tool install . --force # test local installation
Metadata
Release files for context-forge-cli 0.4.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| context_forge_cli-0.4.16.tar.gz | 151.3 kB | Without provenance | Details for context_forge_cli-0.4.16.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| context_forge_cli-0.4.16-py3-none-any.whl | Python 3 | none | any | Details for context_forge_cli-0.4.16-py3-none-any.whl |
Total release size: 243.8 kB
Release files / context_forge_cli-0.4.16.tar.gz
| Download URL | context_forge_cli-0.4.16.tar.gz |
|---|---|
| Size | 151.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f485f8ab3325adb397092d33ffe7985cae80b967139e0f4a2d87876a5aba4ff9
|
|
BLAKE2b-256 checksum How to use checksums |
3399b8b148079e6ca92a3bb9b467d0c8b985ab5ae632a89ce9c4ed106a1c9e8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / context_forge_cli-0.4.16-py3-none-any.whl
| Download URL | context_forge_cli-0.4.16-py3-none-any.whl |
|---|---|
| Size | 92.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99521260bcd869bfeddeba79c163262ea9925e80ba24d8b81a6b5099c443fe2b
|
|
BLAKE2b-256 checksum How to use checksums |
37b430173cf8df57aea74023c45f63268af837fab6972c2bc28f2c7d73e586fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for context-forge-cli 0.4.16
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.