AXF

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.5 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:

{

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

Direct-bin configs remain valid:

{

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

WSL users should use a native WSL AXF install on PATH, not Windows npm shims or npm's _npx cache. Optional shared packs that launch native CLIs should follow the same rule: prefer Linux-native tools earlier on PATH and avoid crossing into Windows shims from WSL.

Root binding

axf, axf mcp, and axf-mcp resolve the active project root and execution root in this order:

1. explicit --project-root and --execution-root
2. AXF_PROJECT_ROOT and AXF_EXECUTION_ROOT
3. legacy CLI aliases: --workspace, --registry-workspace, --execution-workspace
4. legacy environment aliases: AXF_WORKSPACE, AXF_REGISTRY_WORKSPACE, AXF_EXECUTION_WORKSPACE
5. nearest axf.workspace.json from cwd
6. nearest axf.workspace.json from the installed script location
7. cwd fallback

For axf run, unprefixed root flags are global only before the subcommand; after run they are capability-owned. Non-run commands retain their legacy placement because they have no downstream argument owner. The --axf-project-root, --axf-execution-root, and --axf-workspace spellings are accepted later in the AXF-controlled portion of a command. After an axf run ... -- boundary, root-like names belong to the capability.

Run argument ownership

AXF reserves the --axf-* namespace for framework controls and leaves natural public argument names to capabilities. Use an explicit boundary when the ownership should be visible in the command itself:

ax