Developer tools and the SDK that connects them.
AXM Forge is a uv workspace of independently versioned Python packages for
code analysis, quality checks, editing, scaffolding and Git operations.
Use the tools through an MCP client or the generic axm CLI; use the
libraries directly when integrating them into Python applications.
| You want to… | Start here |
|---|---|
| Understand a project or find a symbol | axm-ast: ast_context, ast_search, ast_inspect |
| Audit a package or run its tests | axm-audit: audit, audit_test |
| Combine audit and governance checks over MCP | axm-mcp: verify |
| Validate and apply a batch of edits | axm-edit: batch_edit, batch_rollback |
| Move, rename or extract Python symbols | axm-anvil: anvil_move, anvil_rename, anvil_extract |
| Scaffold a project and check its conventions | axm-init: init_scaffold, init_check |
| Review repository state and commit changes | axm-git: git_preflight, git_commit |
| Find duplicate code or possible reuse | axm-echo: echo_code, echo_check |
| Reduce text size or count tokens | axm-smelt: smelt, smelt_count |
Check each tool's result and documented limits. A successful invocation does not necessarily mean a passing audit or test suite. Batch editing uses validation and rollback, but does not provide a filesystem-wide transaction. Similarity scores identify candidates for review, not proof of equivalent behavior.
The workspace root is development infrastructure; install the packages you need.
| Package | Role | Release | Quality |
|---|---|---|---|
| axm | Core SDK (AXMTool, ToolResult, tool_node) and generic CLI |    |
|
| axm-mcp | MCP server, tool catalog, facade and transports |    |
|
| axm-ast | Read-only structural analysis with tree-sitter |    |
|
| axm-anvil | Python symbol move, rename and extraction |    |
|
| axm-edit | Batch edits, checkpoints and filesystem tools |    |
|
| axm-audit | Quality rules, test execution and test refactoring |    |
|
| axm-init | Scaffolding and project governance checks |    |
|
| axm-git | Git commits, branches, worktrees and release operations |    |
|
| axm-echo | Code similarity and reuse-candidate retrieval |    |
|
| axm-smelt | Text compaction and token measurement |    |
|
| axm-ingot | Dependency-free shared Python helpers |    |
|
| axm-config | Non-sensitive configuration and runtime paths |    |
|
| axm-vault | Credential catalog and secret resolution |    |
|
| axm-doctor | Environment/bootstrap and authentication diagnostics |    |
Both transports are supported:
- stdio is the simplest first installation: the client starts and stops its own server process. The configuration below uses this mode.
- Streamable HTTP suits a persistent server used by several clients.
Start it with
axm-mcp serveand connect clients to/mcp; follow the HTTP setup guide.
Running axm-mcp without a subcommand still selects stdio.
With Python 3.12+ and uv installed, configure your MCP client to start this stdio server process:
{
"command": "uvx",
"args": ["--python", "3.12", "--from", "axm-mcp[forge]", "axm-mcp"]
}The enclosing configuration and its scope depend on your client.
The forge extra installs the main developer-tool packages; it is not a
promise to install every package in this repository. all additionally
includes bibliography and ticket packages from other workspaces. Pin versions
for reproducible environments.
The default facade exposes discovery and dispatch tools alongside selected
direct tools. Use axm_search, axm_describe and axm_call to reach
the installed catalog. The server and tool providers must share one Python
environment. Follow the MCP quick start
for a verified discovery/call sequence and HTTP setup.
This example installs axm and the AST provider into a temporary uv tool environment, then prints help without analysing a project:
uvx --with axm-ast --from axm axm ast_context --helpPackage names and executable names are not interchangeable:
axm-audit, axm-edit and axm-init expose tools through axm,
not standalone executables of those names.
git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups
uv run --package axm-edit --directory packages/axm-edit pytest --cov
uv run mkdocs build --strictContributing covers package-specific checks, the current Makefile limitations, hooks and documentation previews.
axm supplies the shared tool contract and CLI discovery.
axm-mcp exposes installed providers through MCP. Tool packages implement
operations; libraries such as axm-ingot can also be used without a server.
tool_node adapts a registered tool for a DAG, whose runtime lives outside
this workspace.
See the workspace architecture for package boundaries and the package catalog for individual tutorials and API references.
Packages use their full name as a Git tag prefix, for example
axm-ast/v0.5.2 or axm/v0.8.0. The publish workflow derives
packages/<name> from that prefix. Tagging is a release operation;
pushing documentation to main does not publish a package version.
The build and upload jobs have separate conditions. Consult the publish workflow before a release.
A package declares once, through the Private :: Do Not Upload
classifier, that it must never leave the monorepo. Both release
workflows read that marker from the shared
detect-package action:
the PyPI upload is withheld, and so is the GitHub Release, whose
generated notes would otherwise publish the changelog the package is
meant to keep in-house. Tagging, versioning and tests still run — only
the publication stops. PyPI independently rejects the Private ::
prefix on upload, so the classifier is a double safety net.
Apache 2.0 — see LICENSE.