# Contributing to Mozart

Thanks for your interest in contributing! This guide will get you set up.

## Prerequisites

- **[Bun](https://bun.sh/)** v1.1+ — JavaScript runtime and package manager
- **[Podman](https://podman.io/)** — container engine (Docker alternative, rootless by default)
- **macOS/Linux** — Podman on Windows requires WSL2

## Development Setup

```bash
# Clone and install
git clone https://github.com/<your-org>/mozart.git
cd mozart
bun install

# Set up Podman and build the agent container image
bun run src/index.ts setup

# Set your OpenRouter API key
export OPENROUTER_API_KEY=sk-or-...

# Run in dev mode (hot-reloads agent code)
bun run dev
```

## Project Structure

```
src/
  index.ts          CLI entry point (Commander)
  server.ts         HTTP daemon (Hono)
  supervisor.ts     Agent lifecycle orchestrator
  podman.ts         Podman container abstraction
  horcrux.ts        Agent state serialization
  types.ts          Supervisor-side domain types
  mailbox.ts        Async channel primitives
  agent/
    agent.ts        Core Agent class (LLM loop, tools)
    worker.ts       Container entry point (stdin/stdout JSON protocol)
    tools.ts        Built-in agent tools (18 tools)
    memory.ts       SQLite persistence (messages, FTS5, schedules)
    types.ts        Agent-side shared types
    llm/
      provider.ts   OpenRouter API client
      types.ts      LLM message types
      tools.ts      Tool base class and registry
      scheduler.ts  Cron scheduler
ui/                 Svelte 5 chat interface
tests/              Test suite
```

## Running Tests

```bash
# Run all tests
bun test

# Run a specific test file
bun test tests/agent.test.ts

# Run with coverage
bun test --coverage
```

## Code Style

We use [Biome](https://biomejs.dev/) for linting and formatting.

```bash
# Check for lint and format issues
bun run lint

# Auto-fix what can be fixed
bun run format:check
```

Biome is configured in `biome.json`. Key conventions:
- Double quotes for strings
- Tabs for indentation (Biome default)
- No unused imports or variables

## Making Changes

1. **Fork and branch** — Create a feature branch from `main`
2. **Write tests** — Non-trivial changes should include tests
3. **Run the suite** — `bun test && bun run lint` must pass
4. **Keep commits focused** — One logical change per commit
5. **Open a PR** — Describe what changed and why

## Architecture Notes

Mozart uses a supervisor pattern: the host process manages agent lifecycles via Podman containers. Communication between the supervisor and agents uses JSON-line IPC over stdin/stdout.

Key design decisions:
- **Podman over Docker** — rootless containers, no daemon dependency
- **`.soul` files** — declarative agent definitions (model, identity, rules, schedules)
- **SQLite per agent** — each agent has its own database for messages and memory
- **EventBus** — fan-out event distribution for SSE streaming to clients

See the [README](README.md) for architecture diagrams and the full API reference.