Model instructions and tools

Give Orek your project’s working conventions, add guidance for a particular model, or control which existing tools that model can see. Instructions extend Orek’s built-in instructions; they do not replace its operating rules or permissions. Tool rules control availability, while permission checks still decide whether an available tool may perform an action.

Find the model ID and choose a configuration scope

Configure a provider and choose a model first. Inspect the catalog in your shell:

orek models --plain

Copy the exact provider name and <provider>/<model> ID (such as openai and openai/gpt-6-luna). Display names, short aliases, and the provider’s own model names do not match. Model-specific instructions and tool rules both match the provider and model exactly, including case.

Find your configuration paths:

orek config path

Open the user file to apply an entry across projects, or the project’s .orek/config.toml to apply it only here. Edit these entries in the file; config set cannot write a whole instruction or tool rule. Check what Orek loaded with orek config get prompt_guidance or orek config get tool_exposure.

Reload and check changes

Restart Orek in the project’s root directory after editing model-specific instructions or tool rules. Also restart after changing tools.apply_patch.exposed, even through /config set, so the new tool list takes effect. To reload AGENTS.md, see When Orek reads these files.

Select the target model in the TUI:

/model openai/gpt-6-luna

Send a small request that exercises the instruction or tool rule. Inspect the response and confirm the selected model. Tool visibility and approval remain separate controls.

Add model instructions

Orek has no setting that replaces its built-in instructions, and no single setting that adds instructions for every model and project. Choose one of the options below for the scope you need.

Choose where the instructions belong

Add project conventions

Start Orek from your project’s root directory, and create or edit AGENTS.md there. For example:

# Working on this project

- Read the nearest README before changing a module.
- Keep changes focused on the requested task.
- After a code change, run the relevant tests and report their results.
- Explain any behavior that you could not verify.

You can also add nested files, such as src/AGENTS.md or src/api/AGENTS.md. Each file applies to its directory and the directories below it. A deeper file takes precedence over a parent file when they conflict; your direct request takes precedence over all of them.

When Orek reads these files

• Where it looks: When a session starts, Orek searches your project root and any folders added with --add-dir (-A), including their subfolders but not their parent folders. In an open session, /clear or /setup reloads AGENTS.md; otherwise restart Orek after editing.
• What it skips: Hidden folders, paths excluded by .gitignore, .ignore, or Git exclude files, and symlinks.
• Depth limit: Nested AGENTS.md files are found up to nine folder levels below the root.
• Size limits: Orek loads UTF-8 text up to 32 KiB per file and 64 KiB in total. It loads the root file first, then the deepest nested files that fit, and notes when text or files were left out. Keep large reference material in separate files that Orek can read when needed.

Guide project discovery

When search_project is available, project instructions can ask the model to use it for questions about where behavior is implemented, then read the cited source. Use code_graph_query for definitions and caller relationships, grep_files for exact strings, and tool_search to discover available tools. For example, add this convention to AGENTS.md:

- Use search_project to locate relevant project content, then read the
  source before changing it. Start broad when the location is unknown; use a
  literal file or directory path for focused follow-up searches. Check
  freshness and any truncated results.

Instructions do not enable missing tools. search_project needs a project index and tools.search_project.enabled. Tool rules (per model or per quality tier), a subagent profile’s tool list, and --no-tools can remove it. It stays available when automatic retrieval is turned off. See Find and explore code.

Save model-specific guidance

Add this entry to the user or project configuration file you chose above:

[[prompt_guidance.per_model]]
provider = "openai"
model = "openai/gpt-6-luna"
text = """
Keep explanations brief and concrete.
When describing a code change, name the files changed and the checks run.
If evidence is missing, say what still needs to be checked.
"""

Save the file, then inspect what Orek loads:

orek config get prompt_guidance

Matching and override rules

• The provider and model must both match exactly, including case.
• Orek uses the first matching entry with nonblank text. Matching entries are not joined together; keep one entry per provider/model pair.
• A project prompt_guidance.per_model list replaces the entire user list. Include every entry you want available in that project, not just the one whose text differs.
• Orek adds guidance after its built-in instructions. It does not grant tools or skip approval checks.
• If you switch between Claude models with agent.reasoning_replay set to preserve (see Switching models and providers), the conversation keeps the instructions Claude already received. A model with different guidance receives it with your next message, not partway through a tool call already running.

To remove model guidance, delete its entry, save, and restart. If you remove the entire project list, the user list can apply again. Setting the project list to an empty array keeps the user list overridden.

Control model tool access

Use model-specific tool rules when you want a model to work with a smaller set of tools, or when you want to try an existing tool that Orek normally hides. Configure the exact provider/model pair in the user or project scope as described above.

Hide named tools

This example prevents the selected model from using Orek’s local fetch tool:

[[tool_exposure.per_model]]
provider = "openai"
model = "openai/gpt-6-luna"
hidden = ["webfetch"]

Use exact tool names from the agent tool reference. Hiding a tool is not a sandbox—other tools or processes can still access files or the network, so pair tool rules with execution and approval settings.

Reveal an existing hidden tool, if needed

Orek normally uses search_replace to edit existing files. The alternative apply_patch tool is built in but hidden by default. To expose it to just one model, add revealed to that model’s rule:

[[tool_exposure.per_model]]
provider = "openai"
model = "openai/gpt-6-luna"
hidden = ["webfetch"]
revealed = ["apply_patch"]

This example replaces the entry above in the same file. revealed only exposes a tool that already exists in Orek; it does not create a tool or connect an MCP server. Existing permissions and session restrictions still apply.

To make apply_patch available to all models, save this experimental setting in your user configuration (default false):

orek config set tools.apply_patch.exposed true

The equivalent TOML is:

[tools.apply_patch]
exposed = true

A per-model hidden = ["apply_patch"] still takes precedence for that model. Restart Orek after changing this setting so the updated tool list takes effect.

Check the active setting and rule precedence

Check the tool rules Orek loaded, then restart Orek and select the target model:

orek config get tool_exposure

/model openai/gpt-6-luna

Orek evaluates overlapping tool-exposure rules in this order:

To undo a hidden rule, remove the tool from every matching hidden entry that introduced it, save, and restart. See the tool exposure reference for full schema details.

Troubleshooting