AXF

Agent eXoskeleton Framework for workspace-native agent capabilities.

AXF (Agent eXoskeleton Framework) gives teams a framework for building workspace-native agent exoskeletons: small, self-describing capabilities that encode how each codebase is built, tested, searched, diagnosed, and operated safely.

The goal is not to automate judgment. The goal is to compress repeated local ceremony into reliable workspace capabilities, so agents can spend more attention on the actual problem.

When AXF helps

• agents keep guessing which build, test, or validation command applies
• agents repeatedly search for the same repo facts before editing
• local safety rules live in prose, convention, or human memory
• brittle shell chains keep getting rebuilt for repo-specific chores

AXF is not

AXF is not a universal command catalog, a replacement for judgment, or an MCP-only product. It is the framework and control plane for building workspace-native agent exoskeletons from workspace-owned capabilities. MCP is one adapter surface; workspaces own the repo-specific capabilities agents use as their local exoskeleton.

Status: alpha. The core loop is in place: scout, inspect, execute, scaffold, and promote capabilities through one contract. Manifest version axf/v0 is the current alpha contract.

Install and MCP

License

This repository is source-available, not open source.

You may view, fork, modify, and run this project for personal, non-commercial use under the SmarterGPT Source-Available Personal Use License.

Commercial use, organizational use, employer/client use, production use, hosted-service use, redistribution, sublicensing, or embedding in another product or platform requires a separate written license from Joseph Gustavson / Guffawaffle / SmarterGPT.

Public visibility on GitHub does not grant open-source rights or business-use rights.

The npm package name is @smartergpt/axf. It installs two bins:

• axf — the CLI entrypoint, including the stdio MCP launch subcommand axf mcp
• axf-mcp — the stdio MCP server entrypoint

MCP clients may launch axf-mcp directly. For registry-driven or package-driven launch, prefer axf mcp so the package can stay centered on the base axf command surface. Both entrypoints start the same stdio MCP server. The server exposes exactly one MCP tool named axf, and that tool routes into AXF's existing capability surface for the bound workspace.

Global install

npm install --global @smartergpt/axf

Then use either bin directly:

axf doctor
axf mcp
axf-mcp

Repo-local dev launch

From a local clone, run the bins directly with Node:

node /path/to/axf/bin/axf.js doctor
node /path/to/axf/bin/axf.js mcp
node /path/to/axf/bin/axf-mcp.js

A repo-local MCP configuration can either call the direct MCP bin or the CLI subcommand. Prefer the CLI subcommand when the client supports command arguments cleanly:

{
  "mcpServers": {
    "axf": {
      "command": "node",
      "args": ["/path/to/axf/bin/axf.js", "mcp"],
      "cwd": "/path/to/workspace",
      "env": {
        "AXF_WORKSPACE": "/path/to/workspace"
      }
    }
  }
}

Direct-bin configs remain valid:

{
  "mcpServers": {
    "axf": {
      "command": "node",
      "args": ["/path/to/axf/bin/axf-mcp.js"],
      "cwd": "/path/to/workspace",
      "env": {
        "AXF_WORKSPACE": "/path/to/workspace"
      }
    }
  }
}

npm / npx launch

Published-package smoke tests must run from a clean directory such as /tmp, not from the AXF repo root. Running from the repo root can let npx or npm exec pick up a repo-local or globally installed axf binary instead of the package-installed one.

The registry-friendly launch shape is axf mcp, but the direct MCP bin remains valid for manual configurations. These equivalent package-driven forms use the published npm package:

npx -y --package @smartergpt/axf axf doctor
npx -y --package @smartergpt/axf axf mcp
npx -y --package @smartergpt/axf axf-mcp

npm exec --yes --package @smartergpt/axf -- axf doctor
npm exec --yes --package @smartergpt/axf -- axf mcp
npm exec --yes --package @smartergpt/axf -- axf-mcp

Windows-native launch

For registry-style Windows MCP configs, prefer the base axf.cmd launcher with mcp as an argument:

{
  "mcpServers": {
    "axf": {
      "command": "axf.cmd",
      "args": ["mcp"],
      "cwd": "C:\\src\\my-workspace",
      "env": {
        "AXF_WORKSPACE": "C:\\src\\my-workspace"
      }
    }
  }
}

Direct-bin .cmd configs are still valid:

{
  "mcpServers": {
    "axf": {
      "command": "axf-mcp.cmd",
      "args": [],
      "cwd": "C:\\src\\my-workspace",
      "env": {
        "AXF_WORKSPACE": "C:\\src\\my-workspace"
      }
    }
  }
}

WSL / Linux launch

For registry-style WSL/Linux MCP configs, prefer the base axf command with mcp as the first argument:

{
  "mcpServers": {
    "axf": {
      "command": "axf",
      "args": ["mcp"],
      "cwd": "/home/user/src/my-workspace",
      "env": {
        "AXF_WORKSPACE": "/home/user/src/my-workspace"
      }
    }
  }
}

Direct-bin configs remain valid:

{
  "mcpServers": {
    "axf": {
      "command": "axf-mcp",
      "args": [],
      "cwd": "/home/user/src/my-workspace",
      "env": {
        "AXF_WORKSPACE": "/home/user/src/my-workspace"
      }
    }
  }
}

WSL users should use a native WSL AXF install on PATH, not Windows npm shims or npm's _npx cache. AXF's global.lex.* capabilities launch the package-local Lex dependency, but direct Lex usage should follow the same native WSL rule. See WSL Native Lex Install for the recommended user-local install, checkout symlink bridge, and native SQLite build requirements.

Workspace binding

axf, axf mcp, and axf-mcp find the active workspace in this order:

1. explicit --workspace
2. AXF_WORKSPACE
3. nearest axf.workspace.json from cwd
4. nearest axf.workspace.json from the installed script location
5. cwd fallback

For MCP clients, set both cwd and AXF_WORKSPACE to the intended workspace when possible. That makes the exposed command surface deterministic and keeps workspace-relative execution targets anchored to the right repo.

From any directory once installed:

axf doctor
axf list
axf inspect echo say
axf run echo say --message hello
axf scout --check
axf run toy echo say --message hello
axf init capability global.acme.status

axf doctor reports the workspace source it selected and, under WSL, warns when axf, lex, node, or npm resolve through Windows PATH entries under /mnt/c/....

MCP routing and governance

The MCP server exposes one tool named axf. Supported operations are:

• help
• list
• inspect
• run
• doctor
• scout_check

Those operations route into AXF's manifest-backed discovery, resolver, lifecycle, policy, adapter, and executor paths. MCP does not add a second governance model or a raw shell bypass around AXF.

AXF MCP is intentionally not full CLI parity yet. The CLI remains the authoritative mutation and control plane for commands such as init, promote, demote, scout --write, and other registry/materialization flows.

Capabilities such as global.lex.status and global.echo.say are not separate MCP tools. Use operation=help to learn the router contract, operation=list to discover capabilities, and operation=inspect before operation=run. Treat capability lifecycleState, sideEffects, policies, and workspace binding as part of the execution contract.

scout_check is AXF's MCP-specific read-only structured scout diagnostics surface. It is not intended to promise literal CLI parity with axf scout --check.

Registry and manifest updates still happen through normal AXF CLI and filesystem/control-plane flows. The MCP server reloads registry state per request, so external AXF updates become visible on later MCP calls without restarting the server.

Full CLI parity may be considered later behind explicit policy and approval gates.

Lex appears through AXF only when the bound AXF workspace discovers or mounts Lex capabilities such as global.lex.* or toolspace.ops.lex.*.

What's wired up

Built-in adapters

AXF ships two public built-in adapter types:

• internal — runs handlers in-process (adapters/internal/)
• cli — generic subprocess dispatcher with stdout JSON parsing (adapters/cli/)

The standard Lex capability family uses the generic cli adapter. It does not require a dedicated Lex adapter. AXF depends on @smartergpt/lex at runtime and launches the package-local Lex CLI through Node, so global.lex.* does not depend on an ambient lex shim on PATH.

Built-in capabilities

Lex is a reference capability family routed by AXF. It demonstrates how workspace-native memory and policy capabilities can sit behind AXF's resolver, lifecycle, policy, adapter, and executor path without defining the framework itself.

Toolspaces

• toy — smallest mount example; re-mounts echo.say with a local default
• ops — multi-capability mount example for grouped launch surfaces, including the reusable read-only Lex pack

Repo onboarding

The recommended repo flow is:

1. Add axf.workspace.json at the repo root so workspace binding is explicit.
2. Reuse the imported global.lex.* family or mount the read-only Lex pack into a toolspace.
3. Add repo-specific capabilities separately under manifests/capabilities/ or manifests/families/.
4. Keep MCP optional; AXF works as a plain CLI capability router without it.
5. Mark mutating capabilities with sideEffects: "write". AXF does not yet have a first-class approvalRequired field, so approval gates stay a repo policy or review convention for now.

See docs/13-repo-onboarding.md for a concrete pattern including Lex mounts and WSL/Windows notes.

How to add a new provider

The contract is open. Every new provider goes through the same scaffolders and lifecycle gates:

# 1. Scaffold a draft provider adapter (only if the provider has an
#    envelope or quirks the generic cli adapter shouldn't carry):
axf init adapter --kind provider acme --composes cli

# 2. Scaffold each capability:
axf init capability global.acme.status

# 3. Edit the drafts, then:
axf doctor
axf run acme status --any-lifecycle

The four canonical prompts under prompts/ walk an agent through discovery → planning → scaffolding → review against the actual file contract. JSON-first providers can usually use the generic cli adapter directly; provider adapters are for wrappers that need envelope, error, or argument normalization beyond the generic route.

Layout

axf.workspace.json               # workspace marker
bin/axf.js                      # CLI entrypoint
src/cli/                        # CLI parsing + main dispatch
src/core/                       # registry, resolver, executor, adapters, doctor, policy
adapters/<type>/                # type adapters (internal, cli, ...)
adapters/<provider>/            # optional provider adapters for wrapped CLIs
manifests/capabilities/         # capability manifests
manifests/toolspaces/           # toolspace mount manifests
prompts/                        # canonical prompts for agent-authored adapters
docs/                           # architecture, contract, lifecycle, prompts
test/                           # node:test suite

Reading order

1. docs/00-foundation.md — why axf exists
2. docs/01-vocabulary.md
3. docs/02-architecture.md
4. docs/03-capabilities-and-manifests.md
5. docs/04-adapter-contract.md — the two-kind adapter model (type + provider)
6. docs/05-lifecycle-and-promotion.md
7. docs/06-canonical-prompts.md
8. docs/07-v0-bootstrap-plan.md — alpha implementation milestones
9. docs/08-adapter-folder-shape.md — the concrete file contract
10. docs/09-launch-plans.md — interpreter-aware launch plans, env-bound roots, fallback paths
11. docs/10-command-families.md — family imports, public-to-provider arg mapping, materialization, drift
12. docs/11-normalization-guidance.md — JSON-first vs text-first providers, when to write a provider adapter
13. docs/12-layered-docs.md — caller / integrator / author paths through the docs
14. docs/13-repo-onboarding.md — workspace markers, standard Lex capabilities, and platform guidance

Tests

npm test

Uses Node's built-in node:test; no external test runner is required.

What is intentionally not here

• a broad command-alias layer
• privileged integration paths
• a plugin marketplace
• mandatory remote execution or MCP support
• agent-generated capabilities that auto-promote