humbug: Instructions file for Codex

AGENTS.md - Humbug Project Structure

Overview

Humbug is a platform for human-AI collaboration, written in Python. This document describes how AI agents should navigate the codebase.

Architecture decisions

Significant architectural and design decisions are recorded as ADRs in docs/adr/, which holds the definitive index and the conventions for writing new ADRs. Consult it before proposing changes that touch established decisions.

Tool use

• If you want to use the terminal you will require user authorization every time you send keystrokes. If you load files into an editor tab, however, you don't. If you just want to do a simple search of a file then consider using the editor tabs. They can get pretty cluttered though so if you don't need the tab again then close it.
• If you open a terminal it will automatically be in the root of the mindspace directory. Don't change directory unless you want to be somewhere else.
• Terminals will not open with a python virtual environment by default. The venv is at venv/ in the mindspace root.
• Do not pipe pytest output through grep or other filtering tools. pytest interleaves progress dots on stderr with summary lines on stdout, so filtering mangles the output and hides the pass/fail counts. Run pytest with no flags and pipe through tail only if the output is too long to read in full:

  python -m pytest tests/src/menai_ai_tool/ 2>&1 | tail -10
  

Menai C VM binary

• Menai is installed from PyPI as a dependency of Humbug (pip install menai).
• Pre-built wheels include the C VM binary for all supported platforms (Linux, macOS, and Windows on x86_64 and ARM64, Python 3.10–3.14), so no separate clone, build, or download step is needed.
• Humbug's pyproject.toml does not pin a version, so pip install always fetches the latest version from PyPI.
• For local development on Menai itself, clone the menai repository and install it as an editable dependency: pip install -e /path/to/menai.