Skip to content

AXM Logo

axm-forge

Developer tools for the AXM ecosystem — AST introspection, code auditing, project scaffolding, and git automation.

CI axm-audit axm-init Coverage Python 3.12+ License

Philosophy

AXM Forge provides the developer toolchain for the AXM ecosystem. Every tool returns structured, deterministic results — designed for AI agents that need precise answers, not text to parse.

  • Automated Scaffolding

    Generate projects, workspaces, and workspace members that pass all 39 governance checks from day one. Copier templates encode AXM conventions so every new package starts production-ready.

  • Codified Quality Gates

    40+ rules covering lint, types, coverage, complexity, security, and project governance — all in a single verify() call. Scores and grades make quality measurable and comparable.

  • AST-Powered Introspection

    Tree-sitter based analysis that understands Python at the structural level. Find callers, measure blast radius, and trace import graphs — all without grep noise. Every query returns precise, semantic results.

  • Git Workflow Automation

    Structured commits with auto-staging, commit-hook retry, and conventional commit enforcement. Semver tagging and push — all through agent-friendly MCP tools.

  • Atomic Batch Editing

    Replace, create, and delete across dozens of files in a single transactional call. No partial writes, no half-applied refactors — it all lands or none of it does.

  • CST-Based Refactoring

    Move, rename, split, and merge symbols across a codebase without breaking a single import. Concrete syntax trees keep every reference in sync.

  • Token Compaction

    Deterministic strategies to shrink LLM inputs — whitespace collapse, null stripping, table compaction, deduplication — with presets from safe to aggressive. Fit more context, spend fewer tokens.

  • Neural Similarity Detection

    Embed code symbols and cluster intent-equivalent duplicates across packages, or retrieve the public symbols closest to a free-form intention before writing new code. Catches reuse opportunities that token- and AST-level tools miss.

Workspace Packages

Package Description Version Quality
axm AXM CLI — thin autodiscovery wrapper for the ecosystem PyPI audit cov
axm-mcp MCP Server — runtime tool discovery and execution PyPI audit cov
axm-init Python project scaffolding CLI with Copier templates PyPI audit cov
axm-audit Code auditing and quality rules for Python projects PyPI audit cov
axm-ast AST introspection CLI for AI agents, powered by tree-sitter PyPI audit cov
axm-git Git workflow automation for AXM agents PyPI audit cov
axm-edit Atomic batch file editing for AI agents PyPI audit cov
axm-anvil Deterministic CST-based refactoring toolkit — move, rename, split, merge symbols atomically PyPI audit cov
axm-smelt Deterministic token compaction for LLM inputs PyPI audit cov
axm-echo Neural similarity detection — cross-package dedup and upstream-reuse retrieval PyPI audit cov
axm-ingot Shared helper library — common code factored out and tested once, reused across packages PyPI audit cov

Quick Start

Using the tools (via MCP)

Connect the whole AXM toolchain to your MCP client (Claude Code, IDE…) in one command — uvx fetches it on demand, no manual install:

Bash
claude mcp add --scope user axm-mcp -- uvx --python 3.12 --from "axm-mcp[all]@latest" axm-mcp

This exposes verify, audit, the ast_* family, git_commit, batch_edit, and the rest as MCP tools. See the axm-mcp Quick Start for the .mcp.json form and the advanced persistent-HTTP setup.

Developing the workspace

Bash
# Install the workspace
uv sync --all-groups

# Run all tests
make test-all

# Lint + type check
make lint

# Full AXM quality gate (pre-push)
make quality

Architecture

%%{ init: { "flowchart": { "defaultRenderer": "elk" } } }%%
graph TD
    classDef ast fill:#5C6BC0,stroke:#3949AB,color:#fff
    classDef audit fill:#42A5F5,stroke:#1E88E5,color:#fff
    classDef init fill:#26C6DA,stroke:#00ACC1,color:#fff
    classDef git fill:#78909C,stroke:#546E7A,color:#fff
    classDef smelt fill:#FFA726,stroke:#FB8C00,color:#fff
    classDef anvil fill:#EF5350,stroke:#E53935,color:#fff
    classDef edit fill:#AB47BC,stroke:#8E24AA,color:#fff
    classDef axm fill:#66BB6A,stroke:#43A047,color:#fff
    classDef mcp fill:#8D6E63,stroke:#6D4C41,color:#fff
    classDef ingot fill:#BDBDBD,stroke:#757575,color:#000
    classDef echo fill:#EC407A,stroke:#D81B60,color:#fff

    subgraph tools [Tools]
        direction TB

        AUDIT["axm-audit<br/>Code auditing"]:::audit
        ANVIL["axm-anvil<br/>CST refactoring"]:::anvil

        subgraph botrow [ ]
            direction LR
            AST["axm-ast<br/>AST introspection"]:::ast
            EDIT["axm-edit<br/>Batch file editing"]:::edit
            INIT["axm-init<br/>Scaffolding"]:::init
            GIT["axm-git<br/>Git automation"]:::git
            SMELT["axm-smelt<br/>Token compaction"]:::smelt
            ECHO["axm-echo<br/>Neural similarity"]:::echo
        end

        AUDIT --> AST
        AUDIT --> ANVIL
        AUDIT --> ECHO
        ANVIL --> EDIT
        ECHO --> AST
    end

    subgraph foundations [Foundations]
        direction TB
        subgraph baserow [ ]
            direction LR
            MCP["axm-mcp<br/>MCP Server"]:::mcp
            AXM["axm<br/>Core SDK + ToolResult"]:::axm
            INGOT["axm-ingot<br/>Shared helper library"]:::ingot
        end
    end

    %% the whole tool layer builds on the shared foundations
    %% (target a node inside baserow so ELK fills + aligns that row)
    tools --> AXM

    %% hide the inner row containers (keep only Tools / Foundations frames)
    style botrow fill:none,stroke:none
    style baserow fill:none,stroke:none

Learn More