intelligo

Intelligo

The application framework for vertical AI SaaS.

You build the agent, with the AI framework you already use.
Intelligo is everything around it — and it is tested, typed, and yours.

Website · Docs · Blocks · Components · Architecture · Why

_{The first twelve seconds. Watch the whole minute — pages as source, the execution boundary, usage, and the config that makes it yours.}

Status: 1.0. On npm under latest; the public APIs follow semantic versioning. Everything on this page exists and runs today.

An AI product is two halves.

One is your agent: the prompts, the tools, the domain knowledge nobody else has. That half is why the product exists.

The other is the same in every AI SaaS ever built: who is signed in, which workspace they belong to, whether their plan allows this request, what it cost, who to bill, and what to tell an auditor later. Teams spend most of their time rebuilding it.

Intelligo ships the second half finished and stays out of the first. There is no IntelligoAgent, no wrapper around your model calls, no new agent API to learn — use the Vercel AI SDK, Mastra, or anything else, exactly as its own docs describe.

flowchart LR
    subgraph you ["Your application"]
        direction TB
        pages["Installed pages<br/>(your source)"]
        agent["Your agent<br/>any AI framework, unmodified"]
    end

    subgraph intelligo ["Intelligo packages"]
        direction TB
        auth["auth · workspaces · roles"]
        billing["plans · credits · Stripe"]
        exec["executions<br/>admit · settle · audit"]
        core["conversations · documents"]
    end

    registry["Page registry"] -. "shadcn add" .-> pages
    pages --> auth & billing & core
    agent === |"bracketed, never wrapped"| exec
    intelligo --> db[("PostgreSQL")]

It is not an AI framework or a wrapper over one, not a component library, not a hosted platform — you deploy it like any Next.js application — and it has no runtime plugin system: composition happens at build time, on purpose.

You need Node 22.14+, pnpm 9, and PostgreSQL with pgvector (Neon, Supabase, or docker run pgvector/pgvector:pg17).

# asks which pages you want, then installs them as your source — tick the chat
pnpm dlx @intelligo-dev/cli create my-app
cd my-app

Anything you skip installs later, from the registry the scaffold's components.json names @intelligo: pnpm exec shadcn add @intelligo/billing-settings. Blocks install in dependency order, which create works out for you.

Copy .env.example to .env.local, set DATABASE_URL and BETTER_AUTH_SECRET (openssl rand -base64 32), then:

pnpm db:migrate   # the framework's schema, then your own tables
pnpm dev

Sign up, land on the dashboard, and chat. The chat streams against a built-in stub model and emails print to the server console, so nothing else needs configuring first. Team, billing, usage, notifications and artifacts are more items from the same registry. The getting-started guide takes it from here, and Bring your agent shows where yours plugs in.

Every AI run is bracketed, never wrapped. Your route stays written in your framework's own idiom; Intelligo stands on either side of it:

const run = await executions.begin({ workspaceId, userId, capability, model });
if (!run.allowed) return refuse(run.reason);

const result = await yourAgent.generate(messages); // your framework, unmodified

await run.complete({ usage: result.usage }); // or, in catch: run.fail({ error })

• Admit — the plan is checked through a port, the worst-case cost is held against the workspace's credits, and an execution row is written. A refusal is recorded too.
• Run — your code. The handle knows nothing about messages, tools or models.
• Settle — actual tokens and cost are recorded and the credits charged, by compare-and-swap, so a duplicate complete cannot double-bill. On failure the hold is released; if the process dies, it expires.

Model ids are registry keys with per-token pricing. An id with no price is refused at admission and fails an architecture test — never a silent mis-bill. If you would rather not write the route at all, @intelligo-dev/chat is the same lifecycle as two lines:

// app/api/chat/route.ts
export const { POST, DELETE } = createChatHandler(chatServerConfig);

Services live in npm packages you upgrade. Each takes its dependencies as ports, returns typed errors, and is tested against a real database.

Every package has its own page under intelligo.dev/docs/packages.

Pages do not come in a package. They arrive as registry blocks — pages, the shells around them, and drop-in surfaces like banners, gates and the chat panel — and install into your application as source, through the standard shadcn registry protocol — pages, components, loading/empty/error states and thin server actions, rendered by your own shadcn primitives:

Browse them running at intelligo.dev/blocks, and the design system's components — AI message parts, motion patterns, restyled primitives — at intelligo.dev/components.

Three rules keep installed pages healthy for years rather than weeks:

1. Installed components are used as they are. What your product varies goes in the config files the items ship for you to edit — navigation, banners, onboarding steps, credit bundles, the agent's identity, conversation starters, tool renderers. Re-install an item later and your config survives.
2. Copy is translation, not code. Every item reads its strings from its own next-intl namespace. Adding a language is adding message files.
3. Business rules live behind the pages. An installed action parses, calls a typed service, maps the error, revalidates. The invariants are in the packages.

• One PostgreSQL database, with explicit ownership of every table. pgvector rides along; there is no Redis and no separate vector store.
• One service layer, two thin transports — Server Actions for mutations, route handlers for streaming and webhooks.
• One composition root per application. Registries are filled from it explicitly; registration by import side effect is banned.
• AI frameworks stay native. The only thing Intelligo records about a run is its boundary.
• Money is micros with a currency attached, and a deployment declares the one it bills in.
• Architecture is failing tests, not documents. Dependency direction, tenant scoping, registry hygiene and model-id registration break the build when violated.

The longer version, with the package graph, is at intelligo.dev/architecture.

packages/           the framework: core · auth · next · billing · chat · executions · audit · jobs · admin · mastra · cli
packages/registry/  the page registry's source — a private workspace, built with `pnpm registry:build`
apps/app            the reference application: exactly what `create` + `shadcn add` produce, regenerated by CI.
                    Read it to see a finished install; don't build in it
apps/website        intelligo.dev — the site and docs, which also serves the registry at /r
tools/film          the one-minute film above (Remotion)
tests/architecture  the rules, as tests

To look around before installing anything: clone, pnpm install && pnpm dev, and open the reference application on :4002 — a complete, generic workspace AI SaaS built from nothing but the public packages and the registry.

pnpm dev              # reference app :4002, website :4003
pnpm test             # unit, real-database integration and architecture suites
pnpm lint && pnpm type-check
pnpm registry:build   # rebuild the registry artifacts
pnpm db:migrate       # apply the framework's schema

A release is one squash-merged pull request: it bumps every published package and heads CHANGELOG.md with its section; merging it publishes to npm with provenance, tags, and creates the GitHub release. CONTRIBUTING.md is where to start a change; AGENTS.md is the full map of the codebase that coding agents load.

Questions and ideas go to Discussions, bugs to issues, and vulnerabilities go privately, the way SECURITY.md describes. See also SUPPORT.md and the code of conduct. How the project is run, and how to become a maintainer: GOVERNANCE.md.

Apache-2.0 · NOTICE · TRADEMARK.md