programs.codex.enable
Whether to enable Lightweight coding agent that runs in your terminal.
Type: boolean
Default:
false
Example:
true
Declared by:
programs.codex.enableMcpIntegration
Whether to integrate the MCP server config from
programs.mcp.servers into
programs.codex.settings.mcp_servers.
Note: Settings defined in programs.mcp.servers are merged
with programs.codex.settings.mcp_servers, with settings-based
values taking precedence.
Type: boolean
Default:
false
Declared by:
programs.codex.package
The codex package to use.
Type: null or package
Default:
pkgs.codex
Declared by:
programs.codex.context
Global context for Codex.
The value is either:
- Inline content as a string
- A path to a file containing the content
The configured content is written to
CODEX_HOME/AGENTS.md.
Type: strings concatenated with “\n” or absolute path
Default:
""
Example:
''
- Always respond with emojis
- Only use git commands when explicitly requested
''
Declared by:
programs.codex.contextOverride
Global override context for Codex.
This has the same value format as programs.codex.context,
but writes CODEX_HOME/AGENTS.override.md.
Codex prefers AGENTS.override.md over
AGENTS.md in the same directory.
Type: null or strings concatenated with “\n” or absolute path
Default:
null
Example:
''
- Temporarily ignore default global guidance
- Prefer brief answers while debugging
''
Declared by:
programs.codex.hooks
Lifecycle hook events written to CODEX_HOME/hooks.json.
This option can either be a hook event attribute set, a path to a
complete hooks JSON file, or a path to a hook bundle directory
containing hooks.json and supporting hook scripts.
Attribute set values use the same event structure as
programs.codex.settings.hooks and are written under the
top-level hooks key expected by Codex’s JSON hooks file.
Directory values install hooks.json to
CODEX_HOME/hooks.json and install the full directory to
the active Codex home hooks directory. In the default layout, commands
can reference bundled scripts with paths such as
$HOME/.codex/hooks/my-hook. When
home.preferXdgDirectories is enabled, use
$CODEX_HOME/hooks/my-hook.
Hooks can also be configured inline through
programs.codex.settings.hooks; prefer using only one hook
representation per layer.
Type: JSON value or absolute path
Default:
{ }
Example:
{
PreToolUse = [
{
matcher = "^Bash$";
hooks = [
{
type = "command";
command = "/usr/local/bin/codex-pre-tool-use";
timeout = 30;
statusMessage = "Checking Bash command";
}
];
}
];
}
Declared by:
programs.codex.marketplaces
Custom marketplaces for Codex plugins. The attribute name becomes the marketplace name, and the value is either:
- A path to the marketplace directory
- The marketplace package, whether a nix package or the output of a fetcher
Marketplaces are configured through CODEX_HOME/config.toml.
Type: attribute set of (package or absolute path)
Default:
{ }
Example:
{
local-marketplace = ./my-local-marketplace;
gh-marketplace = fetchFromGitHub {
owner = "some-github-org";
repo = "codex-marketplace";
rev = "8a873a220b8427b25b03ce1a821593a24e098c34";
sha256 = "5c2dce95122b5bb73fa547edabbb6c3061c2d193d11e51faecd4d22659e67279";
};
}
Declared by:
programs.codex.mutableSettings
Whether to merge declared settings into a writable Codex configuration file during activation, preserving settings added by Codex or the user. Declared values take precedence. Only supported for Codex 0.2.0 and later. The default keeps the configuration file immutable.
Type: boolean
Default:
false
Example:
true
Declared by:
programs.codex.plugins
List of plugins to use when running Codex. Each entry is either:
- A path to the plugin directory
- The plugin package, whether a nix package or the output of a fetcher
Plugins are installed into Codex’s plugin cache and enabled through
CODEX_HOME/config.toml.
Warning: If using a derivation as the source for a plugin, make sure that the derivation name matches the name of the plugin in the manifest file.
Type: list of (package or absolute path)
Default:
[ ]
Example:
[
./my-local-plugin
(fetchFromGitHub {
owner = "some-github-org";
repo = "codex-plugin";
rev = "779a68ebc2a75e4a184d2c87e5a43a758e6458a1";
sha256 = "228fdd7e5908ea1d2f65218ecd9c71e1eefa0834d200d55fbb8bf8b5563acec0";
})
]
Declared by:
programs.codex.profiles
Named Codex configuration profiles written to
CODEX_HOME/<name>.config.toml.
These profiles are selected with codex --profile <name>.
Codex 0.134.0 and later no longer reads profile settings from
programs.codex.settings.profiles, and the top-level
programs.codex.settings.profile selector is no longer
supported.
Type: attribute set of (TOML value)
Default:
{ }
Example:
{
deep-review = {
model = "gpt-5.5";
model_reasoning_effort = "xhigh";
approval_policy = "on-request";
sandbox_mode = "workspace-write";
};
}
Declared by:
programs.codex.rules
Codex rules files to manage under CODEX_HOME/rules/.
The attribute name becomes the filename, with a .rules
extension added automatically. The value is either:
- Inline content as a string
- A path to an existing rules file
This is useful for declaratively managing persistent
prefix_rule() definitions, including the default
default.rules allow-list Codex writes when you accept
recurring approvals interactively.
Type: attribute set of (strings concatenated with “\n” or absolute path)
Default:
{ }
Example:
{
default = "prefix_rule(pattern = [\"nix\", \"build\"], decision = \"allow\")\n";
github = ./codex/github.rules;
}
Declared by:
programs.codex.settings
Configuration written to CODEX_HOME/config.toml (0.2.0+)
or ~/.codex/config.yaml (<0.2.0). Per default CODEX_HOME
defaults to ~/.codex.
See https://developers.openai.com/codex/config-reference for supported values.
Type: null or TOML value
Default:
{ }
Example:
{
model = "gemma3:latest";
model_provider = "ollama";
model_providers = {
ollama = {
name = "Ollama";
base_url = "http://localhost:11434/v1";
env_key = "OLLAMA_API_KEY";
};
};
mcp_servers = {
context7 = {
command = "npx";
args = [
"-y"
"@upstash/context7-mcp"
];
};
};
}
Declared by:
programs.codex.skills
Custom skills for Codex.
This option can be either:
- An attribute set defining skills
- A path to a directory containing skill folders
If an attribute set is used, the attribute name becomes the skill directory name, and the value is either:
- Inline content as a string (creates a generated skill directory at
<skills-dir>/<name>/) - A path to a file (creates a generated skill directory at
<skills-dir>/<name>/) - A path to a directory (symlinks
<skills-dir>/<name>/to that directory)
If a path is used, it is expected to contain one folder per
skill name, each containing a SKILL.md. Each top-level
skill entry is symlinked into <skills-dir>/, leaving
<skills-dir>/ itself as a normal directory so unmanaged
skills can coexist.
Home Manager manages skills under CODEX_HOME/skills
(typically ~/.codex/skills, or
~/.config/codex/skills when
home.preferXdgDirectories is enabled).
Type: (attribute set of (strings concatenated with “\n” or absolute path)) or absolute path
Default:
{ }
Example:
{
pdf-processing = ''
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
'';
data-analysis = ./skills/data-analysis;
}
Declared by: