Skip to main content
These notes target contributors working inside the sevvo monorepo. If you are just deploying the agent in your environment, see Deploying the agent instead.

​
Stack

  • Package manager: pnpm 9.15.9 (pinned in package.json).
  • Development orchestrator: Tilt.
  • Node: 20+.
  • Workspaces: apps/* and packages/* (see pnpm-workspace.yaml).

​
Layout

​
Setup

The agent’s Prisma client is generated automatically in a postinstall hook. Install Tilt, the Temporal CLI, and PostgreSQL 17 before starting the full development environment. Tilt stores the local Postgres cluster and Temporal database under the ignored .tilt/ directory.

​
Running everything

From the repo root:
This opens Tilt and starts the web app, Convex, the agent, and the agent’s local Postgres and Temporal dependencies as separate resources. Tilt initializes the databases, applies Prisma migrations, shows each service’s logs, and reports readiness for the long-running services. The docs site is available as a manual Tilt resource, or can be run directly when editing docs:

​
Running a single app

​
Agent credentials

See Deploying the agent → Environment variables for the full list. For local dev, provision a SEVVO_AGENT_TOKEN and configure SEVVO_INTERNAL_CONTROL_PLANE_URL and SEVVO_INTERNAL_AUTH_BASE_URL in apps/agent/.env.local. Tilt supplies Postgres on port 55432 and Temporal on port 7233; use these local values:

​
Shared checks

Each runs across all workspaces via pnpm’s recursive workspace runner.

​
Adding shadcn components

Never hand-author shadcn primitives. Use the CLI so files pick up the repo’s customized base-luma style, Tailwind v4 tokens, Hugeicons, and menu color conventions:

​
Adding a docs page

  1. Create <slug>.mdx in apps/docs/ with frontmatter:
  2. Add the slug (no extension) to the appropriate pages array in apps/docs/docs.json.
  3. Preview with pnpm --filter @sevvo/docs preview.
  4. Run pnpm --filter @sevvo/docs check to catch broken links.