Ignore files

To stop Hull from reading or editing certain files, such as secrets, generated code or large data, deny them with permission rules. If you already have a .hullcodeignore file, Hull still reads it.

Use permission rulesCopy Anchor Link

Add deny rules for the read and edit tools in hull.json:

{
  "permission": {
    "read": {
      "*": "allow",
      "secrets/*": "deny",
      "*.pem": "deny"
    },
    "edit": {
      "*": "allow",
      "dist/*": "deny",
      "*.lock": "deny"
    }
  }
}

The last matching rule wins, so put "*" first. Rules let you do things an ignore file can't, such as allowing Hull to read a folder but not edit it.

When Hull tries to use a denied file, the tool call is blocked and the agent is told why.

Use .hullcodeignoreCopy Anchor Link

.hullcodeignore uses .gitignore syntax:

# Secrets
secrets/
*.pem

# Generated output
dist/

# Keep this one
!dist/README.md

• Lines starting with # are comments.
• A trailing / matches a folder and everything in it.
• ! re-allows a path that an earlier pattern blocked.

Hull looks for .hullcodeignore in the project root, and for a global one at ~/.hullcode/.hullcodeignore. It turns every pattern into a deny rule for both read and edit. Rules you write in hull.json take priority over the ignore file.

A project's .hullcodeignore is applied only after you trust the project.

Files Hull skips anywayCopy Anchor Link

When listing and searching files, Hull already skips:

• Files ignored by .gitignore and .ignore
• Common dependency and build folders, such as node_modules, .git, dist, build and __pycache__

This only affects listing and searching. To block access to a file completely, use a deny rule.

Exclude paths from the file watcherCopy Anchor Link

Hull watches your project for changes. To stop it watching busy folders, use watcher.ignore. This only affects change detection, not what the agent can read:

{
  "watcher": {
    "ignore": ["tmp/**", "logs/**"]
  }
}

CheckpointsCopy Anchor Link

Checkpoints are separate from access rules. A file Hull can't read can still be included in a checkpoint unless .gitignore excludes it.

TroubleshootingCopy Anchor Link

• Hull can't open a file you need. Narrow or remove the matching rule in hull.json or .hullcodeignore.
• .hullcodeignore seems ignored. Check that it's in the project root, uses .gitignore syntax and that the project is trusted. Reload or start a new session after editing it.