Houston Beta
Houston docs

Project rules

Houston folds a small hierarchy of rules files into the system prompt on each run, in this order:

  1. the global ~/.houston/AGENTS.md
  2. the project's own AGENTS.md / CLAUDE.md at its root
  3. any AGENTS.md / CLAUDE.md in subfolders, shallowest first

Use them for coding conventions, build and test commands, and house style. Houston treats them as conventions, not as authority to change tool or permission behavior.

  • Imports. Any rules file can pull in others with @path imports.
  • Skipped folders. In a git repository, subfolders the project's .gitignore excludes (dependencies, build output) are never searched for rules. Outside git, well-known dependency and build folders are skipped.
  • No duplicates. When two files hold the same rules (a CLAUDE.md that links to AGENTS.md, or an identical copy), Houston loads them once.
  • Size cap. All rules together are capped at 32,000 characters. When they run over, the global file is shortened (or left out) first, so your project's own rules still fit, and Houston tells the model which files were cut.

Using ~/.claude/CLAUDE.md

Houston doesn't load ~/.claude/CLAUDE.md on its own. To use it everywhere, add this line to ~/.houston/AGENTS.md:

@~/.claude/CLAUDE.md

When Houston finds that file and your global rules don't import it yet, it offers once to add the line for you (Import it) or leave things as they are (Keep separate). Rules after the import line win where the two disagree.