Contributing

Genie is built with Bun and TypeScript. This guide covers setting up a development environment, running quality gates, and building plugins. We build in public because that’s the only honest way to build developer tools.

Development Setup

Prerequisites

Tool	Version	Purpose
Bun	1.x	Runtime, bundler, test runner
tmux	3.x+	Agent transport (required)
git	2.x+	Version control, worktrees
Claude Code	Latest	AI agent backend

Clone and Install

git clone https://github.com/automagik-dev/genie.git
cd genie
bun install

Build

Genie bundles to a single file for distribution:

bun run build

This produces dist/genie.js (~305KB minified) with all dependencies inlined. The shebang #!/usr/bin/env bun makes it directly executable. No runtime dependencies need to be co-located.

Run from Source

During development, run directly from source:

bun run src/genie.ts

Or link globally for the genie command to point at your source:

bun link

Code Style

Genie uses Biome for formatting and linting.

Rule	Setting
Quotes	Single quotes
Indentation	2 spaces
Line width	120 characters
Trailing commas	Always
Commits	Conventional commits (commitlint)

No console.log

console.log is banned in source files via a Biome rule. Use structured logging or the CLI output functions instead. The rule is relaxed in test files.

Quality Gates

Run the full quality gate with:

bun run check

This runs four checks in sequence:

Gate	Command	What It Checks
Type check	`bun run typecheck`	`tsc --noEmit` — all type errors
Lint	`bun run lint`	Biome rules — formatting, code quality
Dead code	`bun run dead-code`	`bunx knip` — unused exports, dependencies
Tests	`bun test`	All `*.test.ts` files

bun run dead-code (knip) has pre-existing false positives for biome, commitlint, and husky devDeps. These are not regressions.

Running Individual Gates

bun run typecheck           # Type checking only
bun run lint                # Linting only
bun run dead-code           # Dead code detection only
bun test                    # All tests
bun test src/lib/wish-state.test.ts  # Single file

Testing

Framework

Tests use bun:test (import from 'bun:test').

Conventions

Convention	Detail
File pattern	Colocated `*.test.ts` next to source
Fixtures	tmpdir with cleanup in `afterEach`
Git tests	Real git repos in `/tmp`, not mocks
Concurrency	`Promise.allSettled()` pattern
Isolation	Set `process.env.GENIE_HOME` to tmpdir

Example Test

import { afterEach, describe, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

describe('myModule', () => {
  let tempDir: string;

  afterEach(() => {
    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
  });

  test('does the thing', () => {
    tempDir = mkdtempSync(join(tmpdir(), 'genie-test-'));
    process.env.GENIE_HOME = tempDir;

    // ... test code ...

    expect(result).toBe(expected);
  });
});

Project Structure

src/
├── genie.ts                 # CLI entry point (commander.js)
├── lib/                     # Core modules
│   ├── wish-state.ts        # PG-backed wish state machine
│   ├── agent-registry.ts    # Worker registry (global JSON)
│   ├── team-manager.ts      # Team CRUD with git clone --shared
│   ├── protocol-router.ts   # Provider-agnostic message routing
│   ├── mailbox.ts           # Durable message store
│   ├── nats-client.ts       # NATS pub/sub singleton
│   ├── db.ts                # pgserve connection management
│   ├── db-migrations.ts     # SQL migration runner
│   ├── task-service.ts      # PG CRUD for task lifecycle
│   ├── scheduler-daemon.ts  # Cron trigger loop
│   ├── transcript.ts        # Provider-agnostic log reading
│   ├── claude-logs.ts       # Claude Code log parser
│   ├── codex-logs.ts        # Codex log parser
│   ├── auto-approve.ts      # Layered trust configuration
│   └── tmux.ts              # tmux wrapper
├── term-commands/           # CLI command handlers
├── genie-commands/          # Setup/utility commands
├── hooks/                   # Claude Code hook system
│   ├── index.ts             # Hook dispatch entry
│   └── handlers/            # Individual hook handlers
├── db/migrations/           # SQL migration files
├── types/                   # Shared Zod schemas
└── ...
skills/                      # Skill prompt files (SKILL.md)

Plugin Development

Genie supports plugins that extend the CLI with additional commands, hooks, and skills.

Plugin Structure

plugins/<plugin-name>/
├── package.json            # Plugin metadata
├── settings.json           # Claude Code settings overlay
├── hooks/
│   └── hooks.json          # Additional hook definitions
├── .claude-plugin/
│   └── plugin.json         # Plugin registration
└── src/                    # Plugin source code

Plugin Registration

Plugins are registered in openclaw.plugin.json at the repo root:

{
  "name": "genie",
  "version": "1.0.0",
  "plugins": ["plugins/genie"]
}

Adding Skills

Skills are markdown files that define agent behavior. To add a new skill:

Create skills/<skill-name>/SKILL.md
Add frontmatter with name, description, and optional triggers
Write the skill prompt in the body

---
name: my-skill
description: Does something useful
triggers:
  - "/my-skill"
  - "run my skill"
---

# My Skill

Instructions for the agent when this skill is invoked...

Skills are loaded dynamically — no registration needed beyond creating the file.

Commit Conventions

Genie uses conventional commits enforced by commitlint:

Prefix	Use
`feat:`	New features
`fix:`	Bug fixes
`chore:`	Maintenance
`docs:`	Documentation
`refactor:`	Code restructuring
`test:`	Test additions/fixes

Branch Naming

feat/<description>
fix/<description>
chore/<description>
docs/<description>
refactor/<description>
test/<description>

PR Workflow

Branch from dev
Make changes, commit with conventional messages
Push and create PR targeting dev
Human reviews and merges dev → main when ready

Known Gotchas

File lock timeout force-removes are intentional — prevents deadlocks from crashed processes. The open('wx') after unlink is atomic, so only one process wins.
Hook dispatch has a 15-second hard timeout — handlers that exceed this silently timeout.
System prompt injection can fail silently — if the prompt file write fails, Claude Code dies on startup trying to read it.
Mailbox delivery is best-effort — dead pane = message stays deliveredAt: null forever.

Community

Genie is open source and we want your help — code, docs, bug reports, wild ideas, even polite disagreements about our architecture choices. Especially those, actually.

Discord

Chat with contributors, ask questions, share what you’re building.

GitHub

Issues, PRs, and the code itself. Star if you’re feeling generous.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Contributing

Contributing

Development Setup

Prerequisites

Clone and Install

Build

Run from Source

Code Style

No console.log

Quality Gates

Running Individual Gates

Testing

Framework

Conventions

Example Test

Project Structure

Plugin Development

Plugin Structure

Plugin Registration

Adding Skills

Commit Conventions

Branch Naming

PR Workflow

Known Gotchas

Community

Discord

GitHub

​Contributing

​Development Setup

​Prerequisites

​Clone and Install

​Build

​Run from Source

​Code Style

​No console.log

​Quality Gates

​Running Individual Gates

​Testing

​Framework

​Conventions

​Example Test

​Project Structure

​Plugin Development

​Plugin Structure

​Plugin Registration

​Adding Skills

​Commit Conventions

​Branch Naming

​PR Workflow

​Known Gotchas

​Community

Discord

GitHub

Contributing

Development Setup

Prerequisites

Clone and Install

Build

Run from Source

Code Style

No console.log

Quality Gates

Running Individual Gates

Testing

Framework

Conventions

Example Test

Project Structure

Plugin Development

Plugin Structure

Plugin Registration

Adding Skills

Commit Conventions

Branch Naming

PR Workflow

Known Gotchas

Community