AXF

Fit the repository once. Let every agent follow the same paved path.

An agent can read your code. It still has to rediscover how this repository wants to be built, tested, searched, diagnosed, and operated. The clues are usually scattered across scripts, package tasks, prose, CI, and human memory.

AXF (Agent eXoskeleton Framework) turns that repeated local ceremony into small, self-describing capabilities. Fit the exoskeleton deliberately once; later agents can discover the right route, inspect its contract, and run it without rebuilding the procedure from scratch.

recurring repository ceremony
          ↓ fit once
inspectable AXF capabilities
          ↓ reuse
agent discovers → inspects → runs

AXF is a traffic cop, not a replacement vocabulary. It preserves a provider's existing command family by default, then projects or normalizes only the parts that need a clearer agent-facing contract. The goal is not to automate judgment. It is to spend less judgment on reconstructing the same route.

The five caller concepts

You do not need the framework vocabulary to use a fitted repository:

• Workspace — the repository context whose operating paths you need. In root-sensitive contracts, AXF distinguishes the project root used for discovery from the execution root used as the runtime working directory.
• Module — a reusable capability pack, such as the built-in echo module or a repository-owned validation pack.
• Capability — one named operation with declared arguments, output modes, side effects, lifecycle, policies, and an execution target.
• Inspect — read the complete contract before execution.
• Run — execute through that contract after checking its effects and authority requirements.

The smallest proof of life is:

npm install --global @smartergpt/axf
axf doctor
axf list --compact
axf inspect echo say
axf run echo say --message hello

AXF 2.1.3 is published under Apache-2.0; earlier npm releases retain their published terms. Outside a fitted workspace, with no root override, this example discovers the bundled manifests in the installed package. doctor reports that project root separately from the current execution directory. An explicit AXF_PROJECT_ROOT overrides discovery; an empty directory without an axf.workspace.json marker has no capabilities. A fitted repository normally adds its own capabilities; echo.say only proves that the registry, resolver, adapter, and executor are connected.

Before and after fitting

Before AXF, a new agent searches multiple instruction files, reverse-engineers package scripts, guesses the safe validation subset, and repeats that work in the next session.

After a deliberate fit, the repository can expose stable entries such as context, check, and handoff. A caller starts with axf guide, inspects the selected capability, and runs the repository-owned route. AXF makes the route visible; the repository still owns it.

Is this repository a fit?

AXF helps when:

• agents repeatedly guess which build, test, or validation command applies;
• the same repository facts must be rediscovered before editing;
• local safety rules live in scattered prose, convention, or human memory;
• brittle shell chains keep being rebuilt for repo-specific chores.

AXF is probably not a fit when one obvious command already covers the work, the ceremony is unlikely to recur, or the provider surface changes faster than the team can maintain a capability contract.

The adoption question is:

Does this repository have repeated local operating ceremony that is worth fitting once into stable, inspectable agent capabilities?

For a bounded, strictly read-only assessment, give an agent this prompt:

Evaluate whether this repository is a fit for AXF by following
docs/agent-evaluation.md. Do not install AXF, edit files, scaffold or promote
capabilities, invoke MCP tools, or run repository code. Inspect only the
existing scripts, package tasks, documentation, agent instructions, CI and
platform/runtime constraints. Identify repeated mistakes and existing overlap,
then return exactly one verdict: adopt, pilot, defer, or not a fit. Include the
evidence, expected fitting cost, ongoing drift cost, authority boundaries, and
the smallest reversible pilot. Do not perform the pilot without separate
approval.

See Agent fit evaluation for the evidence checklist, verdict definitions, and response template.

Choose your path

Stop at the caller guide unless you are responsible for fitting a provider or changing AXF itself. The complete audience map is in Documentation layers.

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.

What AXF is not

AXF is not a universal command catalog, a source of authorization, a replacement for provider identity, a substitute for review, or an MCP-only product. MCP is one agent-facing surface over the same registry and execution path.

Install and MCP

License

AXF is licensed under the Apache License, Version 2.0, including commercial and organizational use under its terms. Preserve the applicable notices. Earlier releases retain their applicable terms.

SmarterGPT was founded by Joseph Gustavson (Guffawaffle). See stewardship, contributing, and project identity. Code licensing does not grant runtime authority.

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

Audit a Codex MCP package pin before assuming the configured server matches the installed CLI:

axf integrate codex --check
axf integrate codex --write
axf integrate codex --check --smoke

Writes are scoped to the AXF package spec in Codex config.toml; restart or reopen Codex afterward. For one-call AXF + Lex bootstrap, including the explicit off | shadow KnowledgeFrame provider rollout, see the packaged templates/session-context workspace recipe and docs/13-repo-onboarding.md.

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/project",
      "env": {
        "AXF_PROJECT_ROOT": "/path/to/project",
        "AXF_EXECUTION_ROOT": "/path/to/project"
      }
    }
  }
}

Direct-bin configs remain valid:

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

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-project",
      "env": {
        "AXF_PROJECT_ROOT": "C:\\src\\my-project",
        "AXF_EXECUTION_ROOT": "C:\\src\\my-project"
      }
    }
  }
}

Direct-bin .cmd configs are still valid:

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

WSL / Linux launch

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