Development

Prerequisites

Bun >= 1.0
TypeScript knowledge
NATS server (downloaded by ravi setup)

Setup

git clone https://github.com/filipexyz/ravi.git
cd ravi
bun install
bun run build
bun link    # Makes `ravi` available globally

Build

bun run build     # Compile TypeScript (runs prebuild hooks first)

The build process:

prebuild → gen:commands (generates CLI command registry)
bun build → Bundles src/cli/index.ts into dist/bundle/ with minification
gen:plugins → Writes the packaged internal plugins artifact to dist/bundle/internal-plugins.json

Dev Mode

bun run dev       # Watch mode — auto-restarts on source changes
ravi daemon dev   # Daemon dev mode — watches src/ and auto-rebuilds

Running Locally

# Run CLI commands directly (without building)
bun src/cli/index.ts -- agents list

# Start daemon in foreground
bun src/cli/index.ts -- daemon run

# Start TUI
bun src/tui/index.tsx

Testing

bun test          # Run all tests

Tests cover: bash tool, hooks, router, heartbeat, permissions, triggers, omni consumer, and bot.

Quality Checks

make quality      # Lint + typecheck (no auto-fix)
make lint         # Biome check only
make typecheck    # tsc --noEmit only

Or individually:

bun run lint          # biome check src/
bun run lint:fix      # biome check --write src/
bun run typecheck     # tsc --noEmit

Documentation

bun run docs:dev          # Start Mintlify dev server
bun run docs:list         # List all docs with summaries
bun run docs:check-links  # Validate internal links
bun run lint:docs         # Markdown lint
bun run check:docs        # lint:docs + check-links

Or via Makefile:

make docs         # Start docs dev server
make docs-check   # Lint + check links

When to Restart the Daemon

Restart required:

After bun run build (code changes need the new bundle)
After modifying src/ files (daemon runs the built bundle)

No restart needed:

After any CLI config command (ravi agents set, ravi triggers set, etc.)
CLI writes directly to SQLite and emits NATS refresh signals
The running daemon picks up changes automatically

Git Hooks

The project uses git hooks via .githooks/:

bun run prepare   # Configure git to use .githooks/ directory

The pre-push hook mirrors the CI quality gate locally:

bun run sdk:check
bun run build
bun run typecheck
bun run test

If the generated SDK is stale, the hook runs bun run sdk:generate, leaves the generated files in the worktree, and blocks the push until they are committed. Never use --no-verify on commits or pushes.

Project Structure

src/
├── cli/              # CLI commands (decorators, groups)
│   ├── commands/     # One file per command group
│   └── index.ts      # Entry point
├── bot.ts            # RaviBot — Claude Agent SDK sessions
├── daemon.ts         # Daemon startup/shutdown
├── gateway.ts        # Gateway — response routing
├── nats.ts           # NATS connection singleton
├── omni/             # Omni integration (consumer, sender, config)
├── router/           # Router, session keys, config store
├── permissions/      # REBAC permission engine
├── leader/           # Leader election via NATS KV
├── heartbeat/        # Heartbeat runner
├── cron/             # Cron job runner
├── triggers/         # Event trigger runner
├── ephemeral/        # Ephemeral session cleanup
├── copilot/          # Claude Code inbox watcher
├── audio/            # TTS generation (ElevenLabs)
├── transcribe/       # Audio transcription (Groq/OpenAI)
├── image/            # Image generation (Gemini)
├── video/            # Video analysis (Gemini)
├── spec/             # Spec mode MCP server
├── plugins/          # Plugin system
│   └── internal/     # Built-in plugins (skills, tools)
├── tui/              # Terminal UI (Ink/React)
├── prompt-builder.ts # System prompt construction
└── pm2.ts            # PM2 process management

Adding CLI Commands

CLI commands use decorators. Each command group is a file in src/cli/commands/:

@group("mygroup")
@description("My command group")
class MyGroup {
  @command("list")
  @describe("List items")
  async list() {
    // implementation
  }

  @command("show")
  @describe("Show item details")
  @arg("id", "Item ID")
  async show(id: string) {
    // implementation
  }
}

After adding/modifying commands, run bun run gen:commands to regenerate the command registry.

Adding Skills

Skills are SKILL.md files in src/plugins/internal/ravi-system/skills/:

src/plugins/internal/ravi-system/skills/
├── agents/SKILL.md
├── contacts/SKILL.md
├── cron/SKILL.md
├── heartbeat/SKILL.md
├── triggers/SKILL.md
└── ...

Each SKILL.md has YAML frontmatter (name, description) and markdown content that gets loaded into agent context when relevant. In source/dev mode, skills are discovered directly from src/plugins/internal/**. The packaged artifact is generated by bun run build; do not commit a generated skills registry.

Messaging

Automation

Security

Integrations

Operations

Development

Prerequisites

Setup

Build

Dev Mode

Running Locally

Testing

Quality Checks

Documentation

When to Restart the Daemon

Git Hooks

Project Structure

Adding CLI Commands

Adding Skills

​Prerequisites

​Setup

​Build

​Dev Mode

​Running Locally

​Testing

​Quality Checks

​Documentation

​When to Restart the Daemon

​Git Hooks

​Project Structure

​Adding CLI Commands

​Adding Skills

Prerequisites

Setup

Build

Dev Mode

Running Locally

Testing

Quality Checks

Documentation

When to Restart the Daemon

Git Hooks

Project Structure

Adding CLI Commands

Adding Skills