2025-11-30 09:40:00 -08:00
# Axiom
2026-06-24 09:59:38 -07:00
Battle-tested skills, agents, and tools for modern Apple OS development — Swift 6, SwiftUI, Liquid Glass, Apple Intelligence, and more. Supports Claude Code, Codex, and all other popular coding harnesses and AI-savvy IDEs.
2025-11-30 09:40:00 -08:00
2026-03-15 20:46:43 -07:00
## What is Axiom?
2025-11-30 09:40:00 -08:00
2026-06-24 09:59:38 -07:00
Axiom gives AI coding assistants deep Apple OS development expertise — the kind that prevents data loss from bad migrations, catches memory leaks before users complain, and stops you from spending 30 minutes debugging a zombie xcodebuild process.
2026-02-03 11:32:48 -08:00
feat(axiom-swiftui): add previews + previews-ref sub-skills + fix README count drift
Closes the coverage gap on *building* SwiftUI previews. Axiom previously
covered *broken* previews (debugging.md Preview Crashes Decision Tree) but
nothing on building good previews — perf rules, PreviewModifier,
@Previewable, Variant Mode, environment setup, when previews are the wrong
tool. Now both halves are first-class skills with bidirectional cross-refs.
New skills (axiom-swiftui/skills/):
- previews.md (discipline, 450 L): previewability principle, five
performance rules ordered by impact (Swift Package isolation, then
PreviewModifier, pin, auto-refresh, XCODE_RUNNING_FOR_PREVIEWS guard),
six environment-setup patterns (A-F), variant matrix discipline,
"when NOT to use previews" boundary, three pressure scenarios, anti-
pattern table.
- previews-ref.md (reference, 588 L): #Preview macro signatures (view,
widget, Live Activity), @Previewable semantics, PreviewModifier protocol
with both @Observable AND Apple-published SwiftData ModelContainer
canonical examples, PreviewTrait table, canvas modes, Variant Mode,
Development Assets, XCPreviewAgent, full PreviewProvider → #Preview
migration table, known issues (Xcode 26.x preview-target gotcha,
ENABLE_PREVIEWS removed in Xcode 16+).
Live-DOM API verifications (per the framework-gap discipline):
- PreviewModifier: Xcode 16+/iOS 18+/macOS 15+ (initial subagent fetch
reported 15.4+/17.5+; corrected via live sosumi.ai re-fetch).
- makeSharedContext(): @MainActor static func ... async throws ->
Self.Context; concrete impls may drop async per Swift's protocol-
satisfaction rules.
- Variants Mode dimensions: Apple only confirms Color Scheme + Dynamic
Type by name in WWDC 2023-10252; corrected from inflated 4-dimension
claim.
- XCODE_RUNNING_FOR_PREVIEWS == "1" stable Xcode 15-26;
ENABLE_PREVIEWS dropped in Xcode 16+ (added to known issues).
Wiring:
- axiom-swiftui/SKILL.md router: 3 Quick Reference rows + 3 decision-
tree branches + 2 anti-rationalization rows.
- debugging.md: scope note at Preview Crashes section pointing back to
previews.md / previews-ref.md.
- hooks/user-prompt-submit.py: new regex catching preview-construction
patterns (slow previews, @Previewable, PreviewModifier, Variant Mode,
sizeThatFitsLayout, XCODE_RUNNING_FOR_PREVIEWS, Development Assets).
- hooks/user-prompt-submit_test.py: 3 new test methods (slow / api /
perf_patterns); total 67/67 pass.
- axiom-mcp/skill-annotations.json: entries with tags + cross-refs.
- docs/skills/ui-design/swiftui-previews.md + docs/reference/swiftui-
previews-ref.md: VitePress pages.
- docs/.vitepress/config.ts: sidebar entries.
Validation:
- /review-skill x2 caught and corrected the PreviewModifier availability
error, a Date + 60 compile error, and a missing Preview.ViewTraits
explanation before ship.
- 5-scenario GREEN-phase router routing test: 5/5 PASS first attempt.
- 2-scenario TDD pressure test: A (variant audit — GREEN used Variant
Mode for 24 visual variants in 4 previews where RED hand-rolled 7
and missed Variant Mode entirely) + B (sunk cost — Opus baseline
already knew XCODE_RUNNING_FOR_PREVIEWS).
Also includes README count auto-maintenance (closes axiom-wz9k):
- README.md gets AXIOM_STATS_BEGIN/END markers around the skill/agent/
command bullet block (and corrects the existing drift: 231 -> 236
skills, 38 -> 39 agents).
- scripts/set-version.js: new step 7 that rewrites the marked block on
every version-script invocation, fails fast if markers missing.
- scripts/pre-deploy.ts: new check 12e sources stats.json as truth and
errors on any drift between README and stats. Drift now FAILS the
build instead of slipping through.
Closes axiom-j2u1
Closes axiom-wz9k
2026-05-28 10:30:31 -07:00
<!-- AXIOM_STATS_BEGIN — auto-maintained by scripts/set-version.js; do not hand-edit -->
chore: bump version to 27.0.0
Axiom leaves beta for the OS 27 cycle.
- iPhone Duo hub in axiom-swiftui, with fold, pose, and camera guidance
folded into layout, presentation, adaptive-layout, and camera skills
(276 skills, up from 275)
- Every 27-cycle claim re-verified against the Xcode 27.0 RC, plus 27.0
SDK coverage for AVFoundation, PhotoKit, ScreenCaptureKit, Background
Assets, XCUITest VoiceOver, and TextKit
- UIDesignRequiresCompatibility is ignored for 27-SDK builds on OS 27;
the Liquid Glass skill and auditor are corrected to match
- iOS 26 navigation bar subtitles in SwiftUI and UIKit, with hook routing
- Authoring metadata footers removed from skill files
- Cursor variant and MCP bundle regenerated
Gates: test:full both phases, version parity across all 9 files, unit
suite 488/488, hook tests 144, MCP tests 181, cross-refs 333 files / 27
suites, router integrity, VitePress dead-link validated.
2026-09-14 10:40:12 -07:00
- **276 skills** covering UI, data, concurrency, performance, networking, accessibility, and more
2026-07-24 09:57:39 -07:00
- **42 agents** that autonomously scan for issues (memory leaks, concurrency violations, build problems)
2026-07-25 09:52:13 -07:00
- **17 commands** for quick audits and diagnostics
feat(axiom-swiftui): add previews + previews-ref sub-skills + fix README count drift
Closes the coverage gap on *building* SwiftUI previews. Axiom previously
covered *broken* previews (debugging.md Preview Crashes Decision Tree) but
nothing on building good previews — perf rules, PreviewModifier,
@Previewable, Variant Mode, environment setup, when previews are the wrong
tool. Now both halves are first-class skills with bidirectional cross-refs.
New skills (axiom-swiftui/skills/):
- previews.md (discipline, 450 L): previewability principle, five
performance rules ordered by impact (Swift Package isolation, then
PreviewModifier, pin, auto-refresh, XCODE_RUNNING_FOR_PREVIEWS guard),
six environment-setup patterns (A-F), variant matrix discipline,
"when NOT to use previews" boundary, three pressure scenarios, anti-
pattern table.
- previews-ref.md (reference, 588 L): #Preview macro signatures (view,
widget, Live Activity), @Previewable semantics, PreviewModifier protocol
with both @Observable AND Apple-published SwiftData ModelContainer
canonical examples, PreviewTrait table, canvas modes, Variant Mode,
Development Assets, XCPreviewAgent, full PreviewProvider → #Preview
migration table, known issues (Xcode 26.x preview-target gotcha,
ENABLE_PREVIEWS removed in Xcode 16+).
Live-DOM API verifications (per the framework-gap discipline):
- PreviewModifier: Xcode 16+/iOS 18+/macOS 15+ (initial subagent fetch
reported 15.4+/17.5+; corrected via live sosumi.ai re-fetch).
- makeSharedContext(): @MainActor static func ... async throws ->
Self.Context; concrete impls may drop async per Swift's protocol-
satisfaction rules.
- Variants Mode dimensions: Apple only confirms Color Scheme + Dynamic
Type by name in WWDC 2023-10252; corrected from inflated 4-dimension
claim.
- XCODE_RUNNING_FOR_PREVIEWS == "1" stable Xcode 15-26;
ENABLE_PREVIEWS dropped in Xcode 16+ (added to known issues).
Wiring:
- axiom-swiftui/SKILL.md router: 3 Quick Reference rows + 3 decision-
tree branches + 2 anti-rationalization rows.
- debugging.md: scope note at Preview Crashes section pointing back to
previews.md / previews-ref.md.
- hooks/user-prompt-submit.py: new regex catching preview-construction
patterns (slow previews, @Previewable, PreviewModifier, Variant Mode,
sizeThatFitsLayout, XCODE_RUNNING_FOR_PREVIEWS, Development Assets).
- hooks/user-prompt-submit_test.py: 3 new test methods (slow / api /
perf_patterns); total 67/67 pass.
- axiom-mcp/skill-annotations.json: entries with tags + cross-refs.
- docs/skills/ui-design/swiftui-previews.md + docs/reference/swiftui-
previews-ref.md: VitePress pages.
- docs/.vitepress/config.ts: sidebar entries.
Validation:
- /review-skill x2 caught and corrected the PreviewModifier availability
error, a Date + 60 compile error, and a missing Preview.ViewTraits
explanation before ship.
- 5-scenario GREEN-phase router routing test: 5/5 PASS first attempt.
- 2-scenario TDD pressure test: A (variant audit — GREEN used Variant
Mode for 24 visual variants in 4 previews where RED hand-rolled 7
and missed Variant Mode entirely) + B (sunk cost — Opus baseline
already knew XCODE_RUNNING_FOR_PREVIEWS).
Also includes README count auto-maintenance (closes axiom-wz9k):
- README.md gets AXIOM_STATS_BEGIN/END markers around the skill/agent/
command bullet block (and corrects the existing drift: 231 -> 236
skills, 38 -> 39 agents).
- scripts/set-version.js: new step 7 that rewrites the marked block on
every version-script invocation, fails fast if markers missing.
- scripts/pre-deploy.ts: new check 12e sources stats.json as truth and
errors on any drift between README and stats. Drift now FAILS the
build instead of slipping through.
Closes axiom-j2u1
Closes axiom-wz9k
2026-05-28 10:30:31 -07:00
<!-- AXIOM_STATS_END -->
2026-03-15 20:46:43 -07:00
- **xclog** — a built-in console capture tool that gives AI assistants access to simulator and device logs
docs(xcsym): fanout .crash support across skills, agents, and public surfaces
Follows a01ae55a (the parser + anonymizer) and 2dce73fb (the hook) by
updating every place that advertised xcsym as supporting only .ips and
MetricKit. Without these, the tool silently accepts .crash input but
every surface (session announcement, skill routers, agent descriptions,
README, VitePress landing page) still claims otherwise — users would
never know to pass .crash files.
Updated:
- Tool messages: main.go usage text; cmd_crash.go Routing hint in the
unsupported-format JSON reject (important: users who see this message
need an accurate list of what IS accepted)
- Session announcement: hooks/session-start.py — every session now
tells the agent xcsym handles .crash
- Skill content: axiom-tools (SKILL + xcsym-ref), axiom-shipping SKILL
crash-log row, axiom-build lldb + xcode-debugging, axiom-performance
SKILL decision tree
- Agent descriptions: crash-analyzer (now names .xccrashpoint bundles
explicitly), memory-auditor field-crash section, test-failure-analyzer
detection criteria
- Public docs: README.md feature bullet + command example, docs/index.md
landing tile, docs/skills/debugging/xcsym.md reference page
- Regenerated mirrors: axiom-codex/** (via npm run build:codex),
axiom-mcp/dist/bundle* (via predeploy)
- Rebuilt bin/xcsym with the updated main.go usage text
All validated by npm run predeploy (static + MCP tests + MCP bundle +
Codex build + Go tests + VitePress).
2026-04-20 12:52:59 -07:00
- **xcsym** — a built-in crash symbolication tool for `.ips` , MetricKit, and Apple's legacy `.crash` text crashes, with automatic dSYM discovery and pattern categorization
2026-06-09 11:02:51 -07:00
- **xcui** — a built-in tool to drive and validate the simulator UI and accessibility (tap by accessibility ID, dump the accessibility tree, check VoiceOver and Dynamic Type)
- **xcprof** — a built-in tool to record and analyze CPU/performance traces (xctrace) without opening Instruments
2025-12-01 11:35:14 -08:00
2026-03-29 13:28:51 -07:00
Every discipline skill is TDD-tested against real developer pressure scenarios. [Learn more about quality ](https://charleswiltgen.github.io/Axiom/start/quality ).
2025-11-30 09:40:00 -08:00
2026-06-24 09:40:13 -07:00
**OS 27 in progress. ** Axiom is on a `27.x` beta that tracks Apple's OS 27 developer betas — OS-27 coverage lands continuously through the beta season. Guidance for OS 26 and earlier stays stable.
2026-06-12 09:57:42 -07:00
2026-03-15 20:46:43 -07:00
## Installation
2025-11-30 09:40:00 -08:00
2026-03-15 20:46:43 -07:00
### Claude Code (native plugin)
2025-11-30 10:26:37 -08:00
```
2025-12-01 13:51:20 -08:00
/plugin marketplace add CharlesWiltgen/Axiom
2025-11-30 10:26:37 -08:00
```
Then search for "axiom" in the `/plugin` menu and install.
2026-08-20 19:29:30 -07:00
### Cursor (native plugin)
feat(scripts): gate the skill listing, always-on footprint, and release-surface sync
Three quality gates were measuring things nothing reads.
1. Skill-listing budget (scripts/skill-listing.ts, pre-deploy check 3).
Claude Code builds its listing from skills/*/SKILL.md frontmatter. Both prior
gates measured claude-code.json against limits Claude Code does not apply
(8,000/250 in the rule doc, 15,000/300 in pre-deploy), so neither could see
the shipped text. Seven router descriptions had drifted between the two files
and /axiom:ask, generated from the manifest array, shipped the stale wording.
The array is now generated from frontmatter with a test that fails on drift.
Real limits, measured live against a 115-skill / 24,576-char listing: the 1%
fraction is 1% of the context in TOKENS, applied in CHARACTERS at ~3 chars per
token. Sweeping skillListingBudgetFraction gave 0.001 -> 3000, 0.002 -> 6000,
0.008 -> 24000, so a 1M model allows 30,000. Per-entry cap is 1,536, not 250.
2. Always-on footprint (scripts/always-on-footprint.ts, check 3b).
The listing is a tenth of what Axiom costs. Per harness, before the user
speaks: claude-code 54,678 chars (~18,200 tok), cursor 12,961, codex 10,908,
mcp 1,454. Agent descriptions are 39,080 of the Claude Code total — 7x the
skill listing — because Cursor truncates the same 42 agents to their first
sentence and Claude Code carries the full <example> dialogues. Ratcheted per
harness so this cannot grow unmeasured again (GH #20 regrew 8.4k -> ~13k
tokens after being closed).
3. Release-surface sync (scripts/release-sync.ts, check 3c).
The marketplace is just `main`, so a tag push ships the plugin irreversibly,
while npm needs a manual publish. beta.48 shipped to plugin users and never
reached npm. Gaps are classified as unresolved (canonical itself shipped but
unpublished — fails the build) or superseded (a pending release closes it).
Also: doc-stats gains a `routers` key and registers cursor-install.md and
README.md, whose ten prose counts had nothing maintaining them — the drift that
once had install.md claiming 184 against a real 254.
2026-08-23 19:16:32 -07:00
Axiom's generated Cursor plugin includes <!--ax:routers-->27<!--/ax--> skill routers, <!--ax:agents-->42<!--/ax--> agents, <!--ax:commands-->17<!--/ax--> `/axiom-*` commands, advisory hooks, and automatic discovery of its MCP server configuration. See the [Cursor install and support guide ](https://charleswiltgen.github.io/Axiom/start/cursor-install ) for the macOS support boundary and local installation steps.
2026-08-20 19:29:30 -07:00
### MCP (VS Code, Cursor MCP-only, Gemini CLI, and more)
2025-11-30 09:40:00 -08:00
2026-03-29 13:28:51 -07:00
See the [MCP setup guide ](https://charleswiltgen.github.io/Axiom/start/mcp-install ).
2025-11-30 09:40:00 -08:00
2026-06-14 17:55:52 -07:00
### Pi (terminal coding agent)
```
pi install git:github.com/CharlesWiltgen/Axiom
```
One command installs the skills plus the `/axiom-*` commands and hooks. See the [Pi setup guide ](https://charleswiltgen.github.io/Axiom/start/pi-install ).
2026-03-15 20:46:43 -07:00
### Xcode (Claude Agent / Codex)
2025-11-30 09:40:00 -08:00
2026-03-29 13:28:51 -07:00
See the [Xcode integration guide ](https://charleswiltgen.github.io/Axiom/start/xcode-setup ).
2025-11-30 09:40:00 -08:00
2026-03-15 20:46:43 -07:00
## Getting Started
2025-11-30 09:40:00 -08:00
2026-03-15 20:46:43 -07:00
Skills activate automatically based on your questions. Just ask:
2025-12-01 14:29:16 -08:00
2026-03-15 20:46:43 -07:00
```
"I'm getting BUILD FAILED in Xcode"
"How do I fix Swift 6 concurrency errors?"
"My app has memory leaks"
"I need to add a database column safely"
"Show me what my app is logging"
2026-04-20 07:29:41 -07:00
"Symbolicate this crash file"
2026-03-15 20:46:43 -07:00
```
2026-03-12 15:26:53 -07:00
2026-03-15 20:46:43 -07:00
You can also use commands directly:
2026-03-12 15:26:53 -07:00
2026-03-15 20:46:43 -07:00
```
/axiom:console # Capture simulator console output
docs(xcsym): fanout .crash support across skills, agents, and public surfaces
Follows a01ae55a (the parser + anonymizer) and 2dce73fb (the hook) by
updating every place that advertised xcsym as supporting only .ips and
MetricKit. Without these, the tool silently accepts .crash input but
every surface (session announcement, skill routers, agent descriptions,
README, VitePress landing page) still claims otherwise — users would
never know to pass .crash files.
Updated:
- Tool messages: main.go usage text; cmd_crash.go Routing hint in the
unsupported-format JSON reject (important: users who see this message
need an accurate list of what IS accepted)
- Session announcement: hooks/session-start.py — every session now
tells the agent xcsym handles .crash
- Skill content: axiom-tools (SKILL + xcsym-ref), axiom-shipping SKILL
crash-log row, axiom-build lldb + xcode-debugging, axiom-performance
SKILL decision tree
- Agent descriptions: crash-analyzer (now names .xccrashpoint bundles
explicitly), memory-auditor field-crash section, test-failure-analyzer
detection criteria
- Public docs: README.md feature bullet + command example, docs/index.md
landing tile, docs/skills/debugging/xcsym.md reference page
- Regenerated mirrors: axiom-codex/** (via npm run build:codex),
axiom-mcp/dist/bundle* (via predeploy)
- Rebuilt bin/xcsym with the updated main.go usage text
All validated by npm run predeploy (static + MCP tests + MCP bundle +
Codex build + Go tests + VitePress).
2026-04-20 12:52:59 -07:00
/axiom:analyze-crash # Parse and triage .ips, MetricKit, or .crash reports
2026-03-15 20:46:43 -07:00
/axiom:fix-build # Diagnose build failures
/axiom:audit memory # Scan for memory leaks
/axiom:audit concurrency # Check for data races
/axiom:health-check # Run all relevant auditors
```
2026-03-12 15:26:53 -07:00
2025-11-30 09:40:00 -08:00
## Documentation
2026-03-15 20:46:43 -07:00
Full documentation, skill catalog, and guides at * * [charleswiltgen.github.io/Axiom ](https://charleswiltgen.github.io/Axiom )**.
2025-11-30 09:40:00 -08:00
2026-03-15 20:48:08 -07:00
## Community
2025-11-30 09:40:00 -08:00
2026-03-15 20:48:08 -07:00
- [r/axiomdev ](https://www.reddit.com/r/axiomdev/ ) — Version announcements with changelogs
2026-03-15 20:46:43 -07:00
- [Report issues or request features ](https://github.com/CharlesWiltgen/Axiom/issues )
- [Share usage patterns and questions ](https://github.com/CharlesWiltgen/Axiom/discussions )
