Skip to content
2 min read · 463 words

Development Workflow

Two terminals, hot reload on both sides, and a short verification loop. This page is the daily-driver reference.

The setup (once)

Covered in Installation: uv sync in backend/, npm install in frontend/, OPENAI_API_KEY in backend/app/.env.

The loop

bash
# Terminal 1 — backend with hot reload
cd backend/app
uv run uvicorn main:app --reload --port 8001
 
# Terminal 2 — frontend with hot reload
cd frontend
npm run dev
While working on…Verify with
Backend endpointsSwagger UI http://localhost:8001/docs or curl; watch the uvicorn console for tracebacks
Backend behaviorthe telemetry itself — GET .../runs, .../tool-calls, .../workflow-runs (Observability)
Frontendhttp://localhost:3000 + npm run typecheck before committing
Database statesqlite3 backend/app/agentops.db (queries)
Docsuv run mkdocs serve from the repo root — treat warnings as failures

Command reference

WhereCommandPurpose
backend/uv syncinstall/update deps from lockfile
backend/app/uv run uvicorn main:app --reload --port 8001dev server
frontend/npm run dev / build / startdev / prod build / serve
frontend/npm run typecheckthe one mechanical gate — run it every time
repo rootuv run mkdocs serve / builddocs preview / build check

There is no linter, formatter config, or test runner in either project yet (Testing) — typecheck and build warnings are the gates that exist.

Making common changes safely

ChangeFollow
New backend endpoint (+ UI access)Add an Endpoint
New agent toolAdd a Tool
New column on an existing tableAdd a Migration — don't skip the migration entry
Prompt editsrules in Prompt System
New UItokens only — Design System

Development gotchas (learned the hard way)

  • Start uvicorn from backend/app/, or you get import errors — or worse, a fresh empty DB in the wrong directory (Troubleshooting).
  • --reload reruns startup on every save — create_all + migrations are idempotent, so this is safe, just noisy.
  • Deleting agentops.db without deleting chroma_db/ leaves orphan vectors that still match searches for reused agent IDs.
  • The scratch files (delete.py, practice_solution.py, …) are not part of the app — don't extend them (Project Structure).
  • Two uv projects — root (docs) and backend/ (API). uv sync in the right directory.

Git conventions

Work on branches, keep main deployable (it auto-deploys the docs site). Commit messages in the repo's history follow a loose conventional style (fix: ..., docs: ...) — match it. PR expectations: Contributing.

PreviousKnown IssuesNextCoding Standards