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 can be injected into AGENTS.md alongside MCP server entries in .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:

uv run venvaxi setup --skill

[!WARNING] Unlike the marked AGENTS.md block, 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 (AGENTS.md block + MCP config) 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 Interpretable Context Methodology (ICM), which uses folder structure as Agent Architecture.

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.

The system is self-documenting - read AGENTS.md (symlink -> CLAUDE.md), which provides development context and routes to CONTEXT.md for the workspace, stage and reference material an agent would follow.

Context reference and guidance markdown files are kept in ICM/_config as living documents and are routed into the agent context where necessary.

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

[!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.

ICM is spec-driven. Three artifact layers are kept deliberately separate:

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 - adapted from JarvusInnovations/specops
• 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