Thank you for your interest in contributing! This guide will help you get started.
Open an issue using the bug report template. Include:
- Steps to reproduce the issue
- Expected vs actual behavior
- Environment details (OS, Node/Bun version)
- Relevant logs (redact secrets)
Open an issue using the feature request template. Describe the problem you're solving and your proposed approach.
- Node.js >= 20 or Bun >= 1.2
- Docker (optional — for the container stack, or an optional Neo4j for graph analytics)
- Git
git clone https://github.com/fastslack/kernl.git
cd Kernl
npm install # or: bun install
cp .env.example .envEdit .env with at minimum:
SQLITE_PATH=./data/kernel.dbnpm run dev # Start MCP server (stdio mode)
npm run build # Compile TypeScriptThe graph is built in (Relate, embedded). To work against an optional Neo4j:
docker compose -f docker-compose.yml -f docker-compose.neo4j.yml up -d # bolt://localhost:17687Tests use in-memory SQLite and do not require a graph server. Tests that exercise the
real Relate engine run when RELATE_CLIENT_MODULE points at an installed client.
npm test # or: bun testnpx tsc --noEmit # or: npm run lint- TypeScript strict mode with
target: ES2022 - ESM only (
"type": "module"in package.json) - Always use
.jsextensions in import paths (Node16 module resolution) - Zod for input validation (converted to JSON Schema for MCP)
- IDs:
newId()(UUIDv4) - Timestamps:
isoNow()(ISO 8601 UTC) - Results:
textResult(markdown)for success,errorResult(msg)for errors
Every module exports a factory function returning KernelModule:
import type { KernelModule, ModuleContext, ToolDefinition } from "../../core/types.js";
export function createFooModule(): KernelModule {
let tools: ToolDefinition[] = [];
return {
name: "foo",
async initialize(ctx: ModuleContext) {
runMigrations(ctx.sqlite, "foo", fooMigrations);
const service = new FooService(ctx.sqlite, ctx.neo4j);
tools = fooTools(service);
},
getTools() { return tools; },
async shutdown() {},
};
}See ARCHITECTURE.md for details.
- Fork the repository and create a feature branch from
main - Write or update tests for your changes
- Ensure all tests pass:
npm test - Ensure type checking passes:
npx tsc --noEmit - Follow the commit message convention (see below)
- Open a PR against
mainwith a clear description
Use conventional commits:
feat(tasks): add recurring task support
fix(crm): handle empty email in contact search
refactor(dashboard): extract KPI calculation
chore(deps): bump @modelcontextprotocol/sdk to 1.27
test(events): add waitlist promotion tests
docs: update module overview table
Format: type(scope): description
Types: feat, fix, refactor, chore, test, docs, perf, ci
Open a discussion or reach out via an issue.