Contributing to Axint

July 14, 2026 · View on GitHub

Thanks for considering a contribution to Axint. This guide will get you oriented quickly.

Before You Start

  1. Open an issue first for large changes. Bug fixes and new templates can go straight to a PR. But if you're changing the compiler, validator, type system, or MCP server architecture, open an issue or discussion first so we can align on the approach before you invest time.

  2. Check existing issues. Browse open issues — especially those labeled good first issue — to find work that's ready to pick up.

Architecture Overview

Understanding the project structure will save you time. Axint is no longer only a TypeScript-to-Swift compiler; the repo also contains the repair loop, MCP surface, project memory, Xcode proof path, telemetry controls, and starter generation that make the compiler useful to agents.

src/
├── core/
│   ├── parser.ts        # Extracts defineIntent() calls → IR
│   ├── view-parser.ts   # SwiftUI view parser
│   ├── widget-parser.ts # WidgetKit parser
│   ├── app-parser.ts    # SwiftUI app scaffold parser
│   ├── generator.ts     # Transforms IR → Swift source
│   ├── swift-validator.ts # Existing Swift repair/diagnostic rules
│   ├── compiler.ts      # Orchestrates the full compile pipeline
│   ├── types.ts         # IR types, Swift type mappings, diagnostics
│   └── index.ts         # Barrel export
├── sdk/
│   └── index.ts         # define*() APIs and helpers (exported from `@axint/compiler`)
├── mcp/
│   ├── server.ts        # MCP server with axint.* tools and built-in prompts
│   ├── manifest.ts      # Runtime marketplace/tool description surface
│   ├── index.ts         # Import surface and direct stdio entry point
│   └── register.ts      # axint-mcp binary entry point
├── templates/
│   └── index.ts         # Intent template registry (templates welcome!)
└── cli/
    └── index.ts         # CLI entry: create, compile, validate, repair, run, xcode

Key data flow:

TypeScript / Python / JSON / .axint definition
        ↓
   parser or schema lowering → Intermediate Representation (IR)
        ↓
   validator           → checks Apple API constraints
        ↓
   generator           → emits Swift, plist, and entitlements
        ↓
   Swift validator     → catches build-time Apple and SwiftUI failures
        ↓
   Fix Packet / Run proof / MCP response

What We're Looking For

Always Welcome (just open a PR)

  • New intent templates — Calendar, reminders, messaging, media playback, smart home, health, maps, payments. Each template in src/templates/ follows a consistent pattern. Look at an existing one and add yours.
  • Existing-product repair fixtures — Small SwiftUI/Xcode examples where Axint should diagnose a real failure such as blocked taps, scroll regressions, missing imports, bad bindings, or concurrency issues.
  • Documentation — Better explanations, more examples, typo fixes.
  • Bug fixes — Especially with a failing test that demonstrates the issue.
  • Test coverage — We can always use more tests, particularly for edge cases in the compiler and validator.

Welcome With Prior Discussion (open an issue first)

  • New MCP tools — Additional tools exposed through the MCP server.
  • Compiler changes — Modifications to the TypeScript/Python/JSON/.axint → IR → Swift pipeline.
  • New target surfaces — Support for SiriKit, Shortcuts, or other Apple execution surfaces beyond App Intents.
  • Dependency additions — Any new runtime dependency needs justification.

Out of Scope for This Repo

The open-source repository is for the compiler, SDKs, CLI, MCP server, templates, tests, and editor integrations.

Please do not open PRs that add private product materials or internal operating docs here, such as:

  • Launch copy or GTM assets
  • Private website or registry implementation details
  • Hosted service playbooks or commercial planning docs
  • Internal analytics, sales, or partnership materials
  • Local-machine paths, internal agent instructions, or private implementation plans

Development Setup

# Clone the repo
git clone https://github.com/agenticempire/axint.git
cd axint

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run the CLI locally
npm run dev -- compile examples/calendar-assistant.ts --stdout

Fastest first contribution path

If you want the cleanest first PR:

  1. Pick a small bug, doc fix, template improvement, or validator edge case.
  2. Reproduce it with the smallest possible fixture in tests/.
  3. Make the code change in the matching src/ area.
  4. Run the narrowest checks first, then the repo-wide gates:
npm run typecheck
npm run lint
npm run build
npm run metrics:check
npm test

Good “first contribution” categories:

  • small validator or generator bug fixes
  • additional tests for real edge cases
  • template improvements
  • doc corrections
  • Xcode workflow polish

Pull Request Process

  1. Fork and branch. Create a feature branch from main. Use a descriptive name: feat/smart-home-template, fix/parameter-type-marshaling, docs/mcp-setup-guide.

  2. Write tests. New features need tests. Bug fixes need a test that would have caught the bug. Tests live in tests/ mirroring the src/ structure.

  3. Follow existing patterns. Match the code style you see in the repo. We use Prettier for formatting and ESLint for linting:

    npm run lint
npm run format

  4. Keep PRs focused. One feature or fix per PR. If you find an unrelated issue while working, open a separate PR for it.

  5. Write a clear PR description. Explain what changed and why. If it's a template, show an example of the TypeScript input and Swift output.

  6. CI must pass. All tests, linting, and type checks must pass before merge.

Release process

Releases should feel boring and reproducible.

Use this checklist:

  1. Sync versions and metrics:
npm run versions:check
npm run metrics:check
  1. Run the core repo gates:
npm run typecheck
npm run lint
npm run build
npm test
  1. If Xcode repair rules changed, confirm the checked-in fixer is current:
npm run gen:swift-fixer:check

  1. If docs or public proof changed, update:

    • README.md
    • docs/ERRORS.md
    • docs/COVERAGE.md
    • docs/RELEASE_NOTES.md

  2. If headline numbers or public proof changed, sync the downstream public surfaces that read from the truth bundle before announcing the release.

  3. Keep package releases aligned. Intentional releases now require npm and PyPI to move together. The release workflow:

    • requires PYPI_TOKEN
    • verifies both registries are in sync before publish
    • verifies both registries are live after publish

    You can run the same guard locally with:

    npm run release:check

  4. Only tag and publish once the repo state, docs, metrics, and downstream public proof all agree.

Adding a New Template

Templates are the easiest way to contribute. Here's the pattern:

// src/templates/your-template.ts
import type { IntentTemplate } from "../templates/index";

export const yourTemplate: IntentTemplate = {
  id: "your-template",
  name: "Your Template Name",
  description: "What this template does",
  category: "productivity", // e.g., "productivity", "media", "smart-home"
  source: `
import { defineIntent, param } from "@axint/compiler";

export default defineIntent({
  name: "YourIntent",
  title: "Your Intent Title",
  description: "What this intent does",
  params: {
    // Define parameters here
  },
  perform: async (params) => {
    return { success: true };
  },
});
  `.trim(),
};

Then register it in src/templates/index.ts by adding it to the templates array.

Code of Conduct

Be respectful. Be constructive. We're building something together. Toxic behavior, harassment, and bad-faith engagement will result in removal from the project.

Questions?

  • GitHub Discussions — For architecture questions and ideas
  • GitHub Issues — For bugs, regressions, and feature requests

Thanks for helping Apple coding agents produce work that can be checked, repaired, and proved.