platform/CLAUDE.md

CLAUDE.md

Project Overview

Officer is a self-hosted personal platform for one person: the server owner. It bundles an AI agent, a terminal, a file browser, a code editor, email, a bitcoin wallet, a remote desktop and customisable dashboards behind a single web app.

Single-user is a hard invariant, not a stage. There is exactly one account, created once by POST /auth/bootstrap while the user table is empty. There are no roles, no invitations, no sandboxing of one user from another, and no per-user isolation anywhere in the codebase. If a change seems to need "which user is this", the answer is always the owner.

Architecture

One Bun process (src/server.tsx) serves everything:

• the React SPA, via Bun's HTML import of src/apps/officer-web/index.html (HMR in dev)
• the REST API, a Hono app mounted at /api (src/servers/hono.ts)
• eight WebSocket providers — terminal, chat, task-runner, pipeline, cliamp, cliamp-audio, desktop, vault — plus a sidecar registration socket. terminal is a byte relay onto the pty sidecar's own listener, not a translating bridge; vault is the same shape onto Vaultwarden's notifications hub.
• a browser relay on its own port (BROWSER_RELAY_PORT, default 18792)

Long-running and privileged work lives in sidecars: separate processes that dial back in over /api/sidecar/register and are tracked in src/servers/sidecar-registry.ts. PM2 runs them (ecosystem.config.cjs): officer (the server), officer-anthropic-proxy, officer-agent, officer-opencode, officer-email, officer-pty, officer-vnc, officer-music, officer-vault, officer-slskd, officer-headscale, officer-transmission, officer-invoiceshelf, officer-wallet, officer-photos, officer-notify, officer-caldav, officer-memos, officer-jellyfin, officer-gitea — twenty as of 2026-08-06, and a list that goes stale every time a sidecar lands. pm2 jlist is the source of truth.

officer-anthropic-proxy and officer-agent are not the same thing. The proxy holds the Anthropic credential and forwards API traffic; the agent is the process that spawns claude. They were one entry named officer-claude until the sidecar-isolation work — which is exactly how the false claim that "restarting officer doesn't disturb the agent" survived so long. Every sidecar is a PM2 peer of officer, so no sidecar is a child of the server and restarting the server does not kill one.

Agents run unsandboxed as the server owner, with --dangerously-skip-permissions. This is deliberate — it is the owner's own machine. Do not add a jail without being asked.

Repository Layout

src/
├── server.tsx              # the single entrypoint: routes, WS upgrades, static files
├── apps/
│   ├── officer-web/        # the SPA shell — Screens/Authentication + Screens/Dashboard
│   └── landing/            # marketing landing page
├── servers/
│   ├── hono.ts             # router composition; everything under /api
│   ├── _middlewares/       # auth, body parsing, origin validation, rate limiting
│   ├── api/<feature>/      # one folder per feature, each exporting a router
│   ├── channels/           # send-claude-code / send-opencode — how /chat drives an agent turn
│   ├── queue/              # background job engine
│   └── sidecar/            # sidecar implementations + the wire protocol
├── databases/officer_db/   # the only database (Postgres + Drizzle)
├── extensions/browser-relay/
└── workspaces/             # shared packages, each a bun workspace

src/workspaces/officerdev is the biggest of these: the windowed "apps" (FileBrowser, Chat, Terminal, CodeEditor, Desktop, Dashboards, Wallet…) that the shell hosts, behind an AppRegistry. src/apps/officer-web is only the shell — screens, routing and settings.

Path aliases (tsconfig.json): @/* → src/apps/officer-web, @/components/* → src/workspaces/components, @@/* → src/servers, @/public/* → public. Workspace packages are imported by their package name (officerdev, hooks, state, types, helpers, …).

Tech Stack

• Runtime: Bun (Node 22 is enforced by a preinstall check)
• Language: TypeScript, strict. bunx tsgo is clean — keep it that way.
• Frontend: React 19, React Router 7, React Query, Tailwind 4, shadcn/ui + custom components
• Backend: Hono
• Database: one Postgres database via Drizzle
• Agents: Claude Code and opencode, driven through sidecars; tools exposed over MCP

Data

Two stores, and the split matters:

Postgres (src/databases/officer_db) holds the account, passkeys, settings, dashboards, email accounts, queue and pipeline jobs. Schema in src/schema/, hand-written queries in src/queries/, types inferred from the schema in src/types.ts.

The filesystem holds everything the agent authors. OFFICER_ITEMS_DIR contains one directory per item under skills/, tools/, tasks/, processes/, extensions/ — no database rows, no scope tiers. DATA_PATH/<email>/ holds the managed home, attachments and the per-account email SQLite stores — those are the email sidecar's, and nothing in the platform opens them. Path helpers live in src/servers/data-path.ts; note getHomeDir (the managed home under DATA_PATH) versus getOwnerHomeDir (the owner's real login home when HOME_DIR is set, which is where terminals, chats and task runs actually execute).

Schema changes use push, not migrations

This database is kept in sync with bun db:push, which diffs the schema code against the live database and alters it directly. drizzle-kit migrate has never been run here — there is no __drizzle_migrations table. Change the schema, run bun db:push, done.

bun db:gen writes files to officer_db/migrations/, but nothing applies them; the old numbered history was deleted because it had drifted from the real schema. Treat the schema code, not those files, as the source of truth.

Declare multi-column uniqueness as uniqueIndex('uq_…').on(a, b), never unique('uq_…').on(a, b) — drizzle-kit mis-diffs named composite unique constraints and re-creates them on every push, which used to stop db:push on an unanswerable truncate prompt. Same for any foreign key whose generated name would exceed Postgres's 63-character identifier limit: name it explicitly. See src/databases/CLAUDE.md → "Composite keys" before adding either.

Security Model

The perimeter is one credential, so the guards matter:

• IS_DEV_BUILD (src/servers/build-env.ts) is true only when PUBLIC_BUILD_ENV is explicitly dev/development. Everything else, including unset, is hardened. Origin validation, rate limiting and password rules all key off it — they fail closed.
• Allowed origins come from PUBLIC_URL. Officer always sits behind an HTTPS reverse proxy, so the forwarded Host must equal PUBLIC_URL's authority exactly.
• JWTs are 30-day, blacklisted on signout, and invalidated by a password change (passwordChangedAt).
• A panic lockdown (src/servers/api/auth/panic.ts) is in-memory only and refuses every authenticated request until the server restarts.

Commands

bun dev          # the whole app — SPA + API + WebSockets, watched
bun start        # production
bunx tsgo        # typecheck (not tsc)
bun test         # tests
bun format       # prettier over every dirty file — see the note below before running it
bun db:push      # apply the schema to Postgres
bun setup        # guided install (writes .env, incl. PUBLIC_BUILD_ENV=production)

Sidecar control is PM2, not npm scripts: pm2 restart officer-<name>, pm2 logs officer-<name>. See docs/working-on-officer.md for which process a given change needs restarted.

Installs are frozen. Never resolve a dependency you did not ask for.

bunfig.toml sets [install] frozenLockfile = true, so bun install resolves from bun.lock and nothing else — it fails rather than quietly picking up a newer version, including a transitive one nobody chose. Verified on bun 1.3.10: a lockfile that no longer satisfies package.json exits 1 with error: lockfile had changes, but lockfile is frozen.

It is config rather than a habit because a supply-chain compromise does not wait for the one time somebody forgets a flag. On 2026-08-04 eleven cache packages — keyv, flat-cache, file-entry-cache, cacheable-request, cache-manager, the @cacheable/* scope, ecto — were published with a preinstall dropper that harvested npm and GitHub tokens, AWS and Kubernetes credentials, SSH and PEM keys, .env files and .claude/settings.json, then republished itself through any npm token it found. It reached 434 further packages across 1,381 versions. This machine was unaffected only because nothing had installed since 2026-08-02.

To change a dependency: edit package.json, run bun install --no-frozen-lockfile deliberately, read the lockfile diff, and commit it. The friction is the point — an unexplained lockfile change in a diff is the signal this exists to produce.

Do not add --no-frozen-lockfile to a script, a Dockerfile or CI to make an error go away. The error means the lockfile and package.json disagree, and that is worth a human look every time.

Format your own files, not the whole dirty tree. bun format globs git diff --name-only HEAD, so it rewrites every uncommitted file — including work in progress that isn't yours, which then shows up as unexplained whitespace churn in someone else's diff. Run bunx prettier --write <paths> on the files you actually touched. bun format is only safe when the tree is otherwise clean.

Code Style

• Paradigm: functional — pure functions, immutability, composition
• TypeScript: strict, no any. Type-only imports are required (verbatimModuleSyntax).
• Comments: minimal, and about why. Don't narrate what the code already says.
• Async: always async/await
• Exports: named only, no defaults
• Files: PascalCase.tsx for components, kebab-case.ts for everything else
• Prettier: single quotes in JS, double in JSX, semicolons, trailing commas, 120 cols

Imports

Order: types → external → workspace → relative.

import type { User } from 'types';
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { useClient } from 'hooks/useClient';
import { formatDate } from 'helpers/formatters';
import { useWebsites } from '../useWebsites';

In app code import types from 'types', which re-exports the database types. Only server and database code imports from officerdb/types directly.

Functions

Arrow functions for one-liners, regular functions for anything with real logic. No multiline parameter lists — extract a params type instead.

type ProcessDataParams = { body: Record<string, unknown> | undefined; query: Record<string, string> };
export function processData({ body, query }: ProcessDataParams): Result { ... }

Components and hooks

type ExperimentCardProps = { experiment: Experiment; onSelect: (id: number) => void };

export const ExperimentCard = ({ experiment, onSelect }: ExperimentCardProps) => { ... };

Complex hooks return objects; simple state hooks return as const tuples. Event parameters are always named ev, never e.

API calls

useClient() returns typed verbs — client.get<Foo>('/foo') really does return Foo, so pass the type parameter and let inference flow from it.

Working With Me

• Ask first — confirm the approach before a significant change
• Explore thoroughly — read the related files before editing
• Keep it simple — no over-engineering, no premature abstraction
• Be explicit — no magic, no implicit behaviour
• Stay focused — note unrelated problems, don't fix them uninvited
• Report honestly — say what you verified and what you didn't

Commit messages: simple lowercase, no prefixes.

Frontend route conventions (apply to EVERY new dashboard route)

Worked examples: /soulseek, /music, /chat.

• Workspace/Panel framework, always — never a standalone single screen. The screen renders <WorkspaceView workspace={ws} locked /> where ws = useDashboardState<LayoutNode>('screens/<name>', defaultLayout), guarded by a normalizeLayout that pins appTypes to an allow-list. Panels are windowed apps under src/workspaces/officerdev/src/apps/<Feature>/, each exporting appRegistryMetas ({ key, name, icon, component, availableOnPanel: false }) and registered in AppRegistry.tsx. The Workspace/Panel framework is orthogonal to routing — it contains no route navigation, and panels live inside the Route element tree, so they can call useParams/useSearchParams directly.
• Page title by route. Add a rule to RULES in src/apps/officer-web/state/usePageTitle.ts ({ match: (p) => p.startsWith('/<name>'), title: '<Name>' }, most-specific first); usePageTitleSync does the rest. startsWith means nested routes are covered.

The URL is the source of truth for selection

docs/navigation-audit.md is the authority here — read it before building a screen that selects things. It names the "opaque click" anti-pattern: an element that opens something addressable but keeps the id in an onClick closure instead of the DOM, leaves the URL unchanged, holds the selection in usePanelChannel/useGlobal, and has no anchor semantics (no cmd-click, no middle-click, not link-focusable). Half the app still does this; none of the new code should.

• Addressable state goes in the URL (useParams / useSearchParams), never in a channel. usePanelChannel is for genuine signals and refresh buses (files:refresh-signal, SLSKD_REFRESH_CHANNEL, MUSIC_RESYNC_CHANNEL) — and declare one with defineChannel in officerdev/src/channels.ts rather than spelling the name and type at each site. "Which thing is open" is a URL. Panels each read the URL rather than passing it between themselves.
• Rows and nav items are real links. <Link> for rows (exemplar: the /chat session list, f35c145); react-router's <NavLink> for nav chrome, so active state comes from the router. The hand-rolled isActive in Dock/Header is scheduled for replacement (audit Phase 4) — don't copy it. A disabled entry renders as a <span>; a disabled <a> is not a thing. A control that mutates rather than navigates stays a <button>.
• Route pairs. A bare screen route plus a param route rendering the same component: /chat + /chat/:sessionId, /jobs + /jobs/:id, /email + /email/:emailId, /headscale + /headscale/:section. One <Navigate … replace /> guard in the screen, placed after all hooks, canonicalises both the bare route and a bogus param.
• Master list + live preview uses ?selected=<id>, not the detail route — linking rows straight to /x/:id destroys preview-on-list, because that route is the full page. Rows link to /x?selected=id on-page and /x/:id off-page; list, mobile panel and preview all read the param. Action buttons are siblings of the anchor, never nested inside it.
• src/workspaces/components/NavLink.tsx is not react-router's NavLink — it's a <Link> wrapper that appends useGlobalQueryString() and provides no active state. Import react-router's when you want isActive.
• Route helpers shared between an officerdev panel app and an officer-web screen must be re-exported from src/workspaces/officerdev/src/index.ts (named exports only — the barrel deliberately avoids export * for app modules to keep appRegistryMetas from colliding).

Further Reading

• docs/navigation-audit.md — authoritative on routing/navigation: the opaque-click anti-pattern, a severity-ranked findings table, the channel-selection map and the four-phase plan
• docs/agent-coordination.md — the north star for the workspace/panel work: agents on one dashboard coordinating with each other instead of through the human, the handoff protocol, and what is deliberately not being built. Read it before ranking, deferring or starting any panel item — it is what docs/workspace-panel-todo.md is ranked against.
• docs/workspace-panels.md — how the Workspace/Panel framework works: the layout tree, how a panel is mounted and what it knows, the URL-vs-channel split for panel-to-panel communication, and the persistence key families. Read before building a panel app. Its defect list is docs/workspace-panel-todo.md.
• docs/sidecar-topology.md — where the sidecar architecture is going, and what was considered and dropped
• docs/working-on-officer.md — how to run, restart and check your work on this machine
• docs/wallet-key-custody.md — what the platform can and cannot see of the wallet
• TODO.md — current direction and deferred work; takes precedence over this file where they disagree
• src/apps/CLAUDE.md — shared frontend patterns
• src/databases/CLAUDE.md — database patterns
• CONVENTIONS.md — component organisation, state management and React patterns, with rationale; src/workspaces/officerdev/APP_CONVENTIONS.md and HOOK_CONVENTIONS.md for panel apps and hooks

Treat the code as the source of truth where anything here disagrees with it.