Instructions and rules

Instructions are Markdown text that Hull adds to every session. Use them for things you'd otherwise repeat in every prompt: coding style, how to run tests, which libraries to use, what to avoid.

Hull reads instructions from several places and combines them:

For most projects, start with an AGENTS.md file at the root. Run /init and Hull writes one for you.

Project instructionsCopy Anchor Link

Put shared project instructions in AGENTS.md at the root of your repository and commit it, so everyone on the team and every Hull surface uses the same guidance. See AGENTS.md.

To split instructions into topics, add Markdown files to .hull/rules/ in the project root. Hull loads every .md file in that folder:

my-project/
├── AGENTS.md
└── .hull/
    └── rules/
        ├── testing.md
        └── api-conventions.md

Personal instructionsCopy Anchor Link

For preferences that apply to all your projects, such as "explain changes briefly" or "use pnpm", create ~/.config/hull/AGENTS.md. You can also put several files in ~/.hull/rules/.

The instructions settingCopy Anchor Link

List extra instruction files in hull.json. Entries can be paths, glob patterns or URLs:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines/*.md",
    "https://example.com/team-instructions.md"
  ]
}

• Relative paths and globs are matched from the current directory up to the root of the repository.
• ~/ expands to your home directory.
• URLs are fetched when a session starts. If a URL doesn't respond within 5 seconds, Hull skips it.

In VS Code, manage this list in Settings > Agent Behaviour > Rules. In JetBrains, use Settings > Tools > Hull Code > Agent Behavior > Rules.

Instructions for one agentCopy Anchor Link

To change how a single agent behaves, give it a prompt. In hull.json:

{
  "agent": {
    "code": {
      "prompt": "Prefer small, focused commits. Run the linter before you finish."
    }
  }
}

Or create a Markdown file for the agent in .hull/agents/, where the body is the prompt. See Custom agents.

Claude Code compatibilityCopy Anchor Link

Hull also reads CLAUDE.md in your project and ~/.claude/CLAUDE.md, so a project set up for Claude Code works without changes. If a folder has both AGENTS.md and CLAUDE.md, Hull uses AGENTS.md.

• In the VS Code extension this is off by default. Turn on hull-code.new.claudeCodeCompat to enable it.
• In the CLI it's on by default. Set HULL_DISABLE_CLAUDE_CODE=1 to turn it off.

Project trustCopy Anchor Link

Instructions in a repository are only loaded after you trust that project. Hull asks the first time you open a project that contains AGENTS.md, .hull/ or similar files. Your global instructions always load. In the CLI, run hull trust to trust the current project.

Legacy rule filesCopy Anchor Link

Hull still loads rule files from older versions of the extension, and applies them to every agent:

• .hullcoderules and .hullcoderules-<mode> in the project root
• .hullcode/rules/ and ~/.hullcode/rules/
• .hull/rules-<mode>/ and .hullcode/rules-<mode>/, for the code, architect, ask and debug modes

Move their content into AGENTS.md or .hull/rules/ when you can.

Write good instructionsCopy Anchor Link

• Be specific. "Use zod for request validation" works better than "validate inputs".
• Show examples. A short code sample of the pattern you want is clearer than a description.
• Group by topic with headings such as Code style, Testing and Security.
• Keep it short. Instructions take up context in every session. Move long, task-specific guidance into a skill, which Hull loads only when it's needed.
• Keep it current. Update instructions when your conventions change.

RelatedCopy Anchor Link

• AGENTS.md
• Skills
• Custom agents
• Settings