hanzo-aci

Hanzo ACI (Agent Computer Interface) is a Python toolkit that gives AI agents the ability to edit files, lint code, index codebases, execute shell commands, and convert documents.

Hanzo ACI - Agent Computer Interface

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-mcp.md, hanzo/hanzo-code.md, hanzo/hanzo-agent.md

Overview

Hanzo ACI (Agent Computer Interface) is a Python toolkit that gives AI agents the ability to edit files, lint code, index codebases, execute shell commands, and convert documents. It provides the backend "hands" for Hanzo's AI coding agents. Integrates with hanzo-mcp for Model Context Protocol server capabilities. Installable as hanzo-aci from PyPI.

Why Hanzo ACI?

Tech Stack

OSS Base

Original work by Hanzo. The LocAgent indexing module draws on code intelligence patterns. The editor module is purpose-built for agent-driven file manipulation.

Repo: github.com/hanzoai/aci

When to use

Hard requirements

  1. Python 3.12+
  2. Poetry for dependency management
  3. hanzo-mcp package (local path dependency at ../mcp -- must be available)
  4. tree-sitter native libraries (installed via tree-sitter-language-pack)

Quick reference

| Item | Value | |------|-------| | PyPI Package | hanzo-aci | | Version | 1.0.0 | | Repo | github.com/hanzoai/aci | | Branch | main | | License | MIT | | Python | >=3.12 | | CLI | hanzo-dev (serve, edit, index) | | Server CLI | hanzo-dev-server | | Test | poetry run pytest | | Lint | make lint |

One-file quickstart

Install and use

# Install from PyPI
pip install hanzo-aci

# Or from source with all extras
git clone https://github.com/hanzoai/aci.git
cd aci
poetry install --extras llama

# Start the unified MCP + ACI server
hanzo-dev serve

# Edit a file via CLI
hanzo-dev edit myfile.py --line 42

# Index a codebase
hanzo-dev index /path/to/project --output index.json

Use in Python code

from hanzo_aci import file_editor, FileCache

# Initialize the file cache
cache = FileCache()

# Open and view a file with line numbers
result = file_editor.open_file("src/main.py", line_number=1)
print(result)

# The editor supports:
# - open_file(path, line_number=None)
# - create_file(path, content)
# - edit_file(path, old_str, new_str)
# - view_file(path, start_line, end_line)
# - undo_edit(path)

# Lint code before applying changes
from hanzo_aci.linter import DefaultLinter
linter = DefaultLinter()
errors = linter.lint("src/main.py")

Core Concepts

Architecture

┌─────────────────────────────────────────────┐
│ hanzo-dev CLI │
│ (unified entry point) │
├──────────┬──────────────┬───────────────────┤
│ serve │ edit │ index │
│ (MCP) │ (ACI) │ (LocAgent) │
└────┬─────┴──────┬───────┴────────┬──────────┘
 │ │ │
┌────▼────┐ ┌────▼──────────┐ ┌───▼──────────┐
│hanzo-mcp│ │ hanzo_aci/ │ │ indexing/ │
│ server │ │ editor/ │ │ locagent/ │
│ │ │ linter/ │ │ tools.py │
│ │ │ utils/ │ │ repo/ │
└─────────┘ └───────────────┘ └──────────────┘

Editor Module

The core module -- provides file manipulation for agents.

| Component | File | Purpose | |-----------|------|---------| | editor.py | 26KB | Main FileEditor class: open, create, edit, view, undo | | file_cache.py | 5KB | In-memory cache for file contents and metadata | | history.py | 4KB | Undo/redo history tracking per file | | encoding.py | 4KB | File encoding detection and handling | | exceptions.py | 1KB | Custom exceptions (EditorError, FileNotFoundError, etc.) | | prompts.py | 1KB | Prompt templates for agent interactions | | results.py | 1KB | Structured result types for editor operations | | md_converter.py | 41KB | Convert PDF/DOCX/PPTX/XLSX/HTML/YouTube to Markdown |

Linter Module

Tree-sitter based code validation.

| Component | File | Purpose | |-----------|------|---------| | linter.py | 5KB | Main linter orchestrator -- dispatches to language-specific impl | | base.py | 2KB | Base linter interface | | impl/ | -- | Language-specific linter implementations |

Indexing Module (LocAgent)

Code intelligence and search.

| Component | File | Purpose | |-----------|------|---------| | tools.py | 46KB | Core indexing tools: index_codebase, search, file analysis | | results.py | 7KB | Search result types and ranking | | compress.py | 2KB | Code compression for context windows | | utils.py | 1KB | Path and file utilities | | repo/ | -- | Repository structure analysis |

Utilities

| Component | File | Purpose | |-----------|------|---------| | shell.py | 2KB | Safe subprocess execution with timeout | | diff.py | 1KB | Unified diff generation for file changes | | logger.py | 800B | Structured logging setup |

CLI Commands

hanzo-dev serve [--transport stdio|sse] # Start MCP server (default)
hanzo-dev edit <file> [--line N] # Open file in ACI editor
hanzo-dev index <path> [--output file] # Index a codebase

Common flags:
 --allow-path <path> Allow access to specific paths
 --enable-all-tools Enable all available tools
 --enable-agent-tool Enable agent delegation tool
 --log-level DEBUG|INFO|WARNING|ERROR

Directory structure

aci/
├── hanzo_aci/
│ ├── __init__.py # Exports file_editor, FileCache
│ ├── cli.py # hanzo-dev CLI (v0.3.1)
│ ├── editor/
│ │ ├── __init__.py # Editor module exports
│ │ ├── editor.py # FileEditor class (26KB)
│ │ ├── file_cache.py # File content caching
│ │ ├── history.py # Undo/redo history
│ │ ├── encoding.py # Charset detection
│ │ ├── exceptions.py # EditorError types
│ │ ├── prompts.py # Agent prompt templates
│ │ ├── results.py # Structured results
│ │ ├── config.py # Editor configuration
│ │ └── md_converter.py # Document-to-Markdown (41KB)
│ ├── linter/
│ │ ├── __init__.py # Linter exports
│ │ ├── linter.py # Main linter
│ │ ├── base.py # Base interface
│ │ └── impl/ # Language-specific linters
│ ├── indexing/
│ │ └── locagent/
│ │ ├── tools.py # Code indexing (46KB)
│ │ ├── results.py # Search results
│ │ ├── compress.py # Code compression
│ │ ├── utils.py # Utilities
│ │ └── repo/ # Repo analysis
│ └── utils/
│ ├── diff.py # Diff generation
│ ├── shell.py # Shell execution
│ └── logger.py # Logging setup
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── data/ # Test fixtures
├── dev_config/
│ └── python/
│ └── .pre-commit-config.yaml
├── .github/workflows/
│ ├── py-unit-tests.yml # Unit test CI
│ ├── py-intg-tests.yml # Integration test CI
│ ├── lint.yml # Ruff lint CI
│ ├── pypi-release.yml # PyPI publish on release
│ └── hanzo-resolver.yml # Issue resolver
├── pyproject.toml # Poetry config, v1.0.0
├── poetry.lock
├── Makefile # lint, install-pre-commit-hooks
└── pytest.ini

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | ModuleNotFoundError: hanzo_mcp | Missing local dependency | Ensure ../mcp exists or install hanzo-mcp from PyPI | | tree-sitter parse errors | Wrong language pack version | Pin tree-sitter-language-pack==0.7.3 | | hanzo-dev serve hangs | No MCP client connected | Use stdio transport with a compatible MCP client | | llama-index import error | Optional dep not installed | Install with poetry install --extras llama | | Encoding errors on file read | Binary file detected | ACI uses binaryornot to skip binary files | | Lint CI fails | Pre-commit hooks not installed | Run make install-pre-commit-hooks |

Related Skills

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: agent, aci, editor, linter, mcp, code-intelligence Prerequisites: Python 3.12+, Poetry, tree-sitter