Skip to content
AgentAtlas

goose .goosehints and AGENTS.md: Global and Project Instructions

How do I give goose project rules with .goosehints or AGENTS.md?

Create a .goosehints file in your project folder, or ~/.config/goose/.goosehints for rules that apply everywhere. By default goose reads both AGENTS.md and .goosehints, and the Developer extension must be on. Local hints win over global hints when they conflict.

Compare: rules and instruction files in every AI coding agent →

File locations

  • Global: ~/.config/goose/.goosehints. Applies to every session.
  • Local: .goosehints in a project folder. Applies only in that folder tree.
  • You can use both. Local hints take priority on conflicts.
  • The Developer extension must be enabled.

AGENTS.md and other file names

By default goose reads AGENTS.md and .goosehints. Set CONTEXT_FILE_NAMES to a JSON array to change the list.

Shell

export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", "project_rules.txt"]'

Example hints

~/.config/goose/.goosehints

Always use TypeScript for new Next.js projects.
Run unit tests before committing any changes.
Prefer functional programming patterns where applicable.

.goosehints in a project

Make sure to confirm all changes with me before applying.
Run tests with `npm run test` ideally after each change.

Pull in other files

  • @filename, such as @README.md, puts that file's content straight into context.
  • A plain file name without @ tells goose where to look when it needs it. Use this for large or optional files.

Nested folders

  • In a git repo, goose loads hint files from the working folder up to the repo root at session start.
  • When goose reads or edits files in a subfolder, it loads hint files it finds there.
  • Loaded hints stay active for the session. Restart to pick up edits reliably.

Set it up in goose Desktop

Open Settings, then Chat, then Project Hints (.goosehints), then Configure. Save and restart the session.

Sources

More goose guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →