An AI-powered context management platform for organizing, optimizing, and collaborating on prompts, agents, rules, and templates.
- Node.js 18+ (recommended: use
corepack
for package manager) - pnpm (managed via corepack)
- AI API Keys (optional for basic functionality)
- Enable corepack and install dependencies:
corepack enable
corepack prepare pnpm@10.15.0 --activate
cd contextforge-app
pnpm install
- 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
- 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
# Start the Next.js development server
pnpm dev
Access at: http://localhost:3000
# Start app + background workers concurrently
pnpm server:dev
This starts both the web app and background processing services.
# 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.
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
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
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:
- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/
- Google AI: https://aistudio.google.com/app/apikey
- GitHub: https://github.com/settings/tokens
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
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
# Start with PostgreSQL, Redis, and monitoring
docker compose -f docker-compose.dev.yml up --build
# 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)
- Access analytics at http://localhost:3000/dashboard/analytics
- View API usage, costs, and performance metrics
- Export reports in multiple formats
- Grafana Dashboards: http://localhost:3001 (admin/admin123)
- Prometheus Metrics: http://localhost:9090
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"
- 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
- 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
- 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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and test thoroughly
- Commit:
git commit -m 'Add amazing feature'
- Push:
git push origin feature/amazing-feature
- Create a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: https://github.com/mgunnin/contextforge/issues
- Discussions: https://github.com/mgunnin/contextforge/discussions
Need help getting started?
- Run
pnpm dev
to start the development server - Visit http://localhost:3000
- Create your first prompt or agent to test the system
- Add API keys in Settings > API Keys when you're ready for AI features