The operating system for agents. You ship Modules; the agent reads skills and calls tools. Everything else is plumbing.

BoringOS is an open-source framework for building agentic platforms — agents receive tasks, execute autonomously via CLI subprocesses (Claude Code, Codex, Gemini CLI, Ollama, …), and report back. The framework never calls LLM APIs directly; CLIs are the agents, BoringOS is the orchestrator.

The thesis in one read: docs/thesis.md — what Hebbs is, what ships on day zero (the Shell), what you install on top (Modules), how the framework works, and how we sell. Read this first, and use it as the source of truth when writing any new doc or marketing copy.

A guided walk through what BoringOS actually looks like running. First the Shell (the operating system surface), then a CRM module example showing how an installable module extends it. Tap Next → to swipe through.

Jump to a section: Shell · Install a module · CRM module example

Run the company from one screen: open work, agents online, weekly spend, and the watch items that need a decision today.

Next → · ↑ Tour

Every task names its owner, blockers, decisions needed, and risks. Comments are the audit trail. This is how a CEO reads work.

← Prev · Next → · ↑ Tour

"Build me a Tesla account brief." Copilot returns a progress chart, the decision committee, and a ready-to-send email — not a chat transcript.

← Prev · Next → · ↑ Tour

A real operating cabinet: Chief of Staff at the top; GTM, RevOps, and Engineering pods underneath. Twelve named operators, one chart, clear accountability.

← Prev · Next → · ↑ Tour

Complex workflows (e.g. enterprise deal qualification) run end-to-end with a span tree on the right. Execution is repeatable and inspectable.

← Prev · Next → · ↑ Tour

Tenant cap, per-team caps, spend by agent and by model. No surprises at the end of the month.

← Prev · Next → · ↑ Tour

The platform ships with the core operating system. New surface areas (sales, support, finance) arrive as signed .hebbsmod packages.

← Prev · Next → · ↑ Tour

One click installs the CRM module. Pipeline, Deals, Contacts, and Companies appear instantly in the left nav — the org now has a sales surface.

← Prev · Next → · ↑ Tour

Board-level visibility: every named account, every value, every owner, every stage. The view a CEO opens before the board call.

← Prev · Next → · ↑ Tour

Persona, journey, recognition, alerts (TPU v5, LangChain redlines), sourced citations. The brief an AE actually reads before the meeting.

← Prev · Next → · ↑ Tour

Leadership, strategy shifts, capex cycle, competitive moves — the account brief an exec walks into the boardroom with.

← Prev · Next → · ↑ Tour

"I just met Sam Altman at the GPT-5.5 event — scan everything we have on OpenAI and draft a follow-up." One turn reaches across deals, contacts, dossiers, and the inbox; the reply is links and decisions, not a chat transcript.

← Prev · ↑ Tour

The agent's prompt is built from two registries, sourced from plain data — no hand-written providers per integration.

• Skills — markdown files (SKILL.md) shipped by every component. Loaded into the agent's prompt under ## Skills. Teach the agent how to think about a domain.
• Tools — Zod-typed callable operations. Registered by Modules, dispatched at one URL: POST /api/tools/<module>.<tool>. The agent reads an inventory, calls them, gets validated responses with structured errors.

A Module bundles skills + tools + (optionally) schema, UI, default workflows, default agents, routines, OAuth, and webhooks. Three roles, same shape:

• Connector — brokers a 3rd-party API (connector-google, connector-slack)
• Capability — pure logic depending on other Modules (triage, prevent-churn)
• Hybrid — owns its own data + tools (crm, inbox)

All registered the same way: app.module(myModule). Adding Notion is one Module package, zero framework edits.

Open Cursor (or any agentic CLI — Claude Code, Codex, Gemini) inside a clone of this repo and say:

"deploy boringos shell on my localhost"

The agent will install dependencies, build the workspace, boot embedded Postgres, and start the shell on http://localhost:3000.

git clone https://github.com/BoringOS-dev/boringos.git
cd boringos
pnpm install
pnpm -r build
pnpm dev

Then open http://localhost:3000.

npx create-boringos my-app
cd my-app && pnpm install && pnpm dev

Or wire one inline:

import { BoringOS } from "@boringos/core";
import { z } from "@boringos/module-sdk";
import type { Module } from "@boringos/module-sdk";

const helloModule: Module = {
  id: "hello",
  name: "Hello",
  version: "0.1.0",
  description: "Demo module",
  skills: [{ id: "hello", source: "module",
    body: "Use `hello.greet` to say hi to someone." }],
  tools: [{
    name: "greet",
    description: "Greet someone by name",
    inputs: z.object({ name: z.string() }),
    async handler({ name }) {
      return { ok: true, result: { message: `Hello, ${name}!` } };
    },
  }],
};

const app = new BoringOS({});
app.module(helloModule);
await app.listen(3000);

Embedded Postgres boots automatically, the tool dispatcher mounts at /api/tools/*, and the agent's prompt now includes the hello skill plus the hello.greet tool.

For the step-by-step guide, see BUILD-A-MODULE.md.

The @boringos/connector-google Module needs an OAuth client. Two minutes in Google Cloud Console, then two env vars.

console.cloud.google.com

1. Create a project (or pick an existing one).
2. Enable APIs — APIs & Services → Library:
   • Gmail API
   • Google Calendar API
3. OAuth consent screen — APIs & Services → OAuth consent screen:
   • User type: External (or Internal if you're on Workspace)
   • Add your email as a test user while in Testing status
   • Add these scopes:
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/calendar
     • https://www.googleapis.com/auth/calendar.events
4. Create OAuth 2.0 Client — APIs & Services → Credentials → Create credentials → OAuth client ID:
   • Application type: Web application
   • Authorized JavaScript origins: http://localhost:3000
   • Authorized redirect URIs: http://localhost:3000/api/connectors/oauth/google/callback
5. Copy the Client ID and Client secret.

Drop these in .env.local at the repo root:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Restart pnpm dev, head to the shell's Connectors screen, click Connect Google, and finish the OAuth flow. Gmail and Calendar tools are now available to every agent in that tenant.

For production hosts, swap http://localhost:3000 for your public origin everywhere above and publish your OAuth consent screen.

• @boringos/connector-google — Gmail (send, search, read, archive) + Calendar
• @boringos/connector-slack — messages, threads, reactions

Six pluggable CLI runtimes ship out of the box: Claude Code, ChatGPT CLI, Gemini, Ollama, generic command, webhook.

• Embedded Postgres by default; external via DATABASE_URL
• Drizzle ORM
• Hono HTTP server
• In-process job queue by default; BullMQ via app.queue(...)

wake (comment / routine / event / admin)
  → coalesce + enqueue
  → fetch agent + create run row
  → build prompt: Skills (from registry) + Tools (from registry)
                  + per-run context (task, comments, session, memory)
  → spawn CLI subprocess with $BORINGOS_CALLBACK_TOKEN
  → agent calls POST /api/tools/<name> with bearer JWT
  → dispatcher: Zod-validate → handler → tool_calls audit row
  → agent posts result comment + sets status=done
  → engine auto-rewakes if more todos remain (success only)

Every side effect goes through one URL, validated by one schema, audited in one table.

• BUILD-A-MODULE.md — step-by-step guide to shipping your first Module (including dashboard widgets + Light/Dark theme support)
• MODULES.md — Module manifest spec, including the --bos-* theme contract every UI-shipping Module should follow
• TOOLS.md — Tool spec, error model, audit, idempotency
• SKILLS.md — Skill spec, file format, priorities
• CLAUDE.md — orientation for contributors
• docs/install-flow.md — how Modules are packaged, uploaded, installed per-tenant, and uninstalled
• docs/INDEX.md — full doc navigation

• examples/quickstart/ — boot, create an agent, assign a task, watch it execute

pnpm install
pnpm -r build
pnpm -r typecheck
pnpm test:run

BoringOS is licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). The full text lives in LICENSE at the repo root and applies to every package in this monorepo, including the shell.

See LICENSE.md for the short index and docs/licensing.md for the longer rationale.

Contributions welcome — see CONTRIBUTING.md.