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 --pac

... [View full README on GitHub](https://github.com/guffawaffle/ax-framework#readme)