Skip to content
Kodakodadocs
Contributing

Development setup

Run Koda from source and test locally.

Running Koda from source is the path for contributors and anyone who wants to touch the Python backend or the Next.js dashboard. The repository is a mono-repo; a single clone gives you everything.

Prerequisites

  • Docker and Docker Compose.
  • Python 3.11+ (pyproject enforces >=3.11).
  • Node.js 20+ and pnpm.
  • A POSIX-like shell. Windows contributors should use WSL 2.

Clone and bootstrap

bash
git clone https://github.com/OpenKodaAI/koda.git
cd koda

Two scripts cover the usual starts. The wrapper handles Docker and Node prerequisites on apt-based Linux with sudo; on macOS or WSL install the prerequisites yourself.

bash
./scripts/install.sh    # same path a user would take
# …or, if prerequisites are already in place:
cp .env.example .env
docker compose up -d --build

Backend development

Install the Python project in editable mode with the dev extras:

bash
pip install -e ".[dev]"

Standard checks before pushing:

bash
ruff check .
ruff format --check .
mypy koda/ --ignore-missing-imports
pytest --cov=koda --cov-report=term-missing
Running a subset of tests

pytest koda/memory/tests/ -k recall runs just the memory recall tests with substring matching. Use -x to stop on the first failure while iterating.

Web dashboard development

bash
pnpm install
cp apps/web/.env.example apps/web/.env.local
pnpm dev:web

The dev server runs on http://127.0.0.1:3000. Set KODA_API_URL in .env.local to point at the running control plane (by default http://127.0.0.1:8090).

Web checks

bash
pnpm lint
pnpm typecheck
pnpm test

Regenerating proto contracts

gRPC service contracts live in proto/. After editing a .proto file, regenerate both the Python and TypeScript bindings:

bash
buf generate

buf.gen.yaml defines the outputs. Regenerated files are committed alongside the .proto change in the same PR.

Database migrations

Migrations live under koda/state/migrations/. Adding a new one is a three-step ritual:

  1. Write the migration file next to the existing ones — numbered, with both up and down sections.
  2. Update the affected typed repositories in koda/state/.
  3. Run docker compose exec app python -m koda.state.migrate against a local compose stack to confirm the migration applies cleanly.

Adding a runtime skill

Drop a new markdown file under koda/skills/. The registry hot-reloads every 30 seconds, so a local dev stack will pick it up without a restart. See Authoring a Skill for the format.

Repository layout

  • koda/ — Python backend: handlers, services, state, memory, skills.
  • apps/web/ — Next.js operator dashboard.
  • packages/cli/ — the @openkodaai/koda npm CLI.
  • proto/ — gRPC service contracts.
  • docs/ — authoritative prose + OpenAPI + architecture diagrams.
  • scripts/ — install wrapper, doctor, and contributor tooling.

Next steps