Skip to content

Commit 80791e2

Browse files
DivitMittalDivitMittal
committed
feat(ai): add modular codex CLI home-manager configuration
Add comprehensive Codex CLI configuration following the same patterns as claude and opencode configurations: - modules/home/codex.nix: Custom module for skills and prompts options (not in upstream home-manager) - home/ai/repl/codex/: Modular configuration split into: - default.nix: Entry point with package and enable - settings.nix: Core settings (model, sandbox, profiles) - mcp-servers.nix: MCP server configurations - custom-instructions.nix: Global rules (git, security, docs) - skills.nix: Reusable knowledge modules - prompts.nix: Custom prompts for common workflows - Export claude-code and codex modules in modules/default.nix
1 parent f49f1ed commit 80791e2

File tree

8 files changed

+632
-0
lines changed

8 files changed

+632
-0
lines changed

‎home/ai/repl/codex/custom-instructions.nix‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
_: {
2+
programs.codex.custom-instructions = ''
3+
## External File Loading
4+
5+
CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
6+
7+
Instructions:
8+
9+
- Do NOT preemptively load all references - use lazy loading based on actual need
10+
- When loaded, treat content as mandatory instructions that override defaults
11+
- Follow references recursively when needed
12+
13+
## Git Workflow Rules
14+
15+
### Commits
16+
- Use Conventional Commits format: `type(scope): description`
17+
- Keep commits atomic (one logical change per commit)
18+
- Write imperative mood ("add feature" not "added feature")
19+
- Reference issues when applicable: `fixes #123`
20+
21+
### Branches
22+
- `main` is protected - never force push
23+
- Feature branches: `feat/description`
24+
- Fix branches: `fix/issue-number` or `fix/description`
25+
- Keep branches short-lived
26+
27+
### Before Committing
28+
- Run `nix fmt` on changed Nix files
29+
- Run `nix flake check` for Nix projects
30+
- Review diff before staging
31+
32+
## Security Rules
33+
34+
### Secrets
35+
- NEVER commit secrets, API keys, passwords, or tokens
36+
- Use agenix/ragenix for encrypted secrets
37+
- Check `.env` files are in `.gitignore`
38+
- Audit file permissions for sensitive data
39+
40+
### Code
41+
- Validate all external input
42+
- Use parameterized queries (no string interpolation for commands)
43+
- Prefer allowlists over denylists
44+
- Log security events but never log secrets
45+
46+
### Nix Specific
47+
- Use `lib.escapeShellArg` for shell arguments
48+
- Avoid `builtins.fetchurl` without hash
49+
- Review systemd service sandboxing options
50+
- Check firewall rules for exposed services
51+
52+
## Documentation Rules
53+
54+
### Comments
55+
- Explain "why" not "what"
56+
- Document non-obvious behavior
57+
- Keep comments up-to-date with code
58+
- Use `## Section` comments to organize long files
59+
60+
### README
61+
- Include: purpose, installation, usage, configuration
62+
- Keep examples working and tested
63+
- Document environment requirements
64+
65+
### Nix Modules
66+
- Add `description` to all `mkOption`
67+
- Document module dependencies
68+
- Include usage examples in comments
69+
70+
## Code Quality Rules
71+
72+
### General
73+
- Prefer pure functions over side effects
74+
- Keep functions small and focused
75+
- Avoid deep nesting (max 3-4 levels)
76+
- Use early returns to reduce indentation
77+
78+
### Error Handling
79+
- Handle errors explicitly
80+
- Provide helpful error messages
81+
- Fail fast and loud in development
82+
- Never silently swallow errors
83+
84+
### Nix Specific
85+
- Use `lib.mkMerge` for complex conditional configs
86+
- Prefer `lib.optionalAttrs` over `if-then-else {}`
87+
- Use `lib.filterAttrs` to remove null/empty values
88+
- Avoid `with` - use explicit `lib.` prefix
89+
90+
### Type Safety
91+
- Never use `as any` or `@ts-ignore` (TypeScript)
92+
- Define proper types for all function parameters
93+
- Use `lib.types.*` for Nix module options
94+
'';
95+
}

‎home/ai/repl/codex/default.nix‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
pkgs,
3+
lib,
4+
...
5+
}: {
6+
imports = lib.custom.scanPaths ./.;
7+
8+
home.packages = lib.attrsets.attrValues {
9+
inherit (pkgs.ai) ccusage-codex;
10+
};
11+
12+
programs.codex = let
13+
# package = pkgs.ai.codex;
14+
package = pkgs.writeShellScriptBin "codex" ''
15+
exec ${pkgs.pnpm}/bin/pnpm dlx @openai/codex "$@"
16+
'';
17+
in {
18+
enable = true;
19+
inherit package;
20+
};
21+
}

‎home/ai/repl/codex/mcp-servers.nix‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{pkgs, ...}: let
2+
pnpmCommand = "${pkgs.pnpm}/bin/pnpm";
3+
in {
4+
programs.codex.settings.mcp_servers = {
5+
sequential-thinking = {
6+
type = "stdio";
7+
command = pnpmCommand;
8+
args = ["dlx" "@modelcontextprotocol/server-sequential-thinking"];
9+
};
10+
deepwiki = {
11+
type = "http";
12+
url = "https://mcp.deepwiki.com/mcp";
13+
};
14+
octocode = {
15+
type = "stdio";
16+
command = pnpmCommand;
17+
args = ["dlx" "octocode-mcp@latest"];
18+
};
19+
exa = {
20+
type = "stdio";
21+
command = pnpmCommand;
22+
args = ["dlx" "exa-mcp-server"];
23+
};
24+
};
25+
}

‎home/ai/repl/codex/prompts.nix‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
_: {
2+
programs.codex.prompts = {
3+
## Git workflows
4+
commit = ''
5+
---
6+
description: Create git commit(s) with proper message(s)
7+
argument-hint: [files-or-scope]
8+
---
9+
## Context
10+
11+
- Current git status: !`git status`
12+
- Current git diff: !`git diff HEAD`
13+
- Recent commits: !`git log --oneline -5`
14+
15+
## Task
16+
17+
Analyze the changes and create commit(s) based on the context:
18+
19+
1. **Multiple commits when**:
20+
- Changes span multiple logical concerns (e.g., feature + refactor + docs)
21+
- Changes affect unrelated components or modules
22+
- User explicitly requests multiple commits or groups of changes
23+
24+
2. **Single commit when**:
25+
- All changes relate to a single logical unit of work
26+
- User specifies a single context or scope
27+
- Changes form one cohesive story
28+
29+
3. **Context-limited commits**:
30+
- If instructed to commit specific files/paths, ONLY stage and commit those files
31+
- Respect explicit scope boundaries provided by the user
32+
- Do NOT include unrelated staged or unstaged changes
33+
34+
Each commit message MUST follow Conventional Commits syntax: `type(scope): description`
35+
'';
36+
37+
pr = ''
38+
---
39+
description: Create a pull request with description
40+
argument-hint: [title]
41+
---
42+
## Context
43+
44+
- Current branch: !`git branch --show-current`
45+
- Default branch: !`gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main"`
46+
- Commits not in main: !`git log main..HEAD --oneline 2>/dev/null || git log origin/main..HEAD --oneline 2>/dev/null`
47+
- Changed files: !`git diff main..HEAD --stat 2>/dev/null || git diff origin/main..HEAD --stat 2>/dev/null`
48+
49+
## Task
50+
51+
Create a pull request:
52+
1. Check if PR already exists for this branch (skip if so, show URL)
53+
2. Push current branch to origin if not already pushed: `git push -u origin HEAD`
54+
3. Create PR with title from $ARGUMENTS or infer from commits/branch name
55+
4. Use this description template:
56+
57+
```
58+
## Summary
59+
<brief description of changes>
60+
61+
## Changes
62+
- <bullet points of key changes>
63+
64+
## Testing
65+
<how to test, or "N/A" if not applicable>
66+
```
67+
'';
68+
69+
changelog = ''
70+
---
71+
description: Update CHANGELOG.md with new entry
72+
argument-hint: [version]
73+
---
74+
## Context
75+
76+
- Recent commits: !`git log --oneline -20`
77+
- Current changelog: !`head -50 CHANGELOG.md 2>/dev/null || echo "No CHANGELOG.md found"`
78+
79+
## Task
80+
81+
Update CHANGELOG.md following Keep a Changelog format:
82+
1. Group changes by type (Added, Changed, Fixed, Removed)
83+
2. Reference relevant commits/PRs
84+
3. Use the provided version or determine appropriate version bump
85+
'';
86+
87+
fix-issue = ''
88+
---
89+
description: Fix a GitHub issue
90+
argument-hint: <issue-number>
91+
---
92+
## Context
93+
94+
- Issue details: !`gh issue view $ARGUMENTS 2>/dev/null || echo "Could not fetch issue"`
95+
96+
## Task
97+
98+
1. Understand the issue from the description and comments
99+
2. Create a branch named fix/$ARGUMENTS or feature/$ARGUMENTS
100+
3. Implement the fix following project conventions
101+
4. Test the changes if applicable
102+
5. Commit with message referencing the issue (e.g., "fix: description (closes #$ARGUMENTS)")
103+
'';
104+
105+
## Code quality
106+
review = ''
107+
---
108+
description: Review code for issues
109+
argument-hint: [file-or-path]
110+
---
111+
## Context
112+
113+
- Files to review: $ARGUMENTS or staged changes
114+
- Diff: !`git diff --cached --stat 2>/dev/null || git diff HEAD --stat`
115+
116+
## Task
117+
118+
Review the code for:
119+
1. **Bugs**: Logic errors, edge cases, null checks
120+
2. **Security**: Input validation, secrets, injection
121+
3. **Performance**: Unnecessary work, memory leaks
122+
4. **Style**: Naming, complexity, documentation
123+
124+
Output format:
125+
- 🔴 Critical (must fix)
126+
- 🟡 Warning (should fix)
127+
- 🟢 Suggestion (nice to have)
128+
'';
129+
130+
refactor = ''
131+
---
132+
description: Refactor code while preserving behavior
133+
argument-hint: <file-or-symbol>
134+
---
135+
## Task
136+
137+
Refactor $ARGUMENTS to improve:
138+
- Maintainability
139+
- Remove duplication
140+
- Simplify complex logic
141+
- Improve naming
142+
143+
Rules:
144+
- Preserve existing behavior exactly
145+
- Make small, incremental changes
146+
- Keep changes reviewable
147+
'';
148+
149+
## Documentation
150+
explain = ''
151+
---
152+
description: Explain code in detail
153+
argument-hint: <file-or-symbol>
154+
---
155+
Read and explain $ARGUMENTS:
156+
1. Purpose and responsibility
157+
2. How it works (high-level flow)
158+
3. Key dependencies and interactions
159+
4. Important edge cases or gotchas
160+
'';
161+
162+
doc = ''
163+
---
164+
description: Generate or improve documentation
165+
argument-hint: <file-or-symbol>
166+
---
167+
## Task
168+
169+
Document $ARGUMENTS:
170+
- Add/update inline comments for complex logic
171+
- Add/update function/module documentation
172+
- Follow existing documentation style in codebase
173+
174+
For Nix:
175+
- Add `description` to mkOption
176+
- Add comments for non-obvious configuration
177+
'';
178+
179+
## Quick actions
180+
test = ''
181+
---
182+
description: Run project tests
183+
---
184+
Detect and run tests:
185+
- Nix: `nix flake check`
186+
- Node: `npm test`
187+
- Python: `pytest`
188+
- Rust: `cargo test`
189+
190+
Report results and any failures.
191+
'';
192+
193+
build = ''
194+
---
195+
description: Build the project
196+
---
197+
Detect and build:
198+
- Nix flake: `nix build`
199+
- Nix darwin: `darwin-rebuild build --flake .`
200+
- Node: `npm run build`
201+
- Rust: `cargo build`
202+
203+
Report success or errors.
204+
'';
205+
206+
clean = ''
207+
---
208+
description: Clean build artifacts and caches
209+
---
210+
Clean up:
211+
1. Git ignored files (with confirmation)
212+
2. Nix result symlinks
213+
3. Build caches (node_modules/.cache, __pycache__, target/)
214+
215+
Ask before deleting anything significant.
216+
'';
217+
};
218+
}

0 commit comments

Comments
 (0)