AIX

AIX is an AI-native framework where applications understand their own architecture, purpose, and security requirements.

Agents, tools, workflows, memory, realtime events, generative interfaces, security and data are first-class primitives.

AIX gives you a Next.js-style developer experience: filesystem routing, React pages, API routes, a dev server and a production build. On top of that, the things AI applications need are part of the framework itself rather than code you glue together:

• Agents with an explicit lifecycle (queued → thinking → calling_tool → waiting_for_approval → completed), streaming, tool calls, retries, timeouts, cancellation, budgets and memory.
• Provider-neutral models (Anthropic, OpenAI, Gemini, DeepSeek, Ollama and any OpenAI-compatible server) plus a deterministic router for model: "auto".
• Generative UI where models produce validated component trees, never code, and interactive actions are signed and permission-checked on the server.
• Security by default. Tools are denied capabilities unless granted, there are human approval gates, and secrets never reach the browser (enforced at build time).
• Realtime. Every run streams typed events over SSE, which drive the React hooks and components.
• AI-native state. Stores, atoms, resources and events, plus shared agentState(), workflowState() and taskState(), all visible in a live inspector at /__aix/state.
• CSS, Tailwind CSS or both. Pick your styling at create (or aix add tailwind later); Tailwind utilities like bg-surface and text-fg map to the same design tokens as plain CSS. See docs/styling.md.
• Design DNA. Pick a style, mood, theme, density and motion during aix create. Every component, generative UI response, generated file and agent follows it, with WCAG contrast enforced automatically.
• Voice. voice: true on an agent and <VoiceChat agent="…" /> give a real-time voice assistant: OpenAI Realtime, Gemini Live, or speech-to-text → any model → text-to-speech, with interruptions, live captions and server-side tools. See docs/voice.md.
• TypeScript, JavaScript and Python. Write tools, agents, workflow steps and tasks in Python next to a TypeScript app: import { analyst } from "./agents/analyst.py" is typed, a TS agent can use a Python tool, and Python reaches data, secrets and models only through the host's security layer. See docs/python.md.
• Installable apps (PWA). aix pwa enable (or pwa: true) adds the manifest, icons, a safe service worker, an offline page and usePWA(). See docs/pwa.md.
• Smart Database. Define a model once and AIX derives storage, validation, ownership and access rules, encryption, APIs, agent tools, events, forms, docs and migrations, plus an AI-readable .aix/data-model.json. Includes natural-language queries and analytics that run with the user's own rights. See docs/data.md.
• Route rules, SEO, AEO and GEO. One routes.ts says who may open each page (roles, sign-in, MFA), which agents and data it uses, and how it should appear to search engines, answer engines and AI. AIX generates head tags, JSON-LD, robots.txt, sitemap.xml and llms.txt, and never indexes protected pages. See docs/routes-and-seo.md.
• Security DNA. .aix/security.json sets the protections for your type of app (finance, healthcare, education …). The build fails when code breaks them: undeclared permissions, hardcoded secrets, unencrypted sensitive fields.
• Built for coding agents. aix mcp exposes the app's architecture, state and design language, plus generators that respect all three.

Status: early (v0.1). The vertical slice from create-aixjs to generative UI, plus workflows, background tasks, state management, the design system and the coding-agent MCP server, are implemented and tested. See Roadmap & status. Nothing below is described as working unless it is covered by tests.

Quick start

npx create-aixjs my-app
cd my-app
cp .env.example .env      # add ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY, or OLLAMA_HOST
npm run dev               # http://localhost:3000 · dashboard at /__aix

A simple example

// agents/assistant.ts — server-only
import { agent, calculator } from "@aixjs/aix";

export const assistant = agent({
  name: "assistant",
  model: "auto",
  instructions: "You are a helpful assistant. Use tools for math.",
  tools: [calculator],
  memory: true,      // conversation memory per thread
  access: "public",  // agents are private by default
});

// app/page.tsx — runs on the server (SSR) and in the browser
import { AgentChat } from "@aixjs/aix/react";

export default function Page() {
  return <AgentChat agent="assistant" />;
}

That gives you streaming responses, tool-call activity, agent status, errors with hints, memory across reloads, and realtime updates, without writing any infrastructure.

Generative UI

// agents/analyst.ts
import { agent, sqlTool } from "@aixjs/aix";

export const analyst = agent({
  name: "analyst",
  instructions: "Query sales, then render a Dashboard with Metric, Chart and Table.",
  tools: [sqlTool(db)],
  permissions: { database: "read" },
  ui: true,           // adds render_ui / update_ui and the component catalog
  access: "public",
});

import { GenerativeUI } from "@aixjs/aix/react";

export default function Page() {
  return <GenerativeUI agent="analyst" />;
}

The model emits JSON like { "type": "dashboard", "children": [{ "type": "metric", "label": "Revenue", "value": "$12,450" }] }. The server validates each element against registered component schemas, rejects unknown components, unsafe URLs and actions that aren't allow-listed, signs every action, and streams elements to the browser as they complete. Your own components plug in with defineComponent() on the server and registerComponent() in the browser. See docs/generative-ui.md.

An agent with approvals

import { agent, tool } from "@aixjs/aix";
import * as z from "zod";

const deploy = tool({
  name: "deploy",
  description: "Deploy the application",
  input: z.object({ environment: z.enum(["staging", "production"]) }),
  permissions: [{ capability: "deployment" }],
  execute: async ({ environment }) => ({ url: `https://${environment}.example.com` }),
});

export const ops = agent({
  name: "ops",
  tools: [deploy],
  permissions: { deployment: "approval" }, // every deploy pauses for a human
  access: "public",
});

The run moves to waiting_for_approval, <AgentChat> shows an approval card, and the run resumes when the user approves. A rejection is returned to the model as an error, and the tool never runs. Tool code can also call await approval.request({ action, description }) directly.

Architecture

CLI (aix dev/build/start/doctor…)
 ↓
Server ── filesystem router, SSR (React 19), API routes, SSE, sessions, CSRF/CSP
 ↓
Runtime ── wires everything per app; no HTTP dependency
 ↓
Agent ──→ Models (providers + router)   Generative UI ──→ Core, Events
      ──→ Tools  (validation, permissions, approvals)
      ──→ Events (typed bus, replayable channels)
      ──→ Memory (KV / vector interfaces)
      ──→ Security (policies, approvals, budgets, audit, secrets)
 ↓
Core ── errors, content model, schemas, async utilities, SSE codec

Each subsystem is its own package (@aixjs/*) behind an interface, so a provider, store, transport or queue can be replaced without touching the rest. The @aixjs/aix package is the public entry point: @aixjs/aix (server), @aixjs/aix/react (browser) and @aixjs/aix/config. See docs/architecture.md.

Status

| Area | Status | |---|---| | CLI: create, dev, build, start, doctor, models, logs, trace, generate, agent/tool new\|list, deploy --target docker | ✅ implemented | | Filesystem routing (dynamic, catch-all, groups, layouts, loading, error, not-found), SSR + hydration, API routes | ✅ | | Agents: lifecycle, streaming, tools, retries, timeouts, cancellation, pause/resume, queueing, structured output, budgets, memory | ✅ | | Models: Anthropic (official SDK), OpenAI & compatible (DeepSeek, Ollama, vLLM, llama.cpp, LM Studio, MLX), Gemini, deterministic router | ✅ (adapters tested against recorded wire formats; not yet against live APIs in CI) | | Tools: validation, permissions, approvals, audit; built-ins (calculator, filesystem, http, git, GitHub, web search via Brave, SQL, email transport) | ✅ | | Generative UI: schema validation, 26 components, streaming, signed actions, approvals | ✅ | | React: useAgent, useAI, useGenerativeUI, useApproval, useRealtime; AgentChat, AgentStatus, AgentActivity, ToolApproval, GenerativeUI, StreamingResponse | ✅ | | Security: deny-by-default capabilities, client/server boundary enforced at build, secret redaction, CSRF, CSP, sessions, rate limits | ✅ | | Memory: conversation, user/project/agent facts, semantic recall (KV + vector interfaces, file/in-memory stores) | ✅ | | Workflows (sequential, parallel, conditions, retries, timeouts, approvals, persistence and resume, pause/cancel/retry) and background tasks (queue adapter, retries, progress, logs, recovery) | ✅ | | State: stores, atoms, signals, events, resources, UI state, agent/workflow/task state, persistence adapters (memory, localStorage, SQLite, Postgres, Redis), state inspector at /__aix/state | ✅ | | Design system: 14 styles, 10 moods, 5 themes, density, motion; tokens, CSS, contrast enforcement, design agent, aix design | ✅ | | aix mcp: an MCP server for coding agents (describe/inspect/modify state, inspect/change design, generate component/feature, analyze UI) | ✅ | | Security DNA (.aix/security.json), permission engine (roles, MFA, four-eyes approvals), identity adapters, build-time coverage | ✅ | | Transactions: double-entry ledger, fraud rules with thresholds you configure, idempotency, reversals | ✅ | | Secrets: secrets.get() (env, files, Vault), redaction on by default, hardcoded-secret scanner that fails the build | ✅ | | Smart Database: semantic models, relations, secure query layer, state machines, encryption, derived APIs and agent tools, events (outbox), migrations, natural-language queries, analytics, model proposals | ✅ (SQLite and Postgres; document stores not yet) | | Voice sessions: OpenAI Realtime, Gemini Live, or STT → any agent → TTS; microphone streaming, interruptions, live captions, voice events, useVoice / <VoiceChat> | ✅ (adapters tested against the wire protocols, not live APIs in CI) | | Route rules (routes.ts): roles, sign-in, MFA, actions, route-granted agents; SEO/AEO/GEO metadata, JSON-LD, robots.txt, sitemap.xml, llms.txt; aix routes, aix seo audit | ✅ | | Security Agent report, change proposals, pre-deploy security simulation, tamper-evident audit | 🚧 next | | Agents using external MCP servers (MCP client) | 🚧 next | | Full developer dashboard at /__aix (index plus state inspector today) | 🚧 next | | Sandboxed code execution / terminal, browser automation, observability exporters | 🔜 Phase 3 (interfaces partly in place) | | Deployment adapters other than Docker | 🔜 Phase 4 |

Repository

packages/   core events security identity permissions site data data-ai transactions models tools memory agent workflows tasks state design-system generative-ui router config runtime server ui cli aix(→ npm: aixjs) create-aix(→ npm: create-aixjs)
examples/   hello-world chatbot agent generative-ui education-platform
docs/       guides for every subsystem
tests/      end-to-end tests (spawn the real CLI) + fixtures

pnpm install
pnpm build        # tsc -b (strict)
pnpm test         # unit + end-to-end

License

MIT