How infinite-labs-ai/infinite-os works
1. Overall shape: local-first monorepo with a control plane and a data plane
- Infinite OS is split into a user-facing CLI, a local app daemon, a background worker, and a Postgres database.
- The CLI is the operator shell and chat UI; the daemon provides the local API boundary; the worker owns scheduled/background sync work; Postgres stores synced analytics data plus system state.
2. Primary request flow
- A user runs infinite or infinite setup in the terminal.
- The CLI talks to the app daemon over localhost.
- For analytics questions, the CLI delegates to the LLM controller and the analytical engine to turn a natural-language prompt into governed metric queries, then renders the result in the TUI.
- For setup and syncing, the CLI orchestrates connection/configuration flows and then triggers local services.
3. Data ingestion and sync boundary
- The worker is the subsystem that connects to external providers and syncs data into Postgres.
- Supported providers in the repo include GA4, PostHog, Stripe, Meta, Shopify, and X.
- The database is treated as a rebuildable cache: provider source systems remain authoritative, while local tables store sync state, raw records, jobs, schedules, and queryable views.
4. Analytics/metric layer
- packages/analytical-engine and packages/metadata define the typed metric/provenance layer that answers questions like “page views last 7 days.”
- This layer is what keeps the system from behaving like a free-form SQL tool: it resolves queries to known metrics and source-aware views rather than guessing.
- The result is source-accurate analytics with explicit authority rules.
5. LLM integration boundary
- packages/llm-controller manages model auth, prompt assembly, session memory, and query advice.
- The README makes the trust model explicit: prompts are sent to the user’s own Claude or Codex credentials; the runtime does not execute arbitrary shell commands or expose local data except through the intended query flow.
- This package is the bridge between conversational input and the governed analytics layer.
6. Setup/onboarding subsystem
- packages/setup handles the guided onboarding flow: provider selection, prompts, recommendations, browser handoff, SSRF-safe flows, and reconciliation of setup state.
- It also manages install commands and workspace artifacts, which suggests setup is a first-class workflow rather than a one-off script.
- This is the boundary where public provider metadata, user confirmation, and local configuration converge.
7. Configuration, identity, and encryption
- packages/config centralizes workspace ID, daemon endpoint, active project, and the local home directory layout.
- packages/core handles encryption/fingerprinting concerns; the README notes connector credentials are encrypted at rest with GROWTH_OS_ENCRYPTION_KEY.
- Configuration is stored locally in a gitignored .growth-os/ area, reinforcing the local-only trust boundary.
8. Database and migration layer
- packages/db owns schema migrations and database access.
- The migration history shows the schema evolved to cover control-plane state, sync state, jobs/schedules, saved reports, provider-specific truth tables, metadata registries, security roles, OAuth token links, and workspace ownership.
- There is a pglite adapter, indicating the repo also supports lightweight/test-local database execution in addition to Postgres.
9. CLI and terminal UI
- apps/cli is the main user entrypoint. It contains command handling plus a rich TUI built on a vendored Ink implementation in ui-tui/packages/ink.
- The CLI includes formatting, progress reporting, interactive sessions, connect/setup wizards, and transcript rendering.
- This layer is purely presentation/orchestration; it does not own analytics or sync logic.
10. Daemon lifecycle and coordination
- apps/app appears to be the local daemon process: it has daemon descriptor/spawn-lock logic and tests around loopback binding and listening.
- That suggests it protects singleton startup and exposes a local HTTP surface for the CLI to discover and talk to.
- The daemon is the coordination point between CLI requests, worker status, and local config.
11. Background worker and scheduled jobs
- apps/worker is a separate service with its own entrypoint and tests, implying an independently runnable process.
- Its responsibility is likely scheduled sync execution and job processing, which matches the database schema for jobs and schedules.
- In the architecture diagram, it should sit behind the daemon/CLI and in front of provider APIs and Postgres writes.
12. Website instrumentation as a separate distributed package
- packages/instrument is published as infinite-tag, a distinct package used inside a customer’s own website repository.
- It auto-detects frameworks such as Next.js, Vite + React, and static HTML, and applies reversible, idempotent changes to add tracking.
- This is an external integration boundary: it does not run inside Infinite OS itself, but feeds GA4/PostHog collection upstream.
13. Runtime and support packages
- packages/runtime provides shared runtime helpers such as session memory, notifications, recipes, and module loading.
- packages/connectors and packages/metadata appear to hold provider-specific fixtures and shared metadata definitions used across setup, sync, and analytics.
- These packages keep provider logic and runtime concerns out of the CLI/daemon/worker apps.
14. Operational packaging
- The repo is managed as a pnpm workspace, with Docker-based local stack support via docker-compose.yml and CI/publish workflows in .github/workflows.
- Scripts and docs show a deliberate local install/update path, including automatic self-update on launch and a one-command bootstrap installer.
- For an architecture diagram, the operational view should show: user terminal → CLI → daemon → worker → Postgres, plus side paths to provider APIs, browser-based auth, and model-provider auth.
Main entry points: src/index.ts Setup · src/index.ts CLI · src/index.ts Database · src/index.ts Daemon
Components 14
Apps
User-facing executables and local services
Packages
Shared domain and infrastructure packages
- Database · Migrations and access layer for state, sync data, and queryable views
packages/db/src/index.ts - LLM Control · Auth, prompt assembly, memory, and query advice for model calls
packages/llm-controller/src/index.ts - Analytical Engine · Governed metric and source-aware analytics resolution
packages/analytical-engine/src/index.ts - Metadata · Typed definitions and provenance for metrics and source mappings
packages/metadata/src/index.ts - Setup · Guided provider onboarding, browser handoff, and reconciliation
packages/setup/src/index.ts - Config · Workspace identity, daemon endpoint, and local home layout
packages/config/src/index.ts - Core · Credential encryption and fingerprinting utilities
packages/core/src/index.ts - Runtime · Session memory, notifications, recipes, and module loading
packages/runtime/src/index.ts - Instrument · External website instrumentation and provider injection package
packages/instrument/src/index.ts - Connectors · Provider-specific fixtures and connector-shape helpers
packages/connectors/src/index.ts
TUI
Vendored terminal UI runtime
- Ink · Vendored terminal UI framework used by the CLI
ui-tui/packages/ink/index.js
Connections 19
- CLI → Daemon: local API · CLI sends commands and session requests to the daemon
- CLI → LLM Control: chat + advice · CLI delegates conversational analysis and query guidance
- CLI → Setup: onboarding · CLI drives provider selection and setup workflows
- CLI → Ink: render TUI · CLI uses Ink-based terminal rendering and interaction
- Daemon → Worker: coordination · Daemon surfaces sync and job state from the worker
- Daemon → Config: read settings · Daemon resolves workspace and endpoint configuration
- Worker → Database: writes sync data · Worker persists jobs, raw records, and views
- Setup → Config: provision workspace · Setup creates and reconciles local workspace state
- Setup → Core: encrypt creds · Setup stores connector credentials using local encryption
- Setup → Connectors: provider guidance · Setup uses provider-specific metadata and fixtures
- LLM Control → Analytical Engine: governed query · LLM controller turns prompts into metric-aware requests
- LLM Control → Runtime: memory + tools · LLM controller uses shared session memory and runtime helpers
- Analytical Engine → Metadata: resolve metrics · Analytical engine depends on typed metric and provenance definitions
- Analytical Engine → Database: query views · Analytics read from queryable views and persisted state
- Metadata → Database: seed schema · Metadata definitions are reflected in the database schema
- Instrument → Connectors: provider targets · Instrumentation package targets GA4, PostHog, and X collection flows
- Instrument → Setup: bootstrap site · Setup can guide installation of external tracking instrumentation
- Core → Database: encrypted storage · Database stores encrypted connector and workspace secrets
- Runtime → Ink: session UI · Runtime helpers support interactive terminal sessions