Codexkit

Professional configuration kit for OpenAI Codex CLI — profiles, agents, skills, prompts, and context management.

What is Codexkit?

Codexkit is a complete, opinionated configuration kit for the OpenAI Codex CLI. It provides battle-tested profiles, structured prompts, reusable skills, lifecycle hooks, context management, and MCP integrations — everything you need to get the most out of Codex from day one. Drop it into any project and start shipping with a professional agent workflow.

Maintained by QuangThai.

Quick Start

Access Model

Codexkit can be distributed as a public npm package even if the source repository remains private. That means end users can install the packaged CLI from npm without GitHub repository access, while repository history and collaboration can remain private.

Preferred Install Flow

For a single project, the simplest installation path is:

# One-time on the machine
npm install -g codexkit

# Inside the project that should use Codexkit
cd /path/to/your-project
codexkit install

# Optional: create a project-local MCP env file
cp .codex/.env.example .codex/.env

# Start Codex from the target project
codexkit run

# If startup is noisy (MCP spinner/context7 churn), use clean mode
codexkit run-clean

If you are working directly from a source checkout, you can still clone the repo locally and run the shipped installers:

# Authorized user only
git clone git@github.com:QuangThai/codexkit.git
cd codexkit

# Inside any git repo you want to use with Codexkit
bash install/install-project.sh /path/to/your-project

# Optional: create a project-local MCP env file
cd /path/to/your-project
cp .codex/.env.example .codex/.env

# Start Codex from the target project
codexkit run

# Clean startup fallback (keeps hooks/DCG enabled)
codexkit run-clean

Project installs are self-contained by default; codexkit install --full-local remains only as a deprecated no-op for backward compatibility.

Remote Installer

Use the remote installer when you want to bootstrap from a prepared archive instead of npm or a local source checkout.

# From a local archive prepared by an authorized user
bash install/install-remote.sh --archive /path/to/codexkit.tar.gz /path/to/your-project

Packaged CLI

If you prefer a Git-based install from source instead of the public npm package, this flow still works for users who have repository access or a working auth token for Git-based npm installs.

# Install CLI
npm install -g github:QuangThai/codexkit#v1.0.9

# Inside any git repo you want to use with Codexkit
cd /path/to/your-project
codexkit install

# Verify from the target project
codexkit doctor

# Compact a completed bead into durable project context
codexkit bead-sync br-123

# Launch Codex with project-local MCP env
codexkit run --profile explore

# Clean startup fallback (keeps hooks/DCG enabled)
codexkit run-clean --profile explore

Important: codexkit install is the only supported install mode. It scaffolds the project into .codex/ and bootstraps prompt discovery into ~/.codex/prompts for the current user. MCP auth: keep project MCP secrets in .codex/.env and start Codex with codexkit run. Do not assume codex will auto-load project .env files by itself. No root env file: Codexkit does not use ./.env or ./.env.example for MCP bootstrap. The supported location is .codex/.env. Git-based access: GitHub-based npm installs and private archive flows still require repository or artifact access. The public npm package does not.

`codexkit run` vs `codex`

Use codexkit run as the default launch command when the project relies on MCP credentials from .codex/.env. The wrapper reads .codex/.env, exports those variables into the process environment, and then launches codex.

If you launch codex directly, the .codex/.env file may exist on disk but will not be loaded automatically unless you already export those variables through another mechanism such as your shell profile, direnv, or another env loader.

If you prefer typing codex, you can create an alias:

alias codex="codexkit run"

That keeps the familiar command name while preserving Codexkit's project-local env bootstrap behavior.

If you need a quiet startup while debugging warnings or MCP startup churn, use:

codexkit run-clean

run-clean keeps the same .codex/.env bootstrap, keeps hooks/DCG enabled, and disables context7 for that launch only.

codexkit doctor reports both validation and ownership:

full-local — the project keeps shared agents, prompts, and skills locally
patch inventory and duplicate/override counts for local shared files

codexkit bead-sync <id> compacts a bead's raw artifacts into .codex/memory/research/beads/<id>.md, so future work can reuse the durable summary without scanning raw .beads/artifacts/ trees first.

codexkit bead-close <id> --reason "..." syncs the bead summary, closes the bead, and flushes bead state in one step.

codexkit bead-search "<query>" --limit 3 ranks prior synced bead summaries and durable context docs so /create can pull forward the most relevant prior work.

codexkit bead-start <id> validates the bead PRD, claims the bead, and prepares the default execution branch.

codexkit bead-verify <id> --full runs project gates plus PRD Verify: commands and records a PASS stamp in .beads/verify.log.

Local Source Alternative

If you keep a local checkout of Codexkit, you can still install directly from it:

cd /path/to/your-project
bash /absolute/path/to/codexkit/install/install-project.sh

Distribution Policy

Codexkit can be published as a public npm package for the packaged CLI distribution path.
The source repository can remain private even when the npm package is public.
Public npm users do not need repository access.
Git-based installs from the repository still require repository read access or an equivalent credential.

Profiles

Six presets that configure model, sandbox, and approval policy:

Profile	Model	Sandbox	Approval	Use Case
`default`	gpt-5.5	workspace-write	on-request	Daily driver
`explore`	gpt-5.4-mini	read-only	never	Codebase understanding
`plan`	gpt-5.5	read-only	never	Architecture & planning
`build`	gpt-5.5	workspace-write	on-request	Implementation
`review`	gpt-5.5	read-only	never	Code review & audit
`ship`	gpt-5.5	workspace-write	on-request	Release & PR prep

# Use a profile
codex --profile explore "how does the auth system work?"
codex --profile build "implement the payments API"
codex --profile review "review the last 3 commits"

See docs/profiles.md for detailed descriptions and customization. docs/profiles.md#optional-tool-profiles-flywheel-mode.

Skills-First Workflows

Codexkit's primary workflow UX is now skills-first, aligned with current Codex guidance for reusable instructions.

Use:

$wf-feature-delivery <goal>
$wf-mission-orchestration <goal-or-plan-or-spec>

These skills preserve Codexkit's artifact-backed flow while avoiding reliance on custom prompt discovery.

Standard Development Flow

$wf-feature-delivery "<goal>"
  -> research/context
  -> bead + PRD
  -> readiness validation
  -> implementation + review
  -> verification

Mission Flow

$wf-mission-orchestration "<goal-or-plan-or-spec>"
  -> mission-spec.json
  -> mission runtime artifacts
  -> readiness validation
  -> mission control / workers
  -> milestone validation

Workflow Contracts (Native Baseline)

Codexkit now treats beads_rust + mission runtime artifacts as the primary execution contract:

br owns task lifecycle truth (create/claim/close/sync).
bv owns graph-aware triage and routing suggestions.
PRD affected_files defines default worker scope.
Mission scripts under .codex/scripts/mission_* own orchestration state transitions.
wf-* skills are primary operator entrypoints; /prompts:* stays as compatibility fallback.

Optional accelerators (CASS, CM, UBS from the flywheel toolchain) can improve speed and insight, but are not required for core mission/feature execution.

Prompts

41 legacy workflow prompt entry points — compatibility surfaces for users who still invoke /prompts:*.

Compatibility note: OpenAI now marks custom prompts as deprecated and recommends skills for reusable instructions. Codexkit still installs prompt files and bootstraps ~/.codex/prompts for backward compatibility, but /prompts:* autocomplete is no longer Codexkit's primary UX contract.

Category	Prompt	Purpose
Setup	`init`	Initialize project context (once per repo)
	`init-user`	Create user profile for personalization
	`init-context`	Set up planning context (project, roadmap, state)
Task Creation	`create`	Create task specification with requirements
	`plan`	Optional compatibility shim for durable `plan.md`
	`plan-refine`	Refine and iterate on an existing plan
	`plan-synthesis`	Synthesize multiple plans into a unified approach
	`research`	Optional compatibility shim for persisted research
Execution	`ship`	Implement + verify + review in one pass
	`verify`	Verify implementation correctness
	`review-codebase`	Structured code review
	`pr`	Prepare and create pull request
	`lfg`	Full autonomous: plan → ship → review → PR
	`autopilot`	Extended autonomous execution loop
	`swarm`	Multi-agent parallel execution
Bead Mgmt	`bead-convert`	Convert existing work into bead format
	`bead-polish`	Refine bead PRD before implementation
Design	`ui-inspire`	Search external UI references grounded in repo patterns
	`design`	UI/UX visual design with code output
	`ui-review`	Review UI/UX for quality and accessibility
	`ui-slop-check`	Audit for AI aesthetic fingerprints with actionable fixes
Session	`handoff`	Save progress and context for next session
	`resume`	Resume work from a previous session
	`status`	Show project status dashboard
	`compound`	Extract and persist learnings
	`search`	Search project memory and context for prior knowledge
	`dream`	Session consolidation and reflection
Mission	`mission`	Enter mission mode for multi-day projects
	`mission-create`	Create a new mission
	`mission-validate`	Validate mission readiness before orchestration
	`mission-plan`	Review or iterate on mission plan
	`mission-spec`	Define mission specifications
	`mission-start`	Start mission execution
	`mission-launch`	Launch mission workers
	`mission-control`	Orchestrate mission execution
	`mission-worker`	Manual/fallback worker surface for a running mission
	`mission-dashboard`	Mission progress dashboard
	`mission-status`	Check mission status
	`mission-intervene`	Pause, resume, redirect, or cancel a mission
	`mission-import`	Import external work into a mission

Legacy Standard Development Flow

/prompts:init     → Set up project context (once per repo)
     ↓
/prompts:create   → Specify a task with requirements
     ↓
/prompts:validate → Prove bead readiness before implementation
     ↓
/prompts:ship     → Implement + verify + review
     ↓
/prompts:verify   → Verify implementation correctness
     ↓
/prompts:pr       → Prepare and create pull request
     ↓
/prompts:compound → Extract and persist learnings

/prompts:create, /prompts:validate, /prompts:ship, and /prompts:verify auto-bootstrap beads state when .beads/ is missing.

/prompts:plan and /prompts:research still exist, but only as optional compatibility shims when you want persisted plan.md or research artifacts.

Legacy Quick Ship Flow

/prompts:ship    → Implement + verify + review in one pass
/prompts:lfg     → Full autonomous: plan → implement → verify → review → PR

Session Management

/prompts:handoff → Save progress for next session
/prompts:resume  → Resume from a previous session
/prompts:status  → Show project status dashboard

Mission Mode

Mission mode is Codexkit's answer to work that is too large for a single prompt, a single session, or a single agent. Instead of treating a complex project as "one giant ask plus some workers", it turns that project into a controlled execution system with explicit authority boundaries:

the user approves direction and gates
one orchestrator owns mission-level execution
workers implement scoped beads
validators check integrated reality
PRD affected_files define edit ownership by default
the bead graph remains the source of truth for what is actually ready

Use missions when the work spans multiple features, multiple sessions, or multiple collaborating agents. For a simple feature or bug fix, use $wf-feature-delivery directly. For a mission, the system stays stronger because planning, execution, validation, and handoff are all artifact-backed instead of being improvised from chat history.

Canonical operator path

$wf-mission-orchestration "<goal-or-plan-or-spec>"

Legacy prompt fallback:

/prompts:mission-start "<goal-or-plan-or-spec>"

That command is the default entrypoint when you want the system to start from whatever you currently have:

a raw goal
a markdown plan
an approved mission-spec.json

If you explicitly want the legacy collaborative planning loop before anything launches, use:

/prompts:mission "<goal>"

If the mission is already running and you want another worker terminal to join the live graph in manual/fallback mode, use:

/prompts:mission-worker <mission-id>

What missions give you

milestone-based orchestration instead of ad-hoc long-running sessions
deterministic mission creation from approved artifacts
graph-aware triage with bv and br
default worker scope via PRD affected_files + Codex native workers
parent-assigned worker packets by default, with mission-worker reserved for manual/fallback routing
local reservation helper support via .codex/scripts/bead_reservations.sh
explicit validation gates between milestones
replay-safe pause/resume/retry behavior

Artifact chain

goal
  -> approved plan + mission-spec.json
    -> mission creation
      -> mission.json + bead PRDs
        -> mission control / worker execution
          -> validation reports + dashboard artifacts
            -> compound / learned rules

If a mission phase cannot point to the artifact that proves it happened, that phase is not complete. This is the core difference between mission mode and an improvised swarm.

Execution model

Mission work follows the beads-native orchestrator sequence:

plan -> approve -> readiness -> triage -> claim -> scope(PRD affected_files) -> dispatch -> verify -> close -> validate -> compound

Per bead, the worker loop is narrower:

reserve scope -> read PRD -> re-check graph -> confirm affected_files scope -> implement -> verify -> release reservation -> report -> stop

This separation keeps mission authority with the orchestrator and keeps workers scoped to actual implementation.

Mission prompt surfaces

mission — planning and approval loop
mission-spec — produce mission-spec.json
mission-start — operator-friendly deterministic start from goal/plan/spec
mission-import — normalize external markdown into mission-spec.json
mission-create — materialize .missions/ and bead runtime artifacts
mission-validate — prove mission readiness before orchestration
mission-launch — deterministic create -> validate -> control launcher
mission-control — live orchestration for an active mission
mission-worker — manual/fallback worker-terminal entrypoint for a running mission
mission-dashboard / mission-status / mission-intervene — observability and control surfaces

Read this next

docs/mission-protocol.md — shortest complete contract
docs/mission-flywheel-runbook.md — practical live-tested sequence (legacy filename; native beads runtime content)
docs/missions.md — broader mission architecture
docs/mission-orchestration.md — orchestration and runtime details

See docs/prompts.md for full prompt descriptions.

Skills

98 reusable procedures — the "how" of your development process. Invoked with the $ prefix.

Category	Skill	Purpose
Planning	`$repo-orientation`	Understand codebase before working
	`$task-planning`	Goal-backward planning methodology
	`$writing-plans`	Zero-ambiguity plan creation with TDD
	`$executing-plans`	Wave-based parallel plan execution
	`$brainstorming`	Collaborative idea refinement
Implementation	`$safe-implementation`	TDD + deviation rules
	`$test-strategy`	Testing approach selection
	`$test-driven-development`	RED → GREEN → REFACTOR cycle
	`$testing-anti-patterns`	Avoid common testing mistakes
	`$frontend-design`	UI implementation patterns
	`$ui-inspiration-scout`	Codebase-grounded external UI scouting
Debugging	`$bug-triage`	Systematic bug investigation
	`$debugging`	Scientific debugging method
	`$systematic-debugging`	4-phase debug framework
	`$root-cause-tracing`	Trace bugs backward to source
Quality	`$code-review`	Review methodology with severity levels
	`$verification`	Goal-backward verification (3-level)
	`$refactoring`	Safe refactoring patterns
Session	`$docs-handoff`	Session handoff and resume
	`$session-management`	Session start/pause/resume lifecycle
	`$context-management`	Token budget and context health
	`$memory-system`	Memory search and observation creation
Release	`$git-pr-prep`	PR preparation and review gates
	`$dependency-upgrades`	Safe dependency update workflow
Task Tracking	`$beads`	Multi-agent task coordination with `br` CLI
	`$beads-bridge`	Beads + agent bridge for cross-session work
	`$prd`	Product Requirements Document creation
	`$prd-task`	PRD to executable JSON task conversion
	`$swarm-coordination`	Parallel agent orchestration patterns
Workflow	`$development-lifecycle`	Full feature lifecycle orchestration
	`$wf-feature-delivery`	Primary single-bead feature delivery flow
	`$wf-mission-orchestration`	Primary multi-feature mission flow
	`$finishing-a-development-branch`	Branch completion and merge workflow
	`$using-git-worktrees`	Git worktree isolation workflow
Research	`$deep-research`	Structured LSP exploration and analysis
Review	`$requesting-code-review`	Dispatch scoped review agents
	`$receiving-code-review`	Handle review feedback with rigor
	`$verification-before-completion`	Evidence-based completion verification

Skills can be chained: $task-planning → $safe-implementation → $verification

See docs/skills.md for detailed descriptions and how to create custom skills.

Patch Workflow

Codexkit can snapshot local overrides to managed core files and re-apply them after upgrades.

# From your project root
codexkit patch create "custom auth - Preserve local auth flow"
codexkit patch list
codexkit patch diff custom-auth

# Upgrade Codexkit, then re-apply all enabled patches
codexkit upgrade --auto-apply-patches

Each patch is stored under Codexkit_patches/<name>/ with:

patch.patch — unified diff against the managed Codexkit source file(s)
metadata.json — name, description, version, enabled state, and target files

Use codexkit patch disable <name> to keep a patch on disk without auto-applying it.

Plugins

Codexkit's plugin system is aligned with the Codex CLI native plugin architecture (v0.110.0+). Plugins are bundles of skills, MCP servers, hooks, and app definitions that Codex CLI discovers automatically.

# Install a plugin
codexkit plugin add git+https://github.com/user/my-plugin.git

# List installed plugins
codexkit plugin list

# Show plugin details
codexkit plugin info my-plugin

# Enable/disable without removing
codexkit plugin enable my-plugin
codexkit plugin disable my-plugin

Plugins install to $CODEX_HOME/plugins/cache/local/<name>/<version>/ with the native .codex-plugin/plugin.json manifest. The feature flag [features] plugins = true and config entry [plugins."name@local"] are managed automatically.

For marketplace support:

codexkit plugin marketplace init
codexkit plugin marketplace add my-plugin --category Productivity

To migrate legacy plugins (from ~/.codexkit/plugins/):

codexkit plugin migrate

See docs/plugins.md for the full plugin guide, plugin.json spec, and marketplace configuration.

Context Management

Codexkit maintains curated project knowledge in .codex/context/:

File	Purpose
`index.md`	Map of available docs (start here)
`architecture.md`	System boundaries and key modules
`conventions.md`	Coding norms and repo patterns
`current-priorities.md`	What matters right now
`decision-log.md`	Durable architecture decision records
`worklog.md`	Session-level human-readable trail
`gotchas.md`	Footguns, edge-cases, and known traps

The agent reads context/index.md at session start and updates worklog.md after significant milestones. This gives every session — and every new contributor — instant project context.

Memory Positioning

Codexkit's default memory model is:

Codex-native primitives such as AGENTS.md, config layering, history, codex resume, and compaction
native Codex memories enabled by [features].memories = true
repo-visible durable docs in .codex/context/ and .codex/memory/

Native memories are additive. Repo docs remain the source of truth for architecture, conventions, state, and decisions.

Optional MCP-backed memory is supported, but only as an additive retrieval layer. It should not replace repo-visible project knowledge.

See docs/memory.md for the default memory strategy and docs/memory-mcp.md for optional MCP-backed memory.

For maintenance, run:

bash .codex/scripts/audit_memory_hygiene.sh

This audits line budgets and boundary drift across worklog.md, decision-log.md, session-context.md, and state.md.

For lightweight local retrieval, run:

bash .codex/scripts/build_memory_index.sh
bash .codex/scripts/memory_search.sh "your query"

This index is derived from repo docs and is safe to rebuild or delete.

Hooks

Lifecycle automation scripts in .codex/hooks/:

Hook	Trigger
`session_start.sh`	At session startup/resume
`after_tool_use.sh`	After Bash tool invocation
`after_agent.sh`	After sub-agent completes
`pre_commit.sh`	Before git commit (validation)
`post_commit.sh`	After git commit
`pre_tool_use_dcg.sh`	Destructive Command Guard (pre-tool)
`mission_worker.sh`	Mission worker process lifecycle
`user_prompt_submit.sh`	On user prompt submission
`stop.sh`	At turn stop / session end hook

Codex hooks are configured in .codex/hooks.json and enabled in shipped Codexkit project config with [features].hooks = true. They can still be disabled by overriding that feature flag. See docs/hooks.md for details.

MCP Integrations

Opt-in external capabilities via Model Context Protocol:

Integration	Transport	Purpose
Tilth	stdio	AST-aware code navigation
Context7	HTTP	Library documentation lookup
Exa	HTTP	Web search and code examples
Ref	stdio	Documentation search and reading

Two-tier architecture:

Project-level (.codex/config.toml): Tilth only — no API keys needed
User-level (~/.codex/config.toml): Context7, Exa, Ref server definitions
Project env (.codex/.env): API keys loaded by codexkit run before codex starts

Example configs are in .codex/mcp/. Copy .codex/.env.example to .codex/.env, fill in the keys you need, then launch with codexkit run. See docs/mcp.md for setup guides and docs/memory-mcp.md for optional retrieval memory. For optional Flywheel coordination and one-shot onboarding, use the compatibility index:

docs/flywheel-compatibility.md

Project Structure

codexkit/
├── AGENTS.md                          # Operating rules (always loaded)
├── CLAUDE.md                          # Claude/Amp agent instructions
├── AGENTS.override.md.example         # Personal override template
├── README.md                          # This file
├── .gitignore
│
├── .codex/
│   ├── config.toml                    # Profiles, agents, hooks, MCP
│   ├── prompts/                       # 41 workflow prompts
│   │   ├── init.md
│   │   ├── init-user.md
│   │   ├── init-context.md
│   │   ├── create.md
│   │   ├── plan.md
│   │   ├── plan-refine.md
│   │   ├── plan-synthesis.md
│   │   ├── research.md
│   │   ├── ship.md
│   │   ├── verify.md
│   │   ├── review-codebase.md
│   │   ├── pr.md
│   │   ├── lfg.md
│   │   ├── autopilot.md
│   │   ├── swarm.md
│   │   ├── bead-convert.md
│   │   ├── bead-polish.md
│   │   ├── ui-inspire.md
│   │   ├── design.md
│   │   ├── ui-review.md
│   │   ├── ui-slop-check.md
│   │   ├── handoff.md
│   │   ├── resume.md
│   │   ├── status.md
│   │   ├── compound.md
│   │   ├── search.md
│   │   ├── dream.md
│   │   ├── mission.md
│   │   ├── mission-create.md
│   │   ├── mission-validate.md
│   │   ├── mission-plan.md
│   │   ├── mission-spec.md
│   │   ├── mission-start.md
│   │   ├── mission-launch.md
│   │   ├── mission-control.md
│   │   ├── mission-worker.md
│   │   ├── mission-dashboard.md
│   │   ├── mission-status.md
│   │   ├── mission-intervene.md
│   │   └── mission-import.md
│   ├── agents/                        # 11 agent definitions
│   │   ├── planner.toml
│   │   ├── reviewer.toml
│   │   ├── shipper.toml
│   │   ├── scout.toml
│   │   ├── vision.toml
│   │   ├── debugger.toml
│   │   ├── refactorer.toml
│   │   ├── builder.toml
│   │   ├── runner.toml
│   │   ├── general.toml
│   │   └── painter.toml
│   ├── context/                       # 8 curated project knowledge files
│   │   ├── index.md
│   │   ├── architecture.md
│   │   ├── conventions.md
│   │   ├── current-priorities.md
│   │   ├── decision-log.md
│   │   ├── worklog.md
│   │   ├── gotchas.md
│   │   └── session-context.md
│   ├── skills/                        # 98 canonical reusable skills
│   │   ├── repo-orientation/
│   │   ├── task-planning/
│   │   ├── safe-implementation/
│   │   ├── verification/
│   │   └── ...
│   ├── hooks/                         # 9 lifecycle scripts
│   │   ├── README.md
│   │   ├── session_start.sh
│   │   ├── after_tool_use.sh
│   │   ├── after_agent.sh
│   │   ├── pre_commit.sh
│   │   ├── post_commit.sh
│   │   ├── pre_tool_use_dcg.sh
│   │   ├── mission_worker.sh
│   │   ├── user_prompt_submit.sh
│   │   └── stop.sh
│   ├── scripts/                       # Utility scripts
│   │   ├── build_startup_brief.sh
│   │   ├── append_worklog.sh
│   │   └── detect_changed_files.sh
│   └── mcp/                           # MCP server examples
│       ├── README.md
│       ├── tilth.toml.example
│       ├── context7.toml.example
│       ├── exa.toml.example
│       └── ref.toml.example
├── install/                           # Installers
│   ├── install-project.sh             # Install to .codex/ (project-level)
│   ├── install-remote.sh              # Download + install into current repo
│   └── validate.sh                    # Validate installation
├── bin/
│   └── codexkit                       # Packaged CLI entrypoint
│
├── templates/                         # Scaffolding templates
│   ├── global/
│   │   ├── README.md
│   │   └── AGENTS.override.md
│   └── project/
│       ├── README.md
│       ├── .codex-config-template.toml
│       └── AGENTS.md.template
│
├── docs/                              # Documentation
│   ├── architecture.md
│   ├── compaction-guide.md
│   ├── config-reference.md
│   ├── dcp-guidance.md
│   ├── hooks.md
│   ├── mcp-advanced.md
│   ├── mcp.md
│   ├── memory-mcp.md
│   ├── memory.md
│   ├── migration-legacy.md
│   ├── migration-map.md
│   ├── plan-storage.md
│   ├── profiles.md
│   ├── agents.md
│   ├── skills.md
│   ├── prompts.md
│   ├── release-checklist.md
│   ├── troubleshooting.md
│   └── tui-configuration.md
│
└── tests/                             # Tests
    ├── run_release_gate.sh            # Release-grade full gate runner
    ├── smoke/
    │   ├── test_structure.sh
    │   └── test_scripts.sh
    └── integration/
        ├── test_bead_close_idempotency.sh
        ├── test_bead_context_search.sh
        ├── test_cli.sh
        ├── test_create_prior_related_work.sh
        ├── test_install.sh
        ├── test_hooks.sh
        ├── test_inventory_consistency.sh
        ├── test_memory_runtime.sh
        ├── test_patch.sh
        ├── test_profiles.sh
        ├── test_remote_install.sh
        ├── test_docs_behavior.sh
        ├── test_docs_inventory.sh
        ├── test_docs_policy.sh
        ├── test_prompt_agent_contracts.sh
        ├── test_prompt_inventory.sh
        ├── test_release_process.sh
        ├── test_skill_catalog.sh
        ├── test_start_ship_verify_e2e.sh
        ├── test_start_workflow.sh
        ├── test_verify_workflow.sh
        └── test_workflow_runtime.sh

Verification

Run the whole shipped verification suite:

bash tests/run_release_gate.sh

The release gate covers:

structure and executable scripts
prompt quality, agent quality, docs consistency, and inventory consistency
install workflow, packaged CLI install, remote installer, and beads-backed runtime workflow
release process validation and project wiring

Customization

Adding a Custom Profile

Edit ~/.codex/config.toml (user-level):

[profiles.my-custom]
model = "gpt-5.5"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Adding a Custom Skill

mkdir -p .codex/skills/my-skill/

Create .codex/skills/my-skill/SKILL.md with YAML frontmatter:

---
name: my-skill
description: What this skill does
trigger: When to activate this skill
---

# My Skill

## Steps

1. ...

Personal Overrides

Copy AGENTS.override.md.example to AGENTS.override.md (gitignored) to add personal instructions that layer on top of the base AGENTS.md.

Migration from Prior Frameworks

If you're migrating from a prior agent framework, see docs/migration-map.md for a complete mapping of old → new file locations, renamed concepts, and upgrade steps.

Contributing

Fork the repo
Create a feature branch (git checkout -b feat/my-feature)
Make your changes — follow the conventions in AGENTS.md
Open a pull request

Please keep changes focused and well-scoped. One PR per concern.

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.codex		.codex
bin		bin
docs		docs
install		install
templates/project		templates/project
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.template-manifest.json		.template-manifest.json
AGENTS.md		AGENTS.md
AGENTS.override.md.example		AGENTS.override.md.example
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
codexkit-1.0.0.tgz		codexkit-1.0.0.tgz
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Codexkit

What is Codexkit?

Quick Start

Access Model

Preferred Install Flow

Remote Installer

Packaged CLI

codexkit run vs codex

Local Source Alternative

Distribution Policy

Profiles

Skills-First Workflows

Standard Development Flow

Mission Flow

Workflow Contracts (Native Baseline)

Prompts

Legacy Standard Development Flow

Legacy Quick Ship Flow

Session Management

Mission Mode

Skills

Patch Workflow

Plugins

Context Management

Memory Positioning

Hooks

MCP Integrations

Project Structure

Verification

Customization

Adding a Custom Profile

Adding a Custom Skill

Personal Overrides

Migration from Prior Frameworks

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`codexkit run` vs `codex`

Packages