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.

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.
• If you send a command to a terminal, don't forget the newline or carriage return required (Unix, or Windows specific).
• 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/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.

App builds

• GitHub Actions builds and packages the desktop app for macOS, Windows, and Linux via manual trigger only (see .github/workflows/build-app.yml).
• The workflow installs menai from PyPI (including the pre-built C VM) via pip install menai.
• macOS produces a signed/notarized .dmg, Windows produces an .exe installer via Inno Setup, and Linux produces an .AppImage for x86_64 and ARM64 via build-appimage.sh.