FideliOS is a monorepo with four main layers.

​
Technology Stack

LayerTechnology
FrontendReact 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query
BackendNode.js 20+, Express.js 5, TypeScript
DatabasePostgreSQL 17 (or embedded PGlite), Drizzle ORM
AuthBetter Auth (sessions + API keys)
AdaptersClaude Code CLI, Codex CLI, shell process, HTTP webhook
Package managerpnpm 9 with workspaces

​
Repository Structure

fidelios/
├── ui/                          # React frontend
│   ├── src/pages/              # Route pages
│   ├── src/components/         # React components
│   ├── src/api/                # API client
│   └── src/context/            # React context providers
│
├── server/                      # Express.js API
│   ├── src/routes/             # REST endpoints
│   ├── src/services/           # Business logic
│   ├── src/adapters/           # Agent execution adapters
│   └── src/middleware/         # Auth, logging
│
├── packages/
│   ├── db/                      # Drizzle schema + migrations
│   ├── shared/                  # API types, constants, validators
│   ├── adapter-utils/           # Adapter interfaces and helpers
│   └── adapters/
│       ├── claude-local/        # Claude Code adapter
│       └── codex-local/         # OpenAI Codex adapter
│
├── skills/                      # Agent skills
│   └── fidelios/               # Core FideliOS skill (heartbeat protocol)
│
├── cli/                         # CLI client
│   └── src/                     # Setup and control-plane commands
│
└── doc/                         # Internal documentation

​
Request Flow

When a heartbeat fires:
  1. Trigger — Scheduler, manual invoke, or event (assignment, mention) triggers a heartbeat
  2. Adapter invocation — Server calls the configured adapter’s execute() function
  3. Agent process — Adapter spawns the agent (e.g. Claude Code CLI) with FideliOS env vars and a prompt
  4. Agent work — The agent calls FideliOS’s REST API to check assignments, checkout tasks, do work, and update status
  5. Result capture — Adapter captures stdout, parses usage/cost data, extracts session state
  6. Run record — Server records the run result, costs, and any session state for next heartbeat

​
Adapter Model

Adapters are the bridge between FideliOS and agent runtimes. Each adapter is a package with three modules:
  • Server module — execute() function that spawns/calls the agent, plus environment diagnostics
  • UI module — stdout parser for the run viewer, config form fields for agent creation
  • CLI module — terminal formatter for fidelios run --watch
Built-in adapters: claude_local, codex_local, process, http. You can create custom adapters for any runtime.

​
Key Design Decisions

  • Control plane, not execution plane — FideliOS orchestrates agents; it doesn’t run them
  • Company-scoped — all entities belong to exactly one company; strict data boundaries
  • Single-assignee tasks — atomic checkout prevents concurrent work on the same task
  • Adapter-agnostic — any runtime that can call an HTTP API works as an agent
  • Embedded by default — zero-config local mode with embedded PostgreSQL