Codex Starter Kit

Codex Starter Kit

A ready-to-use baseline for OpenAI Codex CLI: agents, skills, hooks, MCP, plugins, and global AGENTS.md.

Install it once, restart Codex, and get a practical working setup for development, review, QA, DevOps, design, product, data, and security work.

English · Русская версия

GitHub Repository · Telegram: @pomogay_marketing

What This Is

codex-starter-kit turns a clean Codex CLI setup into a ready working environment.

It includes:

• 62 custom Codex agents in agents/*.toml
• 101 reusable skills in skills/*/SKILL.md
• global Codex working rules in templates/AGENTS.md
• a shell safety hook for risky commands
• default command approval rules in rules/default.rules
• a baseline ~/.codex/config.toml with GitHub plus bundled local Superpowers and Claude Companion plugins
• public docs MCP servers: Context7, Vue, Nuxt UI, and Nuxt
• recommended local MCP routes for Serena, GitNexus, Postgres, Open Design, and claude-mem
• bundled VKirill/superpowers fork in plugins/superpowers
• repo-local Claude Companion plugin prototype in plugins/claude-companion for interactive Claude Code reviews through tmux
• an installer with --dry-run, backups, runtime refresh, and validation

The point is simple: you do not rebuild a Codex workflow from scratch. Install the baseline, verify it, then keep project-specific rules in each repository's local AGENTS.md.

Fast Path

If you want Codex to install this kit for you, open Codex on the target machine and paste this prompt.

Install Codex Starter Kit for OpenAI Codex CLI and verify that the installation is safe.

Repository:
https://github.com/VKirill/codex-starter-kit

Goal:
- make this starter kit the baseline Codex setup on this machine
- install global ~/.codex/AGENTS.md from templates/AGENTS.md
- install custom agents into ~/.codex/agents
- install skills into ~/.agents/skills
- install safety hooks into ~/.codex/hooks and ~/.codex/hooks.json
- install safe command approval rules into ~/.codex/rules
- install the recommended ~/.codex/config.toml from templates/config.recommended.toml
- enable GitHub plus bundled local Superpowers and Claude Companion plugin entries through config.toml
- enable public docs MCP servers for Context7, Vue, Nuxt UI, and Nuxt
- check and document recommended local MCP/plugin routes for Serena, GitNexus, Postgres, Open Design, and claude-mem
- perform full local workflow self-setup when safe: Serena, GitNexus, and claude-mem
- enable Claude Companion only when Claude Code CLI is already installed; do not install Claude or tmux automatically
- include GitHub/source links for every enabled plugin and recommended MCP/plugin route
- preserve old files with timestamped .bak-* backups

Work step by step:
1. If the repository is missing, clone it into ~/projects/codex-starter-kit.
2. If the repository already exists, enter it and check the current git status.
3. Read README.md, install.py, and templates/config.recommended.toml.
4. Run the pack validation:
   python3 scripts/validate-pack.py
5. Run a dry run:
   ./install.sh --dry-run
6. Show me which paths will be replaced, then count agents and skills separately.
7. If the dry run looks safe, run the install with backups:
   ./install.sh
8. Verify that ~/.codex/config.toml contains GitHub, superpowers@codex-starter-kit, and claude-companion@codex-starter-kit plugins, plus MCP servers context7, vue-docs, nuxt-ui-remote, and nuxt-remote.
9. Report that Serena, GitNexus, Postgres, Open Design, and claude-mem are recommended local/plugin routes for the full starter-kit workflow.
10. For each enabled plugin and recommended MCP/plugin route, show its GitHub/source link from README.md or templates/config.recommended.toml.
11. Run full local workflow preflight:
   - detect OS and package manager: apt, dnf, pacman, zypper, brew, or none
   - check commands: tmux, claude, uv, uvx, node, npm, npx, gitnexus
   - check Codex runtime: codex, `codex plugin marketplace upgrade`, `codex mcp list`
   - report missing tools before installing anything
12. If Claude Code CLI is missing, do not install Claude and do not install tmux for Claude Companion. Report that Claude Companion is disabled on this machine until the user installs and authenticates Claude Code manually.
13. If Claude Code CLI exists, verify it with `claude --version`. Then check tmux. If tmux is missing, do not install it automatically; show the manual install command for the detected package manager:
   - Ubuntu/Debian: `sudo apt-get update && sudo apt-get install -y tmux`
   - Fedora/RHEL: `sudo dnf install -y tmux`
   - Arch: `sudo pacman -S --needed tmux`
   - openSUSE: `sudo zypper install -y tmux`
   - macOS: `brew install tmux`
14. Do not read, copy, parse, print, or move Claude credentials. Use Claude Code's own authentication flow only. If Claude is installed but not authenticated, open an interactive `claude` session and ask the user to run `/login`; then re-check. Do not inspect `~/.claude/.credentials.json`, cookies, keychains, bearer tokens, or API keys.
15. If uv/uvx is missing and Serena is requested or absent, install uv after approval using the official Astral installer or the system package manager. Then install and initialize Serena:
   `uv tool install -p 3.13 serena-agent@latest --prerelease=allow`
   `serena init`
   Verify that `serena` is on PATH. Do not hardcode private ports or bearer tokens in public starter-kit files.
16. If GitNexus is missing, install or use it after approval:
   `npm install -g gitnexus`
   or for one-off MCP use:
   `npx -y gitnexus@latest mcp`
   Then run safe checks: `gitnexus --help`, `gitnexus status` in the current repo if applicable. Ask before indexing large repositories. If the user approves indexing this starter-kit repo, run `gitnexus analyze` from the repo root.
17. If claude-mem is missing and the user wants memory continuity, install it after approval:
   `npx claude-mem@latest install`
   Then restart Codex and verify available MCP/tools if safe. If install fails or appears unstable, report the failure and leave it disabled.
18. If recommended local MCP/plugin routes are already installed and safe to verify, check them with `codex mcp list` or their own read-only status command. Do not write private ports, local paths, bearer tokens, or database credentials into public starter-kit files.
19. If the codex command is available, run:
   codex plugin marketplace upgrade
   codex mcp list
20. Validate installed agents:
   ./install.sh --validate-only
21. At the end, briefly summarize what changed, where backups were written, which tools were installed, which recommended MCP/plugin routes are active or missing, what still needs manual login, and that Codex must be restarted.

Safety rules:
- do not delete ~/.codex, ~/.agents, or existing agents/skills without backups
- do not use --force or --no-backup without my explicit approval
- do not copy secrets, bearer tokens, private MCP settings, or local database credentials
- do not install Claude Code or tmux automatically; Claude Companion is opt-in for machines where Claude already exists
- do not read Claude credentials directly; always delegate authentication to Claude Code
- ask before sudo, package-manager installs, global npm installs, `curl | sh`, large repo indexing, daemon startup, or service changes
- prefer read-only checks before mutation; if an install fails, stop and show the smallest safe fix
- if a command needs elevated access or network approval, explain why first
- if a check fails, stop, show the error, and suggest the smallest safe fix

Manual Install

Clone the repository:

git clone https://github.com/VKirill/codex-starter-kit ~/projects/codex-starter-kit
cd ~/projects/codex-starter-kit

Validate the pack:

python3 scripts/validate-pack.py

Preview what the installer will replace:

./install.sh --dry-run

Install the baseline with backups:

./install.sh

Validate installed agents:

./install.sh --validate-only

Restart Codex after installation. Global instructions, agents, skills, hooks, and plugins may not load until the next Codex session.

What Gets Installed

| Path | What goes there | Why | | --- | --- | --- | | ~/.codex/AGENTS.md | global working rules | consistent Codex behavior across projects | | ~/.codex/agents/ | 62 custom subagents | roles for development, review, QA, DevOps, product, design, and copywriting | | ~/.agents/skills/ | 101 skills | reusable instructions for tasks and domains | | ~/.codex/hooks/ | safety and handoff hook scripts | classifies user prompts, guards risky shell commands, auto-approves known safe permission prompts, and nudges verification after installs/failures | | ~/.codex/hooks.json | hook config | connects UserPromptSubmit, PermissionRequest, PreToolUse, and PostToolUse hooks to Codex | | ~/.codex/rules/ | command approval rules | auto-approves common read-only development, Linux, package metadata, and diagnostics commands | | ~/.codex/config.toml | baseline config | plugins, MCP servers, approvals, docs discovery |

By default, the installer replaces managed paths only after moving existing files to timestamped .bak-* backups.

Agent Map

Agents live in agents/*.toml. Each agent has a narrow role, its own model_reasoning_effort, nickname candidates, and a focused skill set.

| Category | Use it for | Agents | | --- | --- | --- | | | handoff intake scoring, task ledgers, planning, workflows, coordination | agents_orchestrator, project_manager_senior, specialized_workflow_architect, automation_governance_architect | | | backend, frontend, mobile, CMS, architecture, code | engineering_backend_architect, engineering_frontend_developer, engineering_senior_developer, engineering_software_architect, engineering_minimal_change_engineer, engineering_rapid_prototyper, engineering_mobile_app_builder, engineering_cms_developer, engineering_codebase_onboarding_engineer, engineering_code_reviewer, engineering_technical_writer, engineering_git_workflow_master, lsp_index_engineer, terminal_integration_specialist, specialized_mcp_builder, specialized_developer_advocate | | | ML, data pipelines, databases, email/audio intelligence | engineering_ai_engineer, engineering_ai_data_remediation_engineer, engineering_data_engineer, engineering_database_optimizer, engineering_email_intelligence_engineer, engineering_voice_ai_integration_engineer, specialized_model_qa | | | infrastructure, incidents, security, compliance | engineering_devops_automator, engineering_sre, engineering_security_engineer, engineering_threat_detection_engineer, engineering_incident_response_commander, engineering_autonomous_optimization_architect, compliance_auditor | | | checks, evidence, accessibility, performance | testing_api_tester, testing_evidence_collector, testing_accessibility_auditor, testing_performance_benchmarker, testing_reality_checker, testing_tool_evaluator, testing_test_results_analyzer, testing_workflow_optimizer | | | roadmaps, feedback, sprints, experiments, delivery | product_manager, product_feedback_synthesizer, product_trend_researcher, product_sprint_prioritizer, product_behavioral_nudge_engine, project_management_project_shepherd, project_management_experiment_tracker, project_management_jira_workflow_steward, project_management_studio_operations, project_management_studio_producer | | | UI, UX, brand, visuals, research | design_ui_designer, design_ux_architect, design_ux_researcher, design_brand_guardian, design_visual_storyteller, design_image_prompt_engineer, design_inclusive_visuals_specialist, design_whimsy_injector | | | knowledge bases, notes, cross-domain reasoning | zk_steward |

Skill Groups

Skills live in skills/. The installer copies them to ~/.agents/skills, where agents can use them for sharper task behavior.

| Group | Examples | | --- | --- | | Process | planning-methodology, task-decomposition, testing-patterns, bug-hunter, code-review-checklist | | Frontend | frontend-developer, react-patterns, nextjs-best-practices, vue-developer, ui-designer, playwright-skill | | Backend | nodejs-expert, fastify-pro, fastapi-pro, api-patterns, auth-implementation-patterns, graphql | | Data | postgresql, database-design, prisma-expert, drizzle-orm-expert, redis-patterns, data-engineer | | Ops | docker-expert, terraform-specialist, linux-sysadmin, github-actions-templates, server-management | | Security | security-audit, backend-security-coder, find-bugs, incident-responder | | Product and Docs | copywriter, ru-text, roadmap-methodology, goal-achievement-review, software-architecture |

Subagents use role-based allowlist emulation through [[skills.config]] enabled = false, so each role sees a focused skill menu instead of the whole library.

Safety Model

The installer runs in baseline mode: it makes this starter kit the main Codex setup on the machine.

Default safeguards:

• ./install.sh --dry-run previews replacements without writing
• old managed paths are moved to timestamped .bak-* backups
• agent TOML files are validated after install
• skills.config paths are rewritten for your home directory
• codex plugin marketplace upgrade and codex mcp list run only when codex is available in PATH
• the local codex-starter-kit plugin marketplace is registered dynamically from the install path, and bundled plugins such as superpowers@codex-starter-kit and claude-companion@codex-starter-kit are enabled when their metadata exists
• bundled local plugins are also copied into the Codex plugin cache, so their skills are visible in new Codex sessions without a separate manual install step
• rules/default.rules reduces routine approval prompts for read-only commands such as package metadata checks, Linux inspection commands, service status checks, Docker/Kubernetes/Terraform read-only inspection, and GitHub CLI view/list commands
• The baseline uses approval_policy = "never" with workspace-write for full trusted auto-edit handoff flow; critical commands still go through rules/hooks.
• Recoverable deletion with gio trash is auto-approved. Permanent deletion commands such as rm, rmdir, and unlink remain blocked.
• cp is auto-approved for autonomous handoff file-copy workflows; sandbox scope and safety hooks still constrain where it can write.
• printf, python, python3, and broad pnpm commands are auto-approved for autonomous handoff workflows; critical mutations such as package publish/deploy/release remain blocked by the safety hook.
• npm workspace forms (npm --workspace, npm -w, npm --workspaces, npm --prefix) and pnpm workspace forms (pnpm --filter, pnpm -F, pnpm --recursive, pnpm -r, pnpm --dir, pnpm -C) are approved for handoff development workflows
• hooks/handoff-intake-classifier.py classifies user prompts on UserPromptSubmit only when ~/.codex/private/handoff-classifier.env exists. With that private file present, it works offline with deterministic fallback and uses the LLM as the primary classifier when OPENAI_API_KEY and HANDOFF_CLASSIFIER_MODEL are set. The LLM path requests strict Responses API Structured Outputs (text.format JSON Schema) and normalizes typed booleans such as should_edit, requires_release_flow, requires_worktree_gate, and requires_gitnexus_impact; plain JSON parsing remains only as a compatibility fallback. The rendered hook context is compact English.
• For implementation prompts, the classifier emits a normalized engineering brief with professional architecture vocabulary and, when Codex provides a working directory, a compact repo profile from root and

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VKirill
• Source: VKirill/codex-starter-kit
• License: MIT
• Homepage: https://github.com/VKirill/codex-starter-kit

Install and usage instructions live in the source repository linked above.