Context Forge

Context is everything.

Context Forge is a local, model-agnostic conversation/context harness for long-running AI discussions. The repository is named context-harness because that describes the category; Context Forge is the product name.

The project treats the conversation itself as the durable artifact. Instead of tying a thread to Claude, Codex, ChatGPT, or any one agent UI, it stores the conversation locally, lets different AIs continue from the same context, and eventually gives the user tools to edit, fork, summarize, graph, and export that context deliberately.

Product Identity

This is not primarily an AI coding workflow engine. It is a workbench for owning and reshaping conversation state.

Use it when you want to:

• continue a discussion across multiple AI models or tools
• preserve conversations independently of any vendor UI
• edit or clone past context to test different outputs
• export a clean thread into a web chatbot or coding agent
• work with math-heavy or research-heavy conversations that need durable context
• eventually drill into only the parts of a long conversation that matter

The shortest description:

A local conversation/context harness for long-running AI work.

What It Is Not

Context Forge is not trying to replace workflow engines like Archon.

Archon-style tools focus on deterministic coding workflows: plan, implement, validate, review, and produce a PR. Context Forge focuses on the conversation and context layer underneath AI work: what was said, what should be included next time, what branch of the discussion is active, and what context should be exported to another model.

In simple terms:

• Archon: run a coding process reliably.
• Context Forge: preserve, reshape, and reuse conversation context.

Core Model

The app owns a local file-first conversation store.

Each conversation is stored as a folder containing:

• conversation metadata
• one Markdown file per message
• generated exports for humans and external AI tools
• future history/snapshot data for rollback and recovery

The backend is the canonical writer. External agents and web chatbots should read exported context and send new messages back through the app, rather than mutating canonical files directly.

Current Status

Phase 1–5 features are implemented and in active daily use for homelab automation and long-running research tasks.

Implemented:

• FastAPI backend with file-first conversation store
• React/Vite frontend: thread view, Vim/CodeMirror editor, KaTeX, graph panel, settings page, attachment support
• Markdown import/export, conversation surgery (edit, insert, delete, fork)
• ChatGPT Bridge (tools/contextforge-extension/) — Firefox extension that links a CF conversation to a ChatGPT tab and drives it autonomously:
  • injects messages into ChatGPT's input via content script
  • flushes suspended requestAnimationFrame rendering by briefly activating the tab every 3s so replies sync without manual tab visits
  • auto-captures the conversation URL after the first message creates it
  • permanent install via NixOS Firefox enterprise policy + AMO-signed .xpi
• Auto-run tool execution — tiered command classifier (SAFE / CONFIRM / BLOCKED) with desktop notifications for commands needing approval:
  • SSH and docker exec are transport layers; the remote command determines the safety tier
  • >/dev/null, 2>/dev/null, /tmp/ writes, command -v checks are safe
  • parse failures auto-retry with a heredoc suggestion
  • no-command streak detector: auto-continues up to 2 times then notifies via a desktop notification and waits for the user
  • notifications go out through notify-send over the session D-Bus, shown by the laptop's notification daemon (quickshell)
• Settings UI: theme, auto-run toggle

Current focus:

• Driving multi-step homelab tasks (Lidarr, Navidrome, qBittorrent) fully autonomously through the ChatGPT bridge
• Hardening the command classifier edge cases

Phase Roadmap

Phase 1 - Conversation MVP

Prove the app can hold a real local conversation.

Goals:

• create and open conversations
• render a thread in the browser
• submit messages through an input field
• persist canonical message files
• keep exports/current.md in sync
• support basic Markdown import
• align the frontend/backend API contract

Phase 2 - Math-Native Input

Make the app materially better than ordinary chat UIs for math-heavy work.

Goals:

• replace the plain text editor with a Vim-style editor
• integrate Obsidian-style LaTeX shortcuts
• keep math display working in message bubbles
• begin supporting structured writing patterns, including bullet-heavy input

Phase 3 - Conversation Surgery

Turn conversations into editable experiments.

Goals:

• edit messages through the GUI
• clone conversations
• fork from prior messages
• insert or delete messages safely
• keep rollback history before destructive edits

Phase 4 - Context Lenses and Graph Navigation

Make long conversations navigable and selectively exportable.

Goals:

• show branches and threads as a graph
• support context lenses such as full thread, summary, branch-only, or selected topic context
• allow drilling into detailed sub-context only when needed
• prepare for future graph-based conversation editing

Phase 5 - Agent and Web-Chatbot Bridge

Let different AI surfaces participate in the same local conversation.

Goals:

• support multiple agent adapters
• improve handoff between local agents and web chatbots
• allow controlled tool-action workflows where model output can be reviewed, executed locally, and exported back into the conversation

Development

Enter the Nix development environment:

nix develop

Run backend tests:

pytest

The current backend entrypoint is:

uvicorn server.main:app --reload --port 8000 --host ::

--host :: binds dual-stack. On many systems localhost resolves to IPv6 ::1 first; without this, uvicorn listens only on IPv4 127.0.0.1 and the browser extension's fetch('http://localhost:8000/...') fails with a NetworkError after every backend restart.

The frontend lives in frontend/ and is a React/Vite app.

npm run dev