Skip to content

ContextForge is an AI-powered context management platform that helps developers, agencies, and AI builders organize, optimize, and collaborate on prompts, agents, rules, and workflows. With robust GitHub importing, AI-driven optimization, and an intuitive directory system, ContextForge makes it easy to build your own vibe‑coding context hub.

Notifications You must be signed in to change notification settings

mgunnin/contextforge

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

35 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

ContextForge

An AI-powered context management platform for organizing, optimizing, and collaborating on prompts, agents, rules, and templates.

πŸš€ Quick Start Guide

Prerequisites

  • Node.js 18+ (recommended: use corepack for package manager)
  • pnpm (managed via corepack)
  • AI API Keys (optional for basic functionality)

πŸ“¦ Installation

  1. Enable corepack and install dependencies:
corepack enable
corepack prepare pnpm@10.15.0 --activate
cd contextforge-app
pnpm install
  1. Setup environment variables:
# Copy the example environment file
cp .env.example .env

# Edit .env and add your API keys (optional for testing)
# At minimum, you need to set secure secrets for JWT and NextAuth
  1. Initialize the database:
# Generate Prisma client
pnpm prisma generate

# Create/update database schema (SQLite by default)
pnpm prisma db push

# (Optional) Seed with test data
node scripts/seed-test-data.js

πŸƒβ€β™‚οΈ Running ContextForge

Option 1: Simple Development (Recommended for testing)

# Start the Next.js development server
pnpm dev

Access at: http://localhost:3000

Option 2: Full Development (with background services)

# Start app + background workers concurrently
pnpm server:dev

This starts both the web app and background processing services.

Option 3: Docker Compose (Full stack)

# Copy Docker environment file
cp .env.docker .env

# Edit .env with your API keys, then start all services
docker compose up --build

Includes: PostgreSQL, Redis, monitoring, and more.

πŸ”§ Configuration Options

Database Options

Option 1: SQLite (Default - Simple)

# In your .env file:
DATABASE_URL="file:./dev.db"

Option 2: PostgreSQL (Recommended for production)

# In your .env file:
DATABASE_URL="postgresql://user:password@localhost:5432/contextforge"

# Or use Docker Compose which includes PostgreSQL
docker compose up postgres

Feature Configuration

Edit your .env file to enable/disable features:

# AI-powered features (require API keys)
ENABLE_AUTO_CLASSIFICATION="false"  # Auto-categorize content
ENABLE_AUTO_OPTIMIZATION="false"    # AI content optimization
ENABLE_QUALITY_ASSESSMENT="false"   # Quality scoring

# Non-AI features (work without API keys)
ENABLE_DUPLICATE_DETECTION="true"   # Find duplicate content

πŸ”‘ API Keys Setup

To use AI features, add your API keys to .env:

# Get these from your AI provider dashboards
OPENAI_API_KEY="sk-..."           # OpenAI GPT models
ANTHROPIC_API_KEY="sk-ant-..."    # Claude models
GOOGLE_AI_API_KEY="AIza..."       # Gemini models
GITHUB_TOKEN="ghp_..."            # For GitHub imports

Where to get API keys:

πŸ“‚ Project Structure

contextforge-app/
β”œβ”€β”€ app/              # Next.js App Router pages and API routes
β”œβ”€β”€ components/       # Reusable React components
β”œβ”€β”€ lib/              # Utilities, database, AI integrations
β”œβ”€β”€ prisma/           # Database schema and migrations
β”œβ”€β”€ public/           # Static assets
β”œβ”€β”€ scripts/          # Database seeding and utility scripts
└── docs/             # Additional documentation

πŸ› οΈ Development Commands

# Development
pnpm dev              # Start development server
pnpm server:dev       # Start with background services

# Database
pnpm prisma generate  # Generate Prisma client
pnpm prisma db push   # Apply schema changes
pnpm prisma studio    # Database admin UI

# Building
pnpm build           # Build for production
pnpm start           # Start production server

# Code Quality
pnpm lint            # ESLint
pnpm typecheck       # TypeScript check
pnpm test            # Run tests

🐳 Docker Usage

Development Stack

# Start with PostgreSQL, Redis, and monitoring
docker compose -f docker-compose.dev.yml up --build

Production Stack

# Copy and edit environment
cp .env.docker .env

# Start full production stack
docker compose up --build

Services included:

  • ContextForge App (http://localhost:3000)
  • PostgreSQL (port 5432)
  • Redis (port 6379)
  • Nginx (ports 80/443)
  • Qdrant Vector DB (port 6333)
  • Prometheus Monitoring (port 9090)
  • Grafana Dashboards (http://localhost:3001)

πŸ“Š Monitoring & Analytics

Built-in Analytics

External Monitoring (Docker only)

πŸ” Troubleshooting

Common Issues

1. Database Connection Errors

# Reset database
pnpm prisma db push --force-reset
pnpm prisma generate

2. Missing Dependencies

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

3. Port Conflicts

# Kill processes on port 3000
lsof -ti:3000 | xargs kill -9

4. AI Features Not Working

  • Verify API keys in .env file
  • Check API key permissions and quotas
  • Enable features in .env: ENABLE_AUTO_CLASSIFICATION="true"

🎯 Core Features

βœ… Working Features

  • Content Management: Create, edit, organize prompts/agents/rules
  • Folder System: Hierarchical organization with auto-suggestions
  • Search & Filter: Find content by name, type, or tags
  • Import/Export: File uploads and batch operations
  • Version Control: Track changes and maintain history
  • Sharing: Generate shareable links for content
  • Analytics: Usage tracking and performance metrics

🚧 Known Issues (Being Fixed)

  • GitHub import may not process all file types correctly
  • Sidebar organization needs improvement
  • Prompt detail page could be more intuitive
  • Some AI features require additional configuration

πŸ“š Documentation

  • Docs Index: /docs/README.md
  • Repository Guidelines: /AGENTS.md
  • Architecture Overview: /docs/architecture/overview.md
  • Development Guide: /docs/guides/development.md
  • Testing Playbook: /docs/guides/testing.md
  • API Specification: /docs/api/openapi.yaml

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and test thoroughly
  4. Commit: git commit -m 'Add amazing feature'
  5. Push: git push origin feature/amazing-feature
  6. Create a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ†˜ Support


Need help getting started?

  1. Run pnpm dev to start the development server
  2. Visit http://localhost:3000
  3. Create your first prompt or agent to test the system
  4. Add API keys in Settings > API Keys when you're ready for AI features

About

ContextForge is an AI-powered context management platform that helps developers, agencies, and AI builders organize, optimize, and collaborate on prompts, agents, rules, and workflows. With robust GitHub importing, AI-driven optimization, and an intuitive directory system, ContextForge makes it easy to build your own vibe‑coding context hub.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages