Skip to content

Development Setup

Complete the local installation in Getting Started first. This page adds the dependencies and checks used when changing Numi.

Requirements

In addition to the local installation requirements, install Node.js 22 and npm to match the frontend checks in CI. Deno is needed to exercise the Pyodide code-interpreter path.

Initial Setup

From the repository root:

make install-dev

This runs uv sync --group dev and npm ci. It installs the Python test, lint, and documentation tools plus the frontend linters and formatter.

Development Workflow

  1. Start the app with make run-web and open http://localhost:4567.
  2. Make the change and run the affected tests.
  3. Run the relevant checks below, then review git diff before committing.

Keep development databases separate from instances containing real accounts and conversations. See Database Migrations before changing models.

Available Commands

Command What it does
make run-web Restores pinned browser assets if missing, then starts the app
make test Runs the Python test suite
npm test Runs the JavaScript behavior tests
make check Checks formatting, lint, unused code, and core-path complexity without editing files
make fix Applies Python and frontend lint fixes and formatting; modifies files
make docs Serves the documentation locally
make docs-build Builds the documentation with warnings treated as errors
make help Lists all available targets

Testing

Run a focused test while working:

uv run pytest tests/test_agent_runtime.py
node --test tests/test_chat_menu.cjs

See Running Tests for the full suite, coverage, and the fixtures already provided by the repository.

Code Quality

For a Python change, check the files you touched:

uv run ruff format --check src/numi_chat/agent/runtime.py
uv run ruff check src/numi_chat/agent/runtime.py

For frontend changes, run the required fix-and-check sequence:

npm run fix:web
npm run check:web
make check

fix:web can modify frontend files outside your change. Review the diff and keep unrelated work intact. make check and make ci-lint are read-only; make fix, make format, and make lint-fix modify files.

Project Structure

Path Start here for
src/numi_chat/agent/ Streaming agent loop, prompts, and message preparation
src/numi_chat/llm/ Model catalog and provider protocol adapters
src/numi_chat/web/ HTTP/WebSocket routes and browser UI
src/numi_chat/services/ Application services, including tool execution
src/numi_chat/tools/ Tool implementations and discovery
src/numi_chat/data/models.py SQLModel table definitions
src/numi_chat/data/db.py Database engine, sessions, and migration startup
migrations/versions/ Alembic schema revisions
tests/ Python and JavaScript tests