docs: documented project settings and disabled providers
Added user-facing settings, providers, and context-file documentation for project config precedence, project-local settings files, disabledProviders model-provider behavior, and path-scoped provider settings. Fixes #2447
This commit is contained in:
roboomp
@@ -0,0 +1,40 @@
|
||||
# Context files
|
||||
|
||||
Context files are markdown files `omp` discovers and injects into the agent context so repository rules, project notes, and tool-specific instructions follow the session.
|
||||
|
||||
## Native `.omp` files
|
||||
|
||||
| File | Scope | Behavior |
|
||||
|---|---|---|
|
||||
| `<cwd>/.omp/AGENTS.md` | Project | Project instructions loaded with the current directory. |
|
||||
| `~/.omp/agent/AGENTS.md` | User | User-level instructions loaded from the agent directory. |
|
||||
| `<cwd>/.omp/RULES.md` | Project | Sticky always-apply rule content re-injected near the current turn. |
|
||||
| `~/.omp/agent/RULES.md` | User | User-level sticky rule content. |
|
||||
|
||||
Other discovery providers can contribute compatible context files from their own conventions, such as Claude, Codex, Gemini, and GitHub instruction files.
|
||||
|
||||
## Discovery providers vs model providers
|
||||
|
||||
`disabledProviders` is a setting, not a context-file field. It accepts provider IDs in a shared namespace:
|
||||
|
||||
| Entry type | Examples | Effect |
|
||||
|---|---|---|
|
||||
| Model provider IDs | `anthropic`, `openai`, `gemini`, `groq`, `ollama`, `openrouter` | Prevent those model providers from becoming selectable, even when credentials are present. |
|
||||
| Discovery provider IDs | `native`, `claude`, `codex`, `gemini`, `github` | Prevent that capability provider from contributing context files, commands, hooks, tools, prompts, or other capability items. |
|
||||
|
||||
Most provider-control use cases should list model provider IDs. Use discovery provider IDs only when you intend to disable an entire config source.
|
||||
|
||||
```yaml
|
||||
# Disable model providers in this project.
|
||||
disabledProviders:
|
||||
- anthropic
|
||||
- openai
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Disable the Claude discovery source entirely.
|
||||
disabledProviders:
|
||||
- claude
|
||||
```
|
||||
|
||||
Project-level values are configured in `<project>/.omp/config.yml`; global values live in `~/.omp/agent/config.yml`. See [Settings](./settings.md) for precedence and array replacement behavior.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Providers
|
||||
|
||||
Providers are the model backends `omp` can route requests to: Anthropic, OpenAI, Gemini, Groq, Ollama, OpenRouter, custom `models.yml` providers, and extension-registered providers.
|
||||
|
||||
## Credentials
|
||||
|
||||
Provider credentials can come from stored auth, OAuth, `models.yml`, or environment variables. `omp` eagerly reads `.env` files at startup, including the current project's `<cwd>/.env`, so provider API keys in a project directory can make those providers available without any additional config.
|
||||
|
||||
Common environment variables include:
|
||||
|
||||
| Provider | Environment variable |
|
||||
|---|---|
|
||||
| Anthropic | `ANTHROPIC_API_KEY` |
|
||||
| OpenAI | `OPENAI_API_KEY` |
|
||||
| Gemini | `GEMINI_API_KEY` |
|
||||
| Groq | `GROQ_API_KEY` |
|
||||
| OpenRouter | `OPENROUTER_API_KEY` |
|
||||
|
||||
## Disabling model providers
|
||||
|
||||
Use the `disabledProviders` setting to make a model provider unavailable, even if credentials exist in `.env` or stored auth:
|
||||
|
||||
```yaml
|
||||
# ~/.omp/agent/config.yml or <project>/.omp/config.yml
|
||||
disabledProviders:
|
||||
- anthropic
|
||||
- openai
|
||||
- gemini
|
||||
- groq
|
||||
```
|
||||
|
||||
Project settings replace the global `disabledProviders` array. To disable a different set in one repository, put that complete set in `<project>/.omp/config.yml`.
|
||||
|
||||
```yaml
|
||||
# ~/.omp/agent/config.yml
|
||||
disabledProviders:
|
||||
- anthropic
|
||||
- openai
|
||||
- gemini
|
||||
|
||||
# <project>/.omp/config.yml
|
||||
disabledProviders:
|
||||
- groq
|
||||
```
|
||||
|
||||
Effective result inside the project: only `groq` is disabled.
|
||||
|
||||
For configuration file locations and precedence, see [Settings](./settings.md).
|
||||
|
||||
## Path-scoped provider settings
|
||||
|
||||
Scope `disabledProviders` to a directory with `path:` when only one subtree needs different provider availability:
|
||||
|
||||
```yaml
|
||||
disabledProviders:
|
||||
- ollama
|
||||
- path: ~/projects/sensitive
|
||||
providers:
|
||||
- anthropic
|
||||
- openai
|
||||
```
|
||||
|
||||
String entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories.
|
||||
|
||||
## Custom providers
|
||||
|
||||
Custom providers live in `~/.omp/agent/models.yml`. See [Model and Provider Configuration](./models.md) for the full `models.yml` schema, runtime discovery options, provider overrides, and model resolution behavior.
|
||||
@@ -0,0 +1,104 @@
|
||||
# Settings
|
||||
|
||||
`omp` reads settings from global files, project files, one-shot config overlays, and runtime inputs. Use project settings when one repository needs a different provider set, model role, tool policy, or UI setting than your global defaults.
|
||||
|
||||
## Files
|
||||
|
||||
| Scope | Path | Notes |
|
||||
|---|---|---|
|
||||
| Global | `~/.omp/agent/config.yml` | Main persistent settings file. `/settings` and `omp config set` write here. |
|
||||
| Global legacy | `~/.omp/agent/settings.json` | Migrated to `config.yml` when possible. |
|
||||
| Project | `<project>/.omp/config.yml` | Recommended per-project override file. Read from the process cwd's `.omp/` directory. |
|
||||
| Project legacy | `<project>/.omp/settings.json` | Still supported for project settings. |
|
||||
| Overlay | Any YAML file passed with `--config <file>` | Applies only to that process and is not persisted. Repeat `--config` to layer files. |
|
||||
|
||||
Project settings are read-only from discovery: changing settings through `/settings` or `omp config set` updates the global file, not `<project>/.omp/config.yml`.
|
||||
|
||||
## Precedence
|
||||
|
||||
Highest priority wins:
|
||||
|
||||
1. Runtime overrides and dedicated CLI flags (`--slow`, `--no-pty`, `--api-key`, etc.)
|
||||
2. Environment variables for fields that define env fallbacks (`PI_SLOW_MODEL`, provider API keys, etc.)
|
||||
3. CLI config overlays (`--config <file>`, later files override earlier files)
|
||||
4. Project settings (`<project>/.omp/settings.json`, then `<project>/.omp/config.yml`; `config.yml` wins within the project layer)
|
||||
5. Global settings (`~/.omp/agent/config.yml`)
|
||||
6. Built-in defaults
|
||||
|
||||
The settings merge itself is:
|
||||
|
||||
```text
|
||||
defaults <- global <- project <- CLI config overlays <- runtime overrides
|
||||
```
|
||||
|
||||
Environment variables are not written into config files; they are consulted by the feature that owns the setting or credential.
|
||||
|
||||
## Project settings
|
||||
|
||||
Put a config file in a project's `.omp/` directory to override global settings only for sessions launched from that directory:
|
||||
|
||||
```yaml
|
||||
# <project>/.omp/config.yml
|
||||
disabledProviders:
|
||||
- groq
|
||||
modelRoles:
|
||||
default: anthropic/claude-sonnet-4-5
|
||||
smol: openai/gpt-5.3-mini
|
||||
```
|
||||
|
||||
Objects are deep-merged. Arrays are replaced wholesale by the higher-precedence layer.
|
||||
|
||||
```yaml
|
||||
# ~/.omp/agent/config.yml
|
||||
disabledProviders:
|
||||
- anthropic
|
||||
- openai
|
||||
- gemini
|
||||
|
||||
# <project>/.omp/config.yml
|
||||
disabledProviders:
|
||||
- groq
|
||||
```
|
||||
|
||||
Effective result in that project:
|
||||
|
||||
```json
|
||||
["groq"]
|
||||
```
|
||||
|
||||
The project array replaces the global array; it does not append to it. In this example, `anthropic`, `openai`, and `gemini` are re-enabled for the project.
|
||||
|
||||
## `disabledProviders`
|
||||
|
||||
`disabledProviders` accepts provider IDs. It disables model providers such as `anthropic`, `openai`, `gemini`, `groq`, `openrouter`, `ollama`, and extension-registered model providers. The same setting also gates capability discovery providers when the entry matches a discovery provider ID such as `native`, `claude`, `codex`, or `gemini`.
|
||||
|
||||
Use model provider IDs when you want to prevent a provider from becoming selectable even if credentials are available from `.env`, OAuth, or stored auth.
|
||||
|
||||
```yaml
|
||||
disabledProviders:
|
||||
- anthropic
|
||||
- openai
|
||||
- gemini
|
||||
- groq
|
||||
```
|
||||
|
||||
## Path-scoped arrays
|
||||
|
||||
`enabledModels` and `disabledProviders` can include entries scoped to a path prefix:
|
||||
|
||||
```yaml
|
||||
enabledModels:
|
||||
- claude-sonnet-4-5
|
||||
- path: ~/work/high-context
|
||||
models:
|
||||
- anthropic/claude-opus-4-5
|
||||
|
||||
disabledProviders:
|
||||
- ollama
|
||||
- path: ~/projects/sensitive
|
||||
providers:
|
||||
- anthropic
|
||||
- openai
|
||||
```
|
||||
|
||||
String entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. Accepted path keys: `path`, `paths`, `pathPrefix`, `pathPrefixes`. Use `models` for `enabledModels`, `providers` for `disabledProviders`, or `values` for either.
|
||||
Reference in New Issue
Block a user