axm 0.8.0

AXM CLI — Unified command-line interface for the AXM ecosystem

Features

• 🔌 Autodiscovery — automatically finds commands from installed AXM packages via entry points
• 🧩 Modular — install only what you need (axm[init], axm[audit], axm[bib], axm[mcp])
• 🛠️ Shared interface — re-exports the core contracts from the package root (from axm import AXMTool, ToolResult, HookAction, HookResult, WitnessResult, ValidationFeedback, WitnessRule, tool_node, tool_metadata, ToolMetadata, ToolNodeError): AXMTool/ToolResult (with optional agent_hint for LLM-optimized descriptions and text for pre-rendered output), HookAction/HookResult, WitnessResult/ValidationFeedback/WitnessRule, and tool_node (adapt any axm.tools tool into a DAG python-node) for ecosystem development
• 📦 Minimal — only depends on cyclopts, everything else is optional

Installation

uv add axm              # CLI shell only
uv add axm[init]        # + scaffolding & project checks
uv add axm[audit]       # + code quality audits
uv add axm[bib]         # + bibliography tools
uv add axm[mcp]         # + MCP server (for AI agents)
uv add axm[all]         # everything

pip install axm              # CLI shell only
pip install axm[init]        # + scaffolding & project checks
pip install axm[audit]       # + code quality audits
pip install axm[bib]         # + bibliography tools
pip install axm[mcp]         # + MCP server (for AI agents)
pip install axm[all]         # everything

Usage

axm                          # shows available commands
axm init_scaffold my-project # if axm-init is installed
axm init_check .             # check project conformity
axm audit .                  # if axm-audit is installed

How It Works

Each AXM package declares commands via pyproject.toml:

# axm-init/pyproject.toml
[project.entry-points."axm.commands"]
init_scaffold = "axm_init.cli:scaffold"
init_check    = "axm_init.cli:check"
init_reserve  = "axm_init.cli:reserve"

The axm CLI discovers these from entry-point metadata and dispatches lazily — it imports only the command you invoke, not every tool at startup.

Package Structure

axm/
├── src/axm/
│   ├── cli.py            # Lazy, dispatch-first autodiscovery wrapper
│   ├── hooks/
│   │   ├── base.py       # HookAction Protocol + HookResult (lifecycle hooks)
│   │   └── __init__.py
│   ├── tools/
│   │   ├── base.py       # AXMTool Protocol + ToolResult + ToolMetadata
│   │   ├── node.py       # tool_node adapter + ToolNodeError (AXMTool → DAG node)
│   │   ├── _discovery.py # entry-point metadata helper
│   │   └── __init__.py
│   ├── witnesses.py      # WitnessResult + ValidationFeedback + WitnessRule
│   └── __init__.py
└── tests/
    ├── unit/             # mirrors src/ (hooks/, tools/, cli, witnesses, __init__)
    └── e2e/              # CLI invoked as a subprocess (test_axm.py)

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm --directory packages/axm pytest

License

Apache-2.0 — © 2026 Gabriel Jarry