Skip to main content
GenieHelper is built on open-source primitives and welcomes contributions from developers who want to improve the platform. This guide covers everything you need to get a local development environment running and contributing code.

​
Prerequisites

1

Install Node.js >= 18

The server and dashboard both require Node.js 18 or later. Use node --version to confirm.
node --version  # must be >= 18.0.0
2

Install Python 3.10+

Python is required for surgical_context.py (JIT skill hydration) and the Crawl4AI document collector.
python3 --version  # must be >= 3.10
3

Install PostgreSQL 16

The primary database. Install the pgvector and AGE extensions. A Docker Compose file is provided at cms/docker-compose.yml.
docker compose -f cms/docker-compose.yml up -d
4

Install Redis

Required by BullMQ for the job queue. The same Docker Compose file starts Redis alongside PostgreSQL and Directus.
5

Install Ollama

Local LLM inference. Install Ollama and pull the three models used by GenieHelper:
ollama pull dolphin3:8b-llama3.1-q4_K_M
ollama pull dolphin-mistral:7b
ollama pull qwen2.5:latest

​
Required services

All services are managed by PM2 in production. For local development, you can start them individually or use the PM2 ecosystem file.
ServicePortStart command
AnythingLLM server3001cd server && node index.js
Directus CMS8055docker compose -f cms/docker-compose.yml up
Dashboard3100cd dashboard && npm run dev
Media Worker—cd media-worker && node index.js
Ollama11434ollama serve (systemd on Linux)
The Stagehand browser automation server (port 3002) and PinchTab are only required if you are working on onboarding or platform scraping features.

​
Environment variables

Create server/.env by copying server/.env.example. The following variables are required:
VariableDescription
CREDENTIALS_ENC_KEY_B64Base64-encoded 256-bit AES key for platform credential encryption. Generate with: openssl rand -base64 32
DIRECTUS_ADMIN_TOKENDirectus admin token. Used only by register.js and rbacSync.js (pre-auth flows).
MCP_SERVICE_TOKENScoped Directus service token used by all other server-to-Directus calls.
DEFAULT_NEW_USER_TIERTier assigned to new registrations. Default: pro. Valid values: starter, creator, pro, studio.
RBAC_SYNC_WEBHOOK_SECRETShared secret for the Directus → rbacSync webhook. Also used by credentials.js for server-to-server auth.
Never commit .env files. CREDENTIALS_ENC_KEY_B64 protects all stored platform credentials. If this key is lost or rotated, all stored credentials become unrecoverable.
Optional variables that enable additional functionality:
VariableDescription
ANTHROPIC_API_KEYEnables the PowerAdmin Claude bypass for admin users in genieChat.js. Not required for regular creator flows.
ANYTHINGLLM_API_KEYAPI key for the AnythingLLM workspace API (auto-generated at setup).
LLM_URLOverride for the AnythingLLM internal URL. Default: http://127.0.0.1:3001.

​
Code standards

​
Linting and formatting

The project uses ESLint + Prettier. Run checks before pushing: 
npm run lint       # ESLint
npm run format     # Prettier
No warnings are allowed in CI. Fix all lint issues before opening a pull request.

​
Documentation

All exported functions and modules require JSDoc comments: 
/**
 * Encrypt a JSON object with AES-256-GCM.
 * @param {object} data - The object to encrypt
 * @returns {string} Base64-encoded encrypted blob including IV and auth tag
 */
function encryptJSON(data) { ... }

​
Directus access rules

Never call Directus directly with raw fetch() from business logic. All Directus reads and writes in server code must go through:
  • serviceClient from server/utils/directusClient.js (standard case)
  • adminFetch from server/utils/directusClient.js (permitted exceptions: credentials.js, register.js, rbacSync.js)
  • cms.directus MCP tools (for writes from agent flows)
This constraint exists to enforce centralized auth, consistent error handling, and auditability.

​
Commit conventions

All commits follow the Conventional Commits format: 
type(scope): description
Types:
TypeWhen to use
featNew feature or capability
fixBug fix
docsDocumentation changes
choreDependency updates, config changes, tooling
refactorCode restructure with no behavior change
testAdding or updating tests
perfPerformance improvement
Scopes: mcp, auth, dashboard, directus, bullmq, stagehand, ollama, pinchtab, nginx, onboarding Examples: 
feat(mcp): add process_media tool to directus MCP server
fix(auth): resolve JWT refresh race condition in dashboard
docs(readme): update server/ README with new MCP tools
chore(deps): vendor stagehand fork v0.4.2
refactor(queue): split media-worker into operations/ modules

​
Branch strategy

BranchPurpose
mainProduction — deployed on the server
developIntegration — all feature branches merge here first
feature/{ticket}-{description}New features (e.g., feature/G-2-skill-rewrites)
fix/{ticket}-{description}Bug fixes (e.g., fix/BUG-004-jwt-refresh)
hotfix/{description}Emergency production fixes that bypass develop
All pull requests target develop. Merges to main are done by the maintainer after integration testing.

​
Where help is needed

These are the open work items where external contributions are most valuable:

G-2: Skill Rewrites

28 remaining backend skill thin-rewrites into the canonical 3-layer format (context → tools → output schema).

FP-Growth Mining

Cross-user pattern mining in memory/consolidation/cross_user/. Requires knowledge of FP-Growth algorithms.

H-series: Platform Publishing

Automated post publishing to OnlyFans, Fansly, and Instagram via PinchTab browser automation.

J-series: E2E Tests

End-to-end test suite covering the full agent pipeline, onboarding flow, and media worker.
See the roadmap for full detail on all open work items.

Build docs developers (and LLMs) love

Get started for freeTalk to us