Want to change Nakama itself? This page is the short path. For the full checklist (style, cassette tests, docs conventions), see [CONTRIBUTING.md](https://github.com/ahmadrosid/nakama/blob/main/CONTRIBUTING.md) on GitHub.

## Run locally

You need [Bun](https://bun.sh) 1.3+, git, and optionally the [GitHub CLI](https://cli.github.com/) for PRs.

```bash
git clone https://github.com/ahmadrosid/nakama.git
cd nakama
bun install
bun run dev:web
```

Open the web dashboard at http://localhost:3003. `dev:web` starts the API if needed.

Other entry points:

```bash
bun run dev:server   # API only
bun run dev:cli      # terminal client
```

If you run the Docker single-container image instead, the dashboard is at http://localhost:4310 (API, web, and platform workers together).

## Where to look

| Area | Path |
|---|---|
| API and agent runtime | `apps/server` |
| Dashboard | `apps/web` |
| CLI | `apps/cli` |
| Channel workers | `apps/platform/{telegram,whatsapp,discord,automation}` |
| Shared libraries | `packages/{core,agent,db,client}` |
| User docs (this site) | `docs/website` |

Deeper layout and conventions: [AGENTS.md](https://github.com/ahmadrosid/nakama/blob/main/AGENTS.md), system design: [ARCHITECTURE.md](https://github.com/ahmadrosid/nakama/blob/main/ARCHITECTURE.md).

## How to test

```bash
bun test
bun run check    # Biome via Ultracite
bun run knip     # unused files, dependencies, and exports (CI fails on findings)
```

Assert behavior, not exact prompt or error copy. Live LLM tests use MSW cassettes (`*.llm.test.ts`); see [CONTRIBUTING.md](https://github.com/ahmadrosid/nakama/blob/main/CONTRIBUTING.md#testing) for replay and `LLM_VCR_MODE=record`.

Docs-only changes: register new MDX pages in `meta.json`, link them from the [Documentation](/docs) hub, then run `bun run build:docs`.

## Open a pull request

1. Branch from `main` (or fork first)
2. Keep the PR to one concern
3. Push and create the PR with `gh pr create`
4. In the body: what changed, what you verified, remaining risks
5. Wait for CI to pass

## Links

- [GitHub repository](https://github.com/ahmadrosid/nakama)
- [CONTRIBUTING.md](https://github.com/ahmadrosid/nakama/blob/main/CONTRIBUTING.md)
- [Discord](https://discord.gg/qhKbMFEUc)