Agent eXperience Interface [venv-axi]

venv-axi provides an Agent eXperience Interface (AXI), which introspects dependencies for consuming projects - querying exact signatures present in that venv, at the exact versions pinned there - in a token-efficient TOON format, on STDOUT.

The CLI is installed as venvaxi and the same tools are available over MCP (STDIO).

Why?

The AXI allows introspection of installed packages by importing them, thereby covering private, internal and undocumented distributions that documentation-retrieval tools cannot see.

The interface cannot drift from the pinned version - reporting what a symbol is rather than how to use it - complimenting a documentation source such as Context7, King Context etc.

The AXI answers 'does this exist and what is its exact shape in the version I have installed?' - other tools answer 'how do I use this and why?'

How?

An agent scans the codebase with available tools and uses its findings to drive the AXI:

1. Scan the codebase -> bare name (Console.print) & package (rich)
2. Resolve bare name -> qualified name

uv run venvaxi find Console.print --package rich

uv run venvaxi inspect rich.console::Console.print

Other commands:

• venvaxi - Live status & next-step hints
• venvaxi list - Installed, declared dependencies
• venvaxi show rich --api - Public API symbols
• venvaxi tree rich --max-depth 1 - Nested module tree
• venvaxi inspect rich.console - Direct children
• venvaxi inherits <qualified_name> - Direct subclasses

Docstrings are truncated to a first line by default - add --docstring for complete bodies. The --refresh option rebuilds a stale graph after a dependency version change.

Ambient context for agents is registered by setup, which writes MCP server entries into .vscode/mcp.json and .mcp.json:

uv run venvaxi setup

The optional --skill flag additionally installs a Skill at .claude/skills/venvaxi/SKILL.md, covering the scan -> resolve -> inspect workflow, commands and MCP tool surface alongside common gotchas. The Skill is the agent-facing half of ambient context, loaded on demand rather than kept in every session:

uv run venvaxi setup --skill

Versions before v0.3.0 also injected an always-on block into AGENTS.md between <!-- venvaxi:begin --> and <!-- venvaxi:end --> markers. That block duplicated the Skill in every session, and is no longer written. setup removes one it finds, leaving every byte outside the markers untouched.

[!WARNING] SKILL.md is a bundled artifact - any local edits to a previously installed copy are overwritten.

The AXI tools can be served over MCP (STDIO) with the venvaxi serve command, which requires the mcp extra:

uv add venv-axi --dev --extra mcp

The MCP server exposes; listPackagesTool, showPackageTool, showPackageApiTool, showModuleTool, getSymbolTool, findSymbolTool, getInheritorsTool and getModuleTreeTool

[!NOTE] Tool names are in camelCase format, generated from the snake_case function names (_mcp.py).

Installation

[!NOTE] Installation is package-manager agnostic. Use another manager like Poetry and replace the uv run accordingly or omit entirely, with an activated venv.

uv add venv-axi --dev

With the MCP server extra:

uv add venv-axi --dev --extra mcp

Register ambient context (MCP config, plus the Skill with --skill) in the consuming repo:

uv run venvaxi setup

[!NOTE] The MCP config (.mcp.json) is only created on setup when venv-axi is installed with the mcp optional dependency. On adding this extra dependency, rerun the setup command.

The symbol graph is cached per-project under ~/.venvaxi/.

A note on AI usage

This project is being used as a testbed for spec-driven development (spec-anchored) on top of Interpretable Context Methodology Interpretable Context Methodology (ICM).

With spec-anchored development, a specification evolves alongside the software and is updated to reflect the current state of the system as it changes. Adverserial agent verification is used to automate spec-drift detection.

ICM replaces framework-level orchestration with filesystem structure. Numbered folders represent stages. Plain markdown files carry prompts and context that tell a single AI agent what role to play at each step.

[!IMPORTANT] Concepts adapted from an Interpretable Context Methodology paper attributed to Van Clief, J. and McDermott, D., 2026 (arXiv:2603.16021).

The system is self-documenting and has been wrapped up in a Claude Code plugin at andyrids/icm-spec.

A large community dedicated to this methodology can be found at https://www.skool.com/cliefnotes.

A community member made a detailed and easy-to-understand video guide on YouTube - here.

[!NOTE] ICM can leverage AI in a way that streamlines development, but also generates enough friction in the right areas to promote continued development (Friction Doctrine). This method of using Agents is a WIP.

specs/ is the source of truth for behaviour; plans/ is the durable record of what got built and why. Stage outputs stay gitignored scratch. See specs/README.md and plans/README.md.

TODO:

• Research spec-driven development integration & ICM suitability
  • Referenced JarvusInnovations/specops
  • Created a Claude Code plugin - andyrids/icm-spec
• Research verification loops & ICM suitability
  • Getting started with loops
  • Building verification loops
• Research context engineering changes
  • The new rules of context engineering

Attribution

tirth8205/code-review-graph

The SQLite Node|Edge graph architecture and symbol-graph walking patterns used in the AXI modules are heavily inspired by code-review-graph.

code-review-graph populates its graph from a static AST, whereas the AXI populates its graph from live object introspection via importlib and inspect.

• Repository: tirth8205/code-review-graph
• License: MIT License - Copyright (c) 2026 Tirth Kanani

toon-format/toon-python

The regex patterns, structural tokens and constant-extraction patterns for TOON format are directly adapted from the official toon-python reference implementation.

• Repository: toon-format/toon-python
• License: MIT License - Copyright (c) 2025 TOON Format Organization

kunchenguid/axi

I became aware of the AXI design principles through Kun Chen via his projects and axi.md site. His benchmarks and use of TOON format inspired and informed the creation of venv-axi - a future contribution to the AXI Community Catalog.

• Repository:
  • kunchenguid/axi
  • kunchenguid/gh-axi
• License: MIT License - Copyright (c) 2026 Kun Chen

JarvusInnovations/specops | IBM/iac-spec-kit | github/spec-kit

I looked at existing repos focused on spec-driven development (SSD), which were useful in determining what functionality and aspects are best to combine with ICM.

• Repository:
  • JarvusInnovations/specops
    • License: N/A
  • IBM/iac-spec-kit
    • License: MIT License - Copyright (c) 2025 Copyright International Business Machines
  • IBM/iac-spec-kit
    • License: MIT License - Copyright (c) 2026 Copyright GitHub, Inc