AGENTS.md

AGENTS.md is a Markdown file at the root of your repository that tells coding agents how to work on your project. Think of it as a README for agents: how the code is organized, how to build and test it, and which conventions to follow.

Hull adds AGENTS.md to every session in that project. Because it lives in the repository, everyone on your team gets the same guidance, in Hull Desktop, the CLI and the IDE extensions. Other coding tools that follow the AGENTS.md convention read it too.

Create oneCopy Anchor Link

Run /init in a session. Hull looks through the project and writes an AGENTS.md, or updates the one you have. Review it, edit anything that's wrong, and commit it.

You can also write it by hand. There's no required format. Plain Markdown with clear headings works best:

# Acme API

Node.js service that serves the Acme mobile app.

## Commands

- Install: `pnpm install`
- Test: `pnpm test` (run before you finish any change)
- Lint: `pnpm lint --fix`

## Code style

- TypeScript strict mode. No `any`.
- Validate request bodies with `zod` schemas in `src/schemas/`.
- Keep route handlers thin. Put logic in `src/services/`.

## Don't

- Don't edit generated files in `src/gen/`.
- Don't add dependencies without asking.

The filename must be AGENTS.md, in capitals.

Where Hull looksCopy Anchor Link

• Project root. Hull loads AGENTS.md from the folder you open and from parent folders up to the root of the repository.
• Subfolders. When an agent reads a file, Hull also loads any AGENTS.md in that file's folder and the folders above it. Use this for guidance that only applies to part of a repository, such as packages/api/AGENTS.md in a monorepo. Subfolder files add to the root instructions, so you don't need to repeat them.

my-project/
├── AGENTS.md            # loaded in every session
└── packages/
    ├── api/
    │   └── AGENTS.md    # loaded when the agent reads files in packages/api
    └── web/
        └── AGENTS.md    # loaded when the agent reads files in packages/web

If a folder has no AGENTS.md, Hull also accepts CLAUDE.md (when Claude Code compatibility is on) or CONTEXT.md.

For instructions that apply to all your projects, use ~/.config/hull/AGENTS.md. See Instructions and rules.

Edits need approvalCopy Anchor Link

Agents can propose changes to AGENTS.md, but Hull always asks before it writes to the root AGENTS.md, even when edits are otherwise auto-approved. This stops an agent from quietly changing its own instructions.

Project trustCopy Anchor Link

Hull loads a repository's AGENTS.md only after you trust the project. Hull asks the first time you open it. This prevents an unfamiliar repository from steering the agent before you've looked at it.

TipsCopy Anchor Link

• Lead with commands. How to install, build, test and lint is the most useful thing you can tell an agent.
• Be concrete. Name files, folders and libraries. "Put new endpoints in src/routes/" beats "follow the existing structure".
• Keep it short. AGENTS.md uses context in every session. Move long procedures into skills, which load only when needed.
• Update it with the code. Treat changes to AGENTS.md like any other change and review them in pull requests.

RelatedCopy Anchor Link

• Instructions and rules
• Skills
• Migrate from another tool