Configuration

OmniDev uses a small set of files to define what capabilities you want and how they are applied across providers.

Core files

• omni.toml: main configuration (commit this)
• omni.lock.toml: pinned versions and commits (commit this)
• omni.local.toml: local overrides (gitignored)
• OMNI.md: project instructions (source of truth)
• .omni/: runtime state (gitignored)

How configuration flows

1. You declare capability sources and profiles in omni.toml.
2. omnidev sync downloads capabilities and generates instructions from rules and docs.
3. Provider files like CLAUDE.md and AGENTS.md are generated from OMNI.md with instructions embedded directly.

omni.toml

Main configuration file. You define capability sources, profiles, and MCP servers here.

See Capability Sources and Profiles for the key sections you will edit most.

MCP details are documented in Capabilities → MCP Servers.

[capabilities.sources]
obsidian = "github:kepano/obsidian-skills"

[profiles.default]
capabilities = ["obsidian"]

omni.lock.toml

Version lock file generated by omnidev sync. It records exact versions/commits of capability sources.

omni.local.toml

Local overrides that are not committed (gitignored). This file has the same structure as omni.toml but takes higher precedence when both files are merged.

Use cases:

• Add private capabilities you don’t want to share with your team
• Override capability sources to point to local development versions
• Disable capabilities from the team config that you don’t need
• Test experimental capabilities before adding them to the shared config

# Add local capabilities to your profile
[profiles.default]
capabilities = ["tasks", "my-private-cap"]

# Override a source to use local development version
[capabilities.sources]
tasks = "file://./local/tasks-dev"

# Add your own local capabilities
my-private-cap = "file://./my-local-capabilities/private"

# Disable capabilities you don't want (from any profile)
[capabilities]
always_disabled = ["telemetry", "analytics"]

Merge behavior

When both omni.toml and omni.local.toml exist:

• Profiles: Local profiles override base profiles with the same name
• Capability sources: Local sources override base sources for the same ID; new sources are added
• Capability groups: Local groups override base groups for the same name; new groups are added
• always_enabled: Combined from both files (deduplicated)
• always_disabled: Combined from both files (deduplicated)
• MCPs: Local MCPs override base MCPs for the same name; new MCPs are added

always_disabled

The always_disabled setting in the [capabilities] section removes capabilities from ALL profiles, regardless of how they are enabled. This is particularly useful in omni.local.toml to disable capabilities from your team’s shared config.

# In omni.local.toml
[capabilities]
# These capabilities will never load, even if listed in profiles or always_enabled
always_disabled = ["noisy-telemetry", "unwanted-feature"]

# You can also use group references
always_disabled = ["group:noisy-tools"]

The always_disabled filter is applied after all other capability resolution (profiles, groups, always_enabled), so it effectively acts as a final blocklist.

OMNI.md

Single source of truth for project instructions. Provider files are generated from this file during sync.

See the dedicated OMNI.md guide.

.omni/

Runtime directory containing downloaded capabilities and state.

• .omni/capabilities/ holds fetched sources
• .omni/state/ holds runtime state (manifest, providers, active profile)