git clone https://github.com/<owner>/plexus.git
cd plexus
bun installRunning bun install automatically installs git hooks via Lefthook (the prepare script runs lefthook install). No extra setup is needed.
Plexus uses Drizzle ORM with dual-dialect support (SQLite and PostgreSQL). Schema definitions live in:
packages/backend/drizzle/schema/sqlite/-- SQLite table definitionspackages/backend/drizzle/schema/postgres/-- PostgreSQL table definitions
- Edit the schema
.tsfiles in the appropriate dialect directories - If adding a new table, update the index exports in
packages/backend/drizzle/schema/index.ts - (Optional) Validate locally by running
bun run generate-migrationsfrompackages/backend/-- this confirms your schema produces valid migration SQL. The name is auto-derived from your branch; you can also specify--name <descriptive-name>explicitly. - Do NOT commit migration artifacts (
.sqlfiles,meta/_journal.json, snapshot files). Only commit the schema.tsfiles. - Open your PR. Migrations are auto-generated by CI after your PR merges to
main.
Drizzle migrations use sequential numbering. When multiple PRs include migrations, they collide on merge (e.g., two PRs both generate migration 0030). By keeping migration generation as a post-merge CI step, conflicts are impossible.
The pre-commit hook prevents accidentally committing migration files. If it fires:
# Remove migration files from your staged changes
git reset HEAD -- packages/backend/drizzle/migrations/ packages/backend/drizzle/migrations_pg/Then commit again with only your schema .ts files.
The hooks are skipped automatically when CI=true (GitHub Actions). To skip locally in exceptional circumstances:
LEFTHOOK=0 git commit -m "..."The project uses separate Drizzle ORM config files for each database dialect:
drizzle.config.sqlite.ts-- SQLite configurationdrizzle.config.postgres.ts-- PostgreSQL configuration
When running Drizzle Kit commands, specify the appropriate config file with --config.
Plexus uses PR Agent Review (.github/workflows/pr-agent-review.yml) for automated code reviews. It is triggered when non-draft pull requests are opened, reopened, marked ready for review, or updated with comments, and is configured via .pr_agent.toml.
OpenCodeReview reviews are optional and are not part of the commit hooks. If opencodereview is available and a review is useful, run the command matching the changes from the repository root:
- Workspace changes (staged, unstaged, and untracked — OCR has no separate staged/unstaged mode):
bun run code:review - Branch against
origin/main:bun run code:review:branch - Latest commit:
bun run code:review:commit
Load the opencodereview-cli skill before invoking OpenCodeReview. If it is unavailable, skip the review without installing or configuring it. Do not invoke it automatically during commits.
All code must be formatted with bun fmt (Bun 1.4.4+) before committing. Configuration, including ignorePatterns for generated and vendored paths, lives in the [fmt] section of bunfig.toml.
bun run format # format everything
bun run format:check # verify without writing
bun run format:changed # format only files changed vs. the default branchThe pre-commit hook runs bun fmt --staged, which formats just the staged files and re-stages them, so you normally don't need to run the formatter by hand.
From the repo root:
bun test # whole suite, one process
bun test --changed=HEAD # only tests affected by uncommitted changes
bun test --parallel # spread files across cores (what CI and the pre-commit hook use)Run plain bun test before pushing: it shares one process across all files, so it catches mock and global leaks that --parallel hides. Before writing or changing a test, read docs/TESTING.md — it covers how to mock, fake timers and fetch, and which patterns leak between files.
The pre-commit hook runs the affected tests automatically (bun test --parallel --changed=HEAD).
bun run devThis starts the backend (with file watching) and the frontend builder in parallel.
If you use mise but do not have it activated in your shell, run the same command through mise:
mise exec -- bun run devThe port is derived automatically from the worktree directory name, so two worktrees can run simultaneously without collision. The port and database are printed at startup:
Starting Plexus Dev Stack...
PORT: 14641
DATABASE_URL: sqlite:///tmp/plexus-browsertesting.db
ADMIN_KEY: password
Override any of these with environment variables:
PORT=4000 ADMIN_KEY=mysecret bun run devWhen frpc is available on PATH and both FRPC_SERVER_ADDR and
FRPC_AUTH_TOKEN are set, the dev server starts an HTTP FRP tunnel after the
local health check passes. The generated subdomain is based on the repository
and worktree names, so each worktree gets its own stable route. For direct dev
processes, the tunnel stops with the dev server; Paseo tears it down when it
stops the managed dev service.
FRP is optional. If frpc is not installed, or the required variables are not
set, the dev server runs normally without a tunnel. The project mise.toml
declares frpc for mise users; run mise install once if it is not installed.
Users who do not use mise can install frpc separately and put it on PATH.
export FRPC_SERVER_ADDR=your-frps-host
export FRPC_AUTH_TOKEN=your-frps-token
export FRPC_SUBDOMAIN_HOST=dev.home.cowger.us # optional, display only
mise exec -- bun run devFRPC_SERVER_PORT is optional and defaults to 7000. FRPC_SUBDOMAIN_HOST
is only used to print the full HTTPS URL; frps remains responsible for the
actual subdomain suffix through its subDomainHost setting.
To get the current worktree's FRP URL without scraping startup logs, run:
bun run dev:get:frp-urlUse bun run dev:get:frp-url -- --hostname, --subdomain, or --json for a hostname, subdomain, or machine-readable result. Use --file to print the path of the temporary URL file written while the tunnel is running. The command derives the same deterministic endpoint as the dev lifecycle; it does not check whether the tunnel is reachable.
For a background dev stack, use the agent lifecycle commands. They work with Paseo when available and fall back to direct process execution otherwise:
bun run dev:agent --detach
bun run dev:stopbun run dev:agent starts or attaches to a workspace script target, defaulting to dev:full, with automatic log streaming. Use --detach to return once the stack is healthy and leave it running in the background. Select a target with bun run dev:agent [target], for example bun run dev:agent dev:pglite --detach; stop it with bun run dev:stop [target].
Prefix these commands with mise exec -- when mise is not activated. Paseo
inherits the environment of the process that launches it. If you want a
Paseo-managed service to use the mise-managed frpc binary, make sure Paseo
itself runs with the project mise environment.
dev:stop stops the dev process and its FRP child. clear-dev only resets the
local data and restarts the backend; it does not replace dev:stop.
To run against an in-process PGlite database instead of SQLite — useful when testing Postgres-specific behaviour without running a real server:
bun run dev:pgliteThe startup output shows the data directory instead of a database URL:
Starting Plexus Dev Stack...
PORT: 14641
DB Driver: PGlite
DB Data Dir: /tmp/plexus-browsertesting.pglite
ADMIN_KEY: password
The data directory persists across restarts (same worktree isolation as SQLite).
Override it with PLEXUS_PGLITE_DATA_DIR=/path/to/dir bun run dev:pglite.
After starting the dev server, seed it with a realistic baseline configuration (providers, model aliases, quota definitions, and API keys) that exercises the full feature set without requiring any real external credentials:
bun run populate-devThis is idempotent — safe to re-run at any time. It uses PUT throughout, so
existing resources are replaced rather than duplicated.
| Category | Count | Notes |
|---|---|---|
| Providers | 11 | Frontier cloud providers (Kilocode, Wisgate, Neuralwatt, OpenRouter, Google, OpenAI, Anthropic, CC, CC-Sigma, OpenLimits, Ozore) |
| Quotas | 2 | Daily, weekly budgets and limits |
| Model aliases | 19 | Frontier model architectures (gpt-5.x, claude-4.5/5, gemini-3.5, deepseek-v4) for chat, embeddings, speech, transcriptions |
| API keys | 4 | Default, OWUI, GithubKey, GHAKey |
All provider URLs are mapped to their real production API gateways, but with safe, redacted mock keys by default. No real secrets are checked into the codebase.
Create scripts/user-populate.json (git-ignored — see scripts/user-populate.example.json
for the format). Anything in that file is merged over the defaults when you run
bun run populate-dev, so you can add real provider keys or personal aliases
without touching committed files and without risk of accidentally leaking secrets.
| Variable | Default | Purpose |
|---|---|---|
PLEXUS_URL |
http://localhost |
Base URL of the target instance |
PLEXUS_PORT |
derived from cwd | Port (matches bun run dev automatically) |
PLEXUS_ADMIN_KEY |
password |
Admin key |
To wipe the database and restart the backend in one step:
bun run clear-devThis deletes the SQLite file from /tmp and sends SIGHUP to the running dev
server, which gracefully shuts down the backend and immediately relaunches it
against the empty database. The frontend is unaffected. The whole cycle takes
about two seconds.
After clearing, re-run bun run populate-dev to restore the baseline config.
Note:
clear-devrelies on a PID file written bybun run devto/tmp/plexus-<worktree>.pid. If the server is not running, it will delete the database file and exit cleanly without error.