Axint

 

Axint is the Apple-native execution layer for AI coding agents.

Describe App Intents, SwiftUI views, widgets, and app shells in TypeScript, Python, JSON, or the preview .axint surface.
Axint emits ordinary Swift, validates Apple-specific rules, and gives agents a repair packet when something needs work.

Website · Playground · Create App · Quick Start · MCP Server · Docs · Registry

---

The loop

Axint exists because Apple-native software is becoming a set of structured system capabilities: App Intents, Siri, Shortcuts, Spotlight, widgets, SwiftUI views, privacy copy, entitlements, and generated metadata.

General coding agents can produce Swift. Axint makes them operate through a smaller contract, validates the Apple-specific parts, coordinates the project proof loop, and writes a repair artifact the next agent run can use.

feature definition
  → Axint IR
  → Swift + plist + entitlements
  → local or Cloud Check verdict
  → project-aware repair plan
  → Fix Packet
  → agent repair
  → rerun

The compiler is useful on its own. Registry and Cloud extend the same workflow:

• Compiler — open-source TypeScript/Python/preview .axint to Apple-native Swift.
• Fix Packet — latest.check.* for the quick verdict, latest.* for the full repair contract.
• Repair — axint repair indexes the existing Apple project, ranks likely files, classifies build/UI/runtime evidence, and returns the smallest patch/proof loop.
• MCP — agents call compile, validate, fix, schema compile, templates, and packet tools directly.
• Registry — install reusable Apple capabilities with source, compiler metadata, and package details attached.
• Cloud Check + feedback — free hosted validation for quick results; signed-in Pro checks add the AI-ready repair prompt, history, and a shareable report. Privacy-safe feedback packets help Axint learn repeated Apple failure modes without sending source code.

WWDC26 made App Intents, App Schemas, Siri, Shortcuts, Spotlight, and Foundation Models tool calls a single agent-facing execution path. Axint now validates that path with schema continuity, entity freshness, execution-target, model-proof, and security-boundary checks.

Read the thesis · Open proof · View Fix Packet

---

License and trademarks

Axint is open-source software licensed under Apache-2.0. The Axint name, wordmark, axis mark, logo, hosted service names, domains, and related Agentic Empire brand assets are not licensed for use by forks or unaffiliated products.

Forks are welcome under the Apache-2.0 license, but they should use distinct names and branding. See NOTICE and TRADEMARKS.md.

---

Why Axint

Apple's API surfaces — App Intents, SwiftUI, WidgetKit — are verbose and contract-heavy. A single widget needs a TimelineEntry, a TimelineProvider, an EntryView, and a Widget struct before you've written a line of business logic. An App Intent needs parameters, metadata, privacy assumptions, and Swift that fits Apple's expectations.

Axint gives agents and developers a smaller authoring surface. One defineIntent() call can replace the intent boilerplate an agent would otherwise regenerate token by token. One defineWidget() can replace the WidgetKit stack. The compiler handles the struct conformances, @Parameter wrappers, LocalizedStringResource literals, plist fragments, entitlements, diagnostics, and repair artifacts around the generated Swift.

Four surfaces, one pipeline:

defineIntent()  →  App Intent for Siri & Shortcuts
defineView()    →  SwiftUI view
defineWidget()  →  WidgetKit widget
defineApp()     →  Full app scaffold

The result: teams and AI tools can author Apple-native features in a smaller surface than hand-written Swift, inspect ordinary generated Swift when it matters, then use Axint Check and Fix Packets to keep the repair loop grounded in the same facts.

---

Quick start

Create the Apple Day Agent starter

If you want the fastest shareable proof path, start here:

npx -y -p @axint/compiler create-axint-app apple-day-agent
cd apple-day-agent
npm run proof
open share/built-with-axint.html

This creates a premium Apple-native mini app instead of a blank scaffold:

• intents/create-event.ts is the App Intent source contract.
• intents/create-reminder.ts and intents/check-weather.ts add two more Apple capabilities.
• .axint/agent-prompts/ gives Codex, Claude Code, and Cursor the exact proof loop.
• ios/App/DayDashboardView.swift gives the starter a real SwiftUI app shell.
• .axint/run/latest.md starts the durable proof trail.
• share/built-with-axint.html gives you an interactive proof preview with the generated app shell, contracts, Swift, and proof.

The point is to make the first run feel real: agent writes Apple-native contracts, Axint compiles multiple capabilities, validates them, renders a usable app preview, and hands the agent a repair path when something breaks.

npm install -g @axint/compiler
axint activate

# initialize Axint inside an existing Apple/Xcode project
axint init --apple-project /path/to/MyApp --agent codex

# compile a single file
axint compile my-intent.ts --out ios/Intents/

# or pipe to stdout
npx -y -p @axint/compiler axint compile my-intent.ts --stdout

Intent

import { defineIntent, param } from "@axint/compiler";

export default defineIntent({
  name: "CreateEvent",
  title: "Create Calendar Event",
  description: "Creates a new event in the user's calendar.",
  domain: "productivity",
  params: {
    title: param.string("Event title"),
    date: param.date("Event date"),
    duration: param.duration("Event duration", { default: "1h" }),
    location: param.string("Location", { required: false }),
  },
});

View

import { defineView, prop, state, view } from "@axint/compiler";

export default defineView({
  name: "EventCard",
  props: {
    title: prop.string(),
    date: prop.date(),
  },
  state: {
    isExpanded: state.boolean(false),
  },
  body: [
    view.vstack({ alignment: "leading", spacing: 8 }, [
      view.text("entry.title"),
      view.conditional("isExpanded", [view.text("entry.date")]),
    ]),
  ],
});

Widget

import { defineWidget, entry, view } from "@axint/compiler";

export default defineWidget({
  name: "EventCountdown",
  displayName: "Event Countdown",
  description: "Shows time until the next event.",
  families: ["systemSmall", "systemMedium"],
  entry: {
    eventName: entry.string("Untitled"),
    minutesUntil: entry.int(0),
  },
  body: [
    view.vstack({ alignment: "center", spacing: 4 }, [
      view.text("entry.eventName"),
      view.text("entry.minutesUntil"),
    ]),
  ],
});

App

import { defineApp, scene, storage } from "@axint/compiler";

export default defineApp({
  name: "WeatherApp",
  scenes: [
    scene.windowGroup("WeatherDashboard"),
    scene.settings("SettingsView", { platform: "macOS" }),
  ],
  appStorage: {
    useCelsius: storage.boolean("use_celsius", true),
    lastCity: storage.string("last_city", "Cupertino"),
  },
});

Compile any surface the same way:

axint compile my-intent.ts --out ios/Intents/
axint compile my-view.ts --out ios/Views/
axint compile my-widget.ts --out ios/Widgets/
axint compile my-app.ts --out ios/App/

Repair an existing Apple app

When the Swift already exists and something subtle breaks, use the project-aware repair loop instead of asking an agent to guess from one file:

axint project index --changed Sources/HomeComposer.swift Sources/FeedScreen.swift

axint repair "comment box is visible but cannot be tapped" \
  --source Sources/HomeComposer.swift \
  --platform ios \
  --actual "visible composer no longer accepts focus or typing" \
  --agent codex

axint feedback latest --format markdown
axint feedback status

axint repair writes .axint/repair/latest.* and a privacy-safe .axint/feedback/latest.json packet. The feedback packet includes project shape, diagnostic codes, issue class, redacted evidence, and likely Axint product owner, but not source code.

Axint also queues source-free feedback automatically when Cloud Check, Run, or Repair finds an Axint learning signal. The default endpoint is https://registry.axint.ai/api/v1/feedback; packets declare source_not_included, never include source by default, and can be turned off with axint feedback opt-out, AXINT_FEEDBACK=off, or AXINT_DISABLE_FEEDBACK=1. Use axint feedback list on a maintainer inbox to cluster imported edge cases into the next Axint fixes.

Axint also sends a tiny source-free adoption heartbeat so the project can see which install paths are actually working: CLI command class, MCP tool name, version, coarse host hint, OS family, Node major version, CI flag, and a random anonymous install ID. It never sends source code, prompts, generated Swift, arguments, file names, local paths, credentials, or machine IDs. Inspect it with axint telemetry status, turn it off with axint telemetry opt-out, or disable it per process with AXINT_TELEMETRY=off / AXINT_DISABLE_TELEMETRY=1.

The same senior repair read is shared by axint.suggest, axint.feature, axint.cloud.check, and axint.repair. If a prompt describes a broken existing SwiftUI flow, Axint routes toward the smallest repair/proof loop instead of generating a replacement screen. New-component prompts can still reference existing app types as context without being blocked.

When MCP transport is stale or closed, use axint suggest <app-description> as the CLI fallback, then continue the same workflow check with --ran-suggest.

---

Public truth

v0.4.32 · 36 MCP tools + 5 prompts · 217 diagnostic codes · 1432 tests · 58 live packages · 50 bundled templates Public proof is regenerated from the compiler's metrics pipeline on every release (`npm run metrics:emit && npm run metrics:check`).

If release numbers, diagnostics, package counts, or MCP surfaces change, update the canonical truth layer and re-run the sync instead of editing proof values by hand.

---

Watch mode

Recompiles on every save with 150ms debounce, inline errors, and optional swift build after each successful compile:

axint watch ./intents/ --out ios/Intents/ --emit-info-plist --emit-entitlements
axint watch my-intent.ts --out ios/Intents/ --format --swift-build

---

Axint Run

axint run is the local/BYO-Mac build loop for Apple projects. It exists so agents do not have to remember separate Axint steps after a long chat or context compaction.

axint session start --dir /path/to/MyApp --name MyApp --agent codex
axint workflow check --dir /path/to/MyApp --agent codex --stage context-recovery --session-token <token> --read-rehydration-context --read-agent-instructions --read-docs-context --ran-status
axint xcode setup --agent claude --guarded --project /path/to/MyApp --name MyApp
axint xcode setup --agent claude --guarded --local-build --project /path/to/MyApp --name MyApp
axint xcode guard --dir /path/to/MyApp --stage context-recovery
axint agent install --dir /path/to/MyApp --agent codex
axint agent advice --dir /path/to/MyApp --agent codex --changed Sources/HomeComposer.swift Tests/HomeComposerUITests.swift
axint memory index --dir /path/to/MyApp --changed Sources/HomeComposer.swift Tests/HomeComposerUITests.swift
axint run --dir /path/to/MyApp --agent codex --scheme MyApp --destination "platform=macOS"
axint run --dir /path/to/MyApp --agent codex --scheme MyApp --changed Sources/HomeComposer.swift --only-testing MyAppUITests/MyAppUITests/testComposerStillAcceptsInput
axint run --dir /path/to/MyApp --agent codex --scheme MyApp --runtime
axint run status --dir /path/to/MyApp
axint run cancel --dir /path/to/MyApp --id axrun_...
axint run --dir /path/to/MyApp --agent codex --scheme MyApp --format json
axint run --dir /path/to/MyApp --agent codex --scheme MyApp --format json --include-source
axint runner once --dir /path/to/MyApp --agent codex --scheme MyApp

axint xcode setup --guarded configures the Xcode Claude Agent with durable MCP paths, writes the project memory pack, starts a session, and creates .axint/guard/latest.json plus .axint/guard/latest.md. That guard report is the audit trail for the problem where an Xcode agent works for a long block, compacts context, and silently stops using Axint.

Use --local-build only while dogfooding this checkout before publishing; it points Xcode at the built local MCP server instead of the npm package.

Agent lanes are explicit now. Codex, Claude Code, Cursor, and Cowork should use their native patch/edit tools for existing files, then run axint workflow check, axint validate-swift, axint cloud check, and axint run. Xcode-hosted agents can use axint.xcode.guard and axint.xcode.write because those tools create real Xcode guard proof.

When an Xcode MCP agent is creating a new Swift file, use axint.xcode.write instead of a raw file write. The tool writes inside the project root, validates Swift, runs Cloud Check, and updates the guard proof in one call. Outside Xcode, do not route routine edits through axint.xcode.write; patch surgically in the active client and let Axint validate the result.

The run starts an agent-specific Axint session, refreshes the project recovery context, validates changed Swift, runs Cloud Check, executes xcodebuild build and xcodebuild test, optionally launches a macOS app for runtime proof, writes .axint/run/latest.json plus .axint/run/latest.md, and stores source-free Cloud learning packets under .axint/feedback when repeated failure shapes appear. Passing focused --only-testing selectors are fed back into Cloud Check so stale UI/accessibility warnings do not override real focused test proof. Failing Xcode tests are extracted from command output and .xcresult when available, then printed under ## Xcode Test Failures with test name, file/line, assertion, likely source area, and identifier so the next repair starts from the real failure.

axint memory index turns the local proof trail into .axint/memory/latest.json and .axint/memory/latest.md. It summarizes risky SwiftUI files, changed files, latest run status, failing tests, latest repair packet, and privacy-safe learning packets so Codex, Claude, Cursor, Xcode, and humans can rehydrate the same project state.

For a repeatable first-use demo, inspect examples/wow/composer-blocker. It models a real SwiftUI bug where an invisible overlay blocks a composer text field and includes a focused UI-test failure for Axint to diagnose.

Long runs also write .axint/run/jobs/<id>.json and .axint/run/latest-active.json. If a client disconnects, an MCP transport times out, or an agent needs to rejoin a build in the same thread, use axint run status to see active process IDs and axint run cancel to stop the child process group without restarting the whole chat.

Rendered axint run --format json is compact by default: it keeps verdict, evidence, diagnostics, artifact paths, feedback packet paths, and next actions visible while omitting full Swift source and trimming long command output. Use --include-source only when the active agent explicitly needs inline Swift/code output in the response.

Agent-token safety is also built into the default run loop. axint run keeps full command logs on disk under .axint/run/logs, while the agent-facing report keeps compact tails and artifact paths. If you omit --changed, Axint validates the project but Cloud Checks only the highest-risk Swift files instead of pushing every source file into the next agent turn. Pass --changed <files> when you want a focused full proof loop.

The MCP tool listing is compact by default for the same reason: agents receive tool names, schemas, enums, and short summaries instead of the full prose-heavy manifest. Set AXINT_MCP_MANIFEST_MODE=full or AXINT_MCP_FULL_MANIFEST=1 only when debugging tool documentation.

Use --dry-run to prove the harness and planned xcodebuild commands before letting a local or BYO Mac runner execute the job.

If an MCP client still lists Axint tools after the transport has closed, use the CLI fallback instead of restarting the whole thread:

axint workflow check --dir /path/to/MyApp --agent codex --stage pre-build --session-token <token> --ran-swift-validate --ran-cloud-check --modified Sources/HomeComposer.swift

This open-source repository does not include the proprietary hosted Axint Cloud control plane: job queues, Mac fleet orchestration, billing, signed-in Pro entitlements, stored report history, or learning pipelines live outside the compiler package.

---

Same-thread upgrades

Agent sessions should not have to restart from scratch just because Axint shipped a new version. Use the upgrade flow inside Codex, Claude, Xcode, or any MCP client to check the latest package, install it when ready, refresh optional Xcode wiring, and write a continuation packet under .axint/upgrade/latest.*.

axint upgrade
axint upgrade --apply
axint upgrade --apply --xcode-install
axint upgrade --target 0.4.31 --apply

From MCP, call axint.upgrade. The tool returns the exact command plan plus a same-thread prompt that tells the agent to keep the current conversation, reload or reconnect only the Axint MCP server/tool process, then call axint.status and axint.activate to prove the running version and first real Axint output before editing code.

---

MCP server

Axint ships an MCP server for Claude Desktop, Claude Code, Cursor, Codex, VS Code, Windsurf, Xcode, and any MCP client. ```json

{ "mcpServers": { "axint": { "command": "npx", "args": [ "-y", "-p", "@axint/compiler", "axint-mcp" ] } } }

MCP tools and built-in prompts:

| Tool | What it does |
| --- | --- |
| `axint.status` | Report the running MCP server version, package path, uptime, and same-thread reload/update instructions |
| `axint.activate` | Run a source-free compiler smoke test so a fresh install proves first real Axint use |
| `axint.upgrade` | Check or apply an Axint upgrade, refresh optional Xcode wiring, and return a same-thread continuation prompt |
| `axint.doctor` | Audit version truth, Node/npm/npx paths, project MCP wiring, and agent start-pack files |
| `axint.xcode.guard` | Guard Xcode agent sessions against context compaction and Axint drift, then write `.axint/guard/latest.*` proof artifacts |
| `axint.xcode.write` | Write a project file through Axint, then validate Swift, run Cloud Check, and update guard proof for Swift files |
| `axint.session.start` | Start an enforced agent session, refresh `.axint/AXINT_REHYDRATE.md`, write `.axint/session/current.json`, and return the token required by workflow gates |
| `axint.compile` | Full pipeline: TypeScript → Swift + plist + entitlements |
| `axint.schema.compile` | Minimal JSON → Swift (token-saving mode for agents) |
| `axint.validate` | Dry-run validation with diagnostics |
| `axint.feature` | Generate an editable feature package: intents, views, widgets, components, app shells, stores, tests, and support fragments |
| `axint.project.pack` | Generate `.mcp.json`, `AGENTS.md`, `CLAUDE.md`, `.axint` rehydration/memory/docs/project files, and the session-first workflow for first-try agent setup |
| `axint.project.index` | Scan the local Apple project and write a compact `.axint/context` pack so Cloud Check can reason over changed files and nearby SwiftUI surfaces |
| `axint.project.syncVersion` | Refresh Axint-owned project-pack version hints after an upgrade so local agent truth does not point at an older package |
| `axint.context.memory` | Return the compact Axint operating memory for new chats and context-compaction recovery |
| `axint.context.docs` | Return the project-local Axint docs context so agents can reload docs after compaction |
| `axint.suggest` | Suggest app-specific Apple-native features, reusable components, and shared stores from a product description |
| `axint suggest` | CLI fallback for the same suggestion pass when MCP transport is stale, closed, or unavailable |
| `axint.registry.search` | Search the Axint Registry for already-published packages that match a natural-language query — call this before `axint.feature` so agents install existing packages instead of regenerating Swift the community has shipped |
| `axint.workflow.check` | Check whether an agent rehydrated Axint after compaction, has an active session token, and used suggest, feature, swift.validate, cloud.check, and Xcode proof before moving on |
| `axint workflow check` | CLI fallback for the same workflow gate when MCP is stale, closed, or unavailable |
| `axint.scaffold` | Generate a starter TypeScript intent from a description |
| `axint.swift.validate` | Validate existing Swift against build-time rules |
| `axint.swift.fix` | Auto-fix mechanical Swift errors (concurrency, Live Activities) |
| `axint.fix-packet` | Read the latest AI-ready repair packet from a local compile or watch run |
| `axint.cloud.check` | Run an agent-callable Cloud Check report against Swift or TypeScript source |
| `axint.repair` | Plan a project-aware Apple repair loop for existing app bugs, with likely files, root causes, host-aware patch guidance, proof commands, and feedback packet |
| `axint.feedback.create` | Create or read a privacy-safe, source-free feedback packet |
| `axint feedback status / opt-out / opt-in / sync / list` | Manage automatic source-free feedback, opt out, retry queued packets, and cluster imported feedback into Axint fix queues |
| `axint telemetry status / opt-out / opt-in` | Inspect and manage source-free adoption telemetry for CLI and MCP usage |
| `axint.agent.install` | Install the local multi-agent project brain so Codex, Claude, Cursor, Xcode, and humans share one `.axint` truth layer |
| `axint.agent.advice` | Return host-specific next moves from project context, active claims, latest proof, and latest repair artifacts |
| `axint.agent.claim` | Claim files before an agent edits them so other agents avoid conflicting patches |
| `axint.agent.release` | Release local file claims after an agent finishes or abandons a task |
| `axint.run` | Run the enforced Apple build loop: session, workflow gate, Swift validation, Cloud Check, xcodebuild build/test, optional runtime launch, and `.axint/run` artifacts |
| `axint.run.status` | Read the latest or selected Axint run job, including active child process IDs, after client disconnects or long-running builds |
| `axint.run.cancel` | Cancel the latest or selected active Axint run by stopping child process groups |
| `axint.tokens.ingest` | Convert design tokens into SwiftUI token enums for generated views |
| `axint.templates.list` | List bundled reference templates |
| `axint.templates.get` | Return the source of a specific template |

Built-in prompts:

| Prompt | What it does |
| --- | --- |
| `axint.project-start` | Start an Xcode/Apple project by reading the docs, verifying MCP, and establishing the check/fix loop |
| `axint.context-recovery` | Recover Axint after a new chat, context compaction, or long coding drift |
| `axint.quick-start` | Get a quick-start guide |
| `axint.create-intent` | Start a new intent from guided parameters |
| `axint.create-widget` | Start a new widget from guided parameters |

`axint.schema.compile` is the key optimization — agents send ~20 tokens of JSON and get compiled Swift back directly, skipping TypeScript entirely.

<!-- truth:readme-discovery-links:start -->Need a working repo instead of a raw snippet? Browse **[axint-examples](https://github.com/agenticempire/axint-examples)**. Still seeing older package names like `@axintai/compiler`? Use the current package identity: `@axint/compiler`.<!-- truth:readme-discovery-links:end -->

---

## Diagnostics

Diagnostic codes across the validator surface with fix suggestions and color-coded output:

| Range | Domain |
| --- | --- |
| `AX000`–`AX023` | Compiler / Parser |
| `AX100`–`AX118` | Intent |
| `AX200`–`AX202` | Swift output |
| `AX300`–`AX322` | View |
| `AX400`–`AX422` | Widget |
| `AX500`–`AX522` | App |
| `AX700`–`AX750` | Swift build rules |
| `AX720`–`AX737` | Swift 6, SwiftUI, and accessibility checks |
| `AX740`–`AX749` | Live Activities |

```text
error[AX100]: Intent name "sendMessage" must be PascalCase
  --> src/intents/messaging.ts:5:9
   = help: rename to "SendMessage"

Full reference: docs/ERRORS.md

---

Type mappings

TypeScript	Swift	Default value
string	String	✓
int	Int	✓
double	Double	✓
float	Float	✓
boolean	Bool	✓
date	Date	—
duration	Measurement<UnitDuration>	✓ ("1h")
url	URL	—
optional<T>	T?	✓

---

Playground

No install required — cloud.axint.ai runs the same compiler in a server-backed playground, returning Swift live without a local install.

---

Editor extensions

Extensions for Claude Code, Claude Desktop, Codex, VS Code / Cursor, Windsurf, JetBrains, Neovim, and Xcode.

---

Project structure

axint/
├── src/
│   ├── core/        # Parser, validator, generator, compiler, IR
│   ├── sdk/         # defineIntent(), defineView(), defineWidget(), defineApp()
│   ├── mcp/         # MCP server and prompt surface
│   ├── cli/         # CLI (compile, watch, validate, eject, init, xcode)
│   └── templates/   # Bundled reference templates
├── python/          # Python SDK
├── extensions/      # Editor extensions (9 editors)
├── spm-plugin/      # Xcode SPM build plugin
├── tests/           # Compiler, CLI, SDK, MCP, and Python coverage
├── examples/        # Example definitions
└── docs/            # Error reference, assets

---

What's next

Current priorities — full roadmap in ROADMAP.md:

• IntentDialog + richer Apple parameter types
• Swift → TypeScript round-trip for existing Apple projects
• More surface templates in the registry (Control Widgets, App Shortcuts catalog)

---

Contributing

PRs reviewed within 48 hours. Browse good first issue to get started, or see CONTRIBUTING.md.

Apache 2.0, no CLA.

---

Requirements

• Node.js 22+
• Any OS (macOS, Linux, Windows)
• Xcode 15+ to ship the generated Swift

---

License

Apache 2.0 — fork it, extend it, ship it.

---