# Competitive Parity Gaps

**Status:** Living doc  •  **Owner:** Benjamin Booth  •  **Last updated:** 2026-05-02

Running catalog of where Axiom trails peer agent harnesses (Claude Code, Cursor, Aider, Mastra, LangGraph, OpenAI Agents, Codex, Hermes). Items here are neither roadmap nor commitments — they're signal. We fill gaps when doing so unlocks real user value, not because a competitor has a feature.

Populated from the 2026-04-22 harness-parity audit and grown during Tier 1c migration work. Each item names what the gap is, what the nearest peer does, and a quick cost/risk read.

---

## Runtime / control plane

| Gap | Peer reference | Why it matters | Cost |
|---|---|---|---|
| **Platform lifecycle hooks** (PreToolUse, PostToolUse, UserPromptSubmit, Stop) at the harness layer | Claude Code | Extensions have hooks as a capability kind (AEOS §4.7); the platform itself has no equivalent. | Medium — mirror the AEOS hook kind at platform scope. |
| **HITL approval checkpoints at runtime** (agent pauses → human approves → continues) | LangGraph | RACI is our *policy* layer; this is the *mechanism*. Without it, long chains can't pause for human review. | Large — new primitive. |
| **Streaming + user-interrupt mid-stream** (Esc to halt, redirect) | Claude Code, Cursor | Interactive UX cornerstone. | Medium — gateway-level work. |
| **Cost / budget tracking** (token + dollar totals, budget caps, per-session display) | Claude Code, OpenAI Agents | Table stakes for any multi-turn harness; we show nothing today. | Small — wrap existing gateway calls. |
| **Fine-grained per-tool permissions** (allow/deny/ask patterns per principal) | Claude Code | Trust profiles are coarser; this is per-invocation granularity. **Partial (2026-05-01, T1.3):** chat session now has per-tool allowlist via `/permissions` slash command + footer indicator. Per-principal scope still pending. | Medium — extends policy engine. |

## Developer experience

| Gap | Peer reference | Why it matters | Cost |
|---|---|---|---|
| **Slash commands / user-defined workflow shortcuts** | Claude Code (`.claude/commands/*.md`) | We ship 24 `axi ext` verbs; users can't easily define their own workflow macros. **Partial (2026-05-01, T1.6):** chat REPL now has the slash-palette UX — `ChatCompleter` with descriptions + filter, arg-completion for `/model` and `/resume`, `@file` PathCompleter, `!bash` escape, Tab-queue-after-turn, multi-line parity. User-defined macro file pattern (`.axi/commands/*.md`) still pending. | Small — scan a dir, wire to CLI. |
| **Settings hierarchy** (user > project > local override) | Claude Code, Cursor | `$AXIOM_HOME/config/` is per-extension; no platform-level hierarchy. | Small — resolve cascade. |
| **Visual studio / playground** (live graph, state inspector, trace replay) | Mastra Studio, LangGraph Studio | Big instructor-demo differentiator for the Prague classroom audience. | Large — new surface. |
| **Diff review UI for interactive edits** | Claude Code, Cursor Composer | When an agent edits files, human sees + approves the diff. *Note: REV-U Phase 1 (PR #108, 2026-05-02) ships CLI-native PR review with cited evidence — adjacent surface but the **edit-side** approval flow is still the gap here.* | Medium — requires agent-edit protocol. |
| **Prompt libraries** (reusable, user-editable templates exposed) | Claude Code custom commands, Cursor rules | `PromptComposer` is internal; users can't author reusable system-prompt blocks. | Small — file-based contrib surface. |
| **Multi-modal inputs** (images, PDFs in chat) | All of them | Chat is text-only today. | Medium — gateway + ingestion. |

## Agent proactivity

| Gap | Peer reference | Why it matters | Cost |
|---|---|---|---|
| **Cadence loops / scheduled agents** | Claude Code (cron/schedule skill), Mastra | SCAN's persona includes cadence mode; the mechanism to "run this every 6 hours" isn't exposed to user-built extensions. **Partial (2026-05-02):** harness has `RemoteTrigger`-backed cloud routines (one-time + cron) usable from any session; RIVET now durably tracks them across sessions (PR #107). Manifest-declared `[[agent.cadence]]` for user-built extensions still pending. | Medium — scheduler primitive. |
| **Event-driven triggers** (webhooks, file watchers, queue consumers) | Mastra, LangGraph | Extensions can observe; they can't react to external events without custom code. | Medium — trigger abstraction. |
| **Background tasks** (runs while user works elsewhere) | Claude Code | User-facing agent blocks the REPL today. **Partial (2026-05-02):** cloud routines run agents in Anthropic-hosted CCR sessions out-of-process; session-watcher (Monitor) wakes the REPL on events. In-REPL non-blocking agents (true background while user keeps typing) still pending. | Medium — session-model change. |

## Connectors

The pattern is missing, not the integrations. A proper connector shape = OAuth + token vault + rate-limit/retry + consistent MCP surface + provenance stamp. Shipping one-off integrations without this shape is what competitors do badly.

| Family | Targets | Notes |
|---|---|---|
| Messaging | Slack, Microsoft Teams, Discord | SMTP email exists; push-notification adapters noted as pending in memory. **2026-05-02 framing:** outbound is the load-bearing piece — agents need *presence/voice* in channels, not just inbound watchers. Pattern dependencies: outbound auth (bot tokens vs delegated), channel resolution, capability tokens for delegated posting. |
| Code forges | GitHub, GitLab | GitLab-primary per project convention. |
| Issue trackers | Linear, Jira | Linear is reserved for Soilmetrix per memory; we use GitLab issues. |
| Docs | Notion, Confluence, Google Drive, Dropbox | Prague classroom use case needs Drive at minimum. |
| Calendars | Google Calendar, Outlook | |
| Design | Figma | Low priority. |
| Databases | Postgres, SQLite, DuckDB | Postgres is the operational backbone. |
| Web | Playwright browser, search APIs | |

## Deployment / ops

| Gap | Peer reference | Why it matters | Cost |
|---|---|---|---|
| **One-command deploy** (`axi ext deploy <target>`) | Mastra (`mastra deploy`), Vercel for agents | AEOS §10.3 lists `axi ext deploy` as Tier 3. | Medium. |
| **Rate limits + retries for LLM calls** (production-grade resilience) | OpenAI Agents, LangGraph | Gateway handles routing; retry/backoff is ad-hoc per call site. | Small. |
| **Graceful degradation / error boundaries** (typed fallback on tool failure) | LangGraph | When a tool fails mid-chain, recovery is bespoke. | Medium. |

## Gaps surfaced during Tier 1c migrations

*Each migration may surface a gap vs. peer harnesses. Log them here with the commit that revealed them.*

- 2026-04-24 — `dfib_agent → diagnostics` migration: `axi ext migrate` tool produces compound double-nest and mechanically strips `_agent`. Peer harnesses' migrators (none have this specific tool) aren't really comparable, but the tool should do more of the work than it currently does. Tracked in the Tier 1c migration tracker's "discovered gaps" section.
- 2026-04-24 — `eve_agent → signals` migration revealed that SCAN's `[[agent.watchers]]` declarative watcher loop has no peer-equivalent in mainstream harnesses (Mastra and LangGraph have triggers but no built-in heartbeat scheduler tied to manifest declarations). It's a differentiator, but the AEOS schema doesn't yet describe it — see the migration tracker for the deferred capability translation.
- 2026-04-24 — `classroom/` AEOS pass: the runtime reads `[chat_tools]` (chat-tool discovery in `axiom.extensions.discovery.load_chat_tools`) and `[mcp_servers.*]` (MCP server generation in `axiom.extensions.mcp_generation`). Both are pre-AEOS bridge blocks retained transitionally; the AEOS 0.1 schema relaxes `additionalProperties = true` (commit e760bab) so they parse, but they aren't expressible as `[[extension.provides]]` blocks today. Peer harnesses: MCP server registration is roughly parallel to Mastra's agent-tool exposure but with stricter manifest declarations. Translation = (a) extend AEOS schema with `chat_tool` + `mcp_server` capability kinds, (b) update the discovery + mcp_generation runtime to read from `[[extension.provides]]`, (c) re-tighten `additionalProperties` to `false` once all extensions are converted. Cost: ~half-day for schema + runtime + sweep across the ~5 extensions still using the legacy blocks.
- 2026-04-24 — `classroom/` migration didn't touch `agents/chalke/instructor_skills.md` + `student_skills.md` + `coordination.md` — those describe CHALKE's dual-perspective skill split but pre-date the AEOS canonical `skills/<name>/SKILL.md` form. Translation to canonical SKILL.md requires deciding whether each is a separate skill (3 SKILL.md files) or a single dual-perspective skill (1 SKILL.md with sub-sections). Cost: ~1-2 hours once the form is decided. Peer harnesses don't have a direct equivalent — most agent frameworks treat all skills as flat tool registries; CHALKE's perspective-aware skill routing is an Axiom differentiator worth keeping.

## Closed / partial since 2026-04-24

| Item | Status | Shipping ref | Remaining |
|---|---|---|---|
| Slash-command palette UX in chat REPL | **Partial** | PR #102+ (Tranche 1.6, 2026-05-01) | User-defined macro file pattern (`.axi/commands/*.md`) |
| Per-tool allow/deny/ask permissions (chat session scope) | **Partial** | PR #102+ (Tranche 1.3, 2026-05-01) | Per-principal granularity; persistence across sessions |
| Cloud-routine scheduling (`RemoteTrigger`) | **Partial** | This session, 2026-05-02 — usable from any session | Manifest-declared `[[agent.cadence]]` for user-built extensions |
| Background tasks via cloud routines | **Partial** | PR #107 RIVET watcher, 2026-05-02 — durable cross-session tracking | True non-blocking in-REPL agents |
| Friendly error mapper + secret redaction at error sites | **Partial** | PR #102+ (Tranche 1.7, 2026-05-01) | Not in original gap list, surfaced during the audit; secret redaction promoted to T1 from T2/C2 |
| Plan-mode hard-strips tools at API call | **Closed** | PR #102+ (Tranche 1.2, 2026-05-01) | — |
| First-run no-provider guard with friendly hint | **Closed** | PR #102+ (Tranche 1.1, 2026-05-01) | — |

## Differentiators shipped 2026-05-02 (no peer parity to chase)

These widen the moat rather than close a gap. Recording them here so the gap doc stays an honest signal of *trailing*, not a hidden roadmap.

- **REV-U Phase 1** (PR #108) — CLI-native PR review with 5 specialized passes (correctness/perf/security/docs/tests), validator gate against diff-line membership, severity-tagged terminal report. Closest peer is GitHub Copilot's PR review, which is GitHub-only and lacks the validator step. *Future Phase 6 Linus-mode retraction is wide-open SOTA gap.*
- **TIDY stale-worktree skill** (PR #109) — `axi tidy worktrees [--prune]` with cited evidence (S1 missing / S2 origin-deleted / S3 ancestor-of-main / S4 PR-merged). No peer harness has anything like this; pure hygiene differentiator.
- **RIVET cloud-routine watcher** (PR #107) — durable cross-session tracking of `RemoteTrigger` routines with state-transition logging into RIVET's heartbeat ledger. No peer has the lifecycle-vs-hygiene split (RIVET vs TIDY); this is the lifecycle eye.

## Surfaces not in this doc

- **Scientific displays** (`src/axiom/extensions/builtins/scidisplay/` is a stub today). Not a peer-parity gap — none of the peer harnesses do scientific rendering well. Tracked as a NeutronOS / Keplo *pull*, not a parity gap. PRD pending.

---

## How to use this list

- Adding: write the gap with the nearest peer that does it better and a cost read. Don't add gaps without a named peer — "we should have X because it'd be cool" isn't a gap.
- Removing: when the feature ships, move it to a "Closed" section with the shipping commit.
- Grooming: reread quarterly. Some entries will stale out as the peer landscape moves.
