A context window management application for LLM interactions. Organize your prompts, reference materials, and generated content with a three-zone architecture designed for optimal context caching.

ContextForge helps you manage the context window when working with Large Language Models. Instead of manually copying and pasting content, organize it into zones that optimize for LLM caching and token efficiency.

• Visual Zone Management - Drag-and-drop blocks between zones
• Multi-Turn Brainstorming - Have conversations with LLMs using your context
• Three LLM Providers - Ollama (local), Claude Code, and OpenRouter
• Real-Time Streaming - See responses as they generate
• Workflows & Templates - Create reusable document pipelines
• Projects - Organize related sessions together
• Session Snapshots - Save and restore context states
• LLM Observability - LangFuse integration for tracing

• Node.js 18+
• pnpm (npm install -g pnpm)
• At least one LLM provider (see below)

# Clone the repository
git clone https://github.com/opcheese/context_forge_ts.git
cd context_forge_ts

# Install dependencies
pnpm install
cd site && pnpm install && cd ..

# Copy environment file
cp .env.example .env.local

# Start everything (SPA + Astro site + Convex)
pnpm dev:all

• Landing page / blog: http://localhost:4321/
• App (SPA): http://localhost:5173/app/

# Preview production build locally (builds + serves with SPA rewrites)
pnpm preview

# Build everything (same as Vercel deploy)
pnpm build:all

ContextForge supports three LLM providers. You need at least one configured.

Free, local, private. Great for development and testing.

# Install from https://ollama.ai/download
# Pull a model
ollama pull llama3.2

# Ollama runs at http://localhost:11434 by default

Access Claude, GPT-4, Llama, and 100+ models through one API.

# Get API key from https://openrouter.ai/keys
# Add to .env.local:
OPENROUTER_API_KEY=sk-or-v1-...

Then set via Convex:

pnpm exec convex env set OPENROUTER_API_KEY sk-or-v1-...

Uses the Claude Code CLI (requires Claude subscription).

# Install Claude Code CLI from https://claude.ai/code
# Find path: which claude
# Add to .env.local:
CLAUDE_CODE_PATH=/path/to/claude

Then set via Convex:

pnpm exec convex env set CLAUDE_CODE_PATH /path/to/claude

Copy .env.example to .env.local and configure:

ContextForge uses two frameworks in one repo to serve different needs:

• Astro 5 (site/) — static HTML for the landing page, blog, and legal pages. Search engines index real HTML, not JavaScript-rendered SPAs. Astro builds these as plain .html files.
• Vite + React (src/) — SPA for the authenticated app at /app/*. Needs client-side routing, real-time Convex subscriptions, and drag-and-drop.

┌──────────────────────────────────────────────────────┐
│                   Build Pipeline                      │
│                                                      │
│  Step 1: Vite builds SPA                             │
│  src/ ──→ site/public/app/  (index.html + JS/CSS)   │
│                                                      │
│  Step 2: Astro builds everything                     │
│  site/src/ + site/public/ ──→ site/dist/             │
│                                                      │
│  Final output: site/dist/                            │
│  ├── index.html           (Astro landing page)       │
│  ├── blog/*/index.html    (Astro blog posts)         │
│  ├── privacy/index.html   (Astro legal)              │
│  └── app/                 (Vite SPA, copied over)    │
│      ├── index.html                                  │
│      └── assets/*.js,css                             │
└──────────────────────────────────────────────────────┘

Vercel deploys site/dist/ with a rewrite rule: /app/* → /app/index.html (for SPA client-side routing). All other routes serve Astro's static HTML directly.

Interactive elements on Astro pages (hero animations, zone demo) use React "islands" — components that render server-side during build and hydrate client-side when scrolled into view (client:visible).

See Architecture docs for the full technical breakdown.

contextforge/
├── convex/                 # Backend (Convex)
│   ├── schema.ts           # Database schema
│   ├── blocks.ts           # Block CRUD operations
│   ├── sessions.ts         # Session management
│   ├── templates.ts        # Template management
│   ├── workflows.ts        # Workflow management
│   ├── projects.ts         # Project management
│   ├── generations.ts      # LLM generation tracking
│   ├── claudeNode.ts       # Claude Code integration
│   ├── http.ts             # HTTP endpoints (Ollama, OpenRouter)
│   └── lib/                # Shared backend utilities
│
├── src/                    # App SPA (React 19 + TanStack Router)
│   ├── routes/             # Pages (file-based routing, all under /app/)
│   ├── components/         # React components (shadcn/ui)
│   ├── hooks/              # Custom hooks
│   ├── contexts/           # React contexts
│   └── lib/                # Utilities
│
├── site/                   # Public site (Astro 5)
│   ├── src/pages/          # Landing, blog, legal pages (.astro)
│   ├── src/content/blog/   # MDX blog posts
│   ├── src/components/     # Astro components + React islands
│   ├── src/layouts/        # Page layouts (Base, BlogPost)
│   └── public/             # Static assets (favicon, OG image, robots.txt)
│
├── docs/                   # Documentation
└── e2e/                    # Playwright tests

# Start everything concurrently
pnpm dev:all

# Run all checks
pnpm lint && pnpm test:run && pnpm build:all

# Format code
pnpm format

# Run E2E tests (requires app + Convex running)
pnpm test:e2e

# Type check
pnpm exec tsc --noEmit

The app deploys to Vercel as a single project. Vite builds the SPA into site/public/app/, then Astro builds all static pages into site/dist/. Vercel serves site/dist/ with a rewrite rule for /app/* to enable SPA client-side routing.

Content is assembled in a specific order to optimize LLM caching:

┌─────────────────┐
│  System Prompt  │ ← Extracted from system_prompt blocks
├─────────────────┤
│   PERMANENT     │ ← Guidelines, personas (best cache hits)
├─────────────────┤
│    STABLE       │ ← Reference material, templates
├─────────────────┤
│    WORKING      │ ← Recent work, notes, documents
├─────────────────┤
│   User Prompt   │ ← Current request
└─────────────────┘

ContextForge uses 12 semantic block types:

Create multi-step document creation pipelines:

1. Define templates for each step
2. Configure which zones carry forward
3. Start a project from the workflow
4. Progress through steps, building on previous outputs

See docs/README.md for a complete list of documentation.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

MIT - see LICENSE file for details.