Skip to content
/
Tier B A13 Methodology

ACT-House-Engineering/codex-starter

codex-starter-acthouse · ACT-House-Engineering/codex-starter · ★ 3 · last commit 2025-08-09

Minimal OpenAI Codex starter with a container setup script, AGENTS.md behavioral guide, and reference docs for code quality workflows (twelve-factor, pragmatic programmer).

Best whenCodex tasks should reference named methodology documents (twelve-factor.md, pragmatic.md) as grounding material for code improvement prompts.
Skip ifVery opinionated AGENTS.md rules
vs seeds
Does not fit any seed archetype — the only OpenAI Codex (cloud agent) starter in the batch vs all seeds targeting Claude Code or I…
Primitive shape
No installable primitives
00

Summary

ACT-House-Engineering/codex-starter — Summary

ACT-House-Engineering/codex-starter is a minimal OpenAI Codex (not Claude Code) starter template providing a setup script, AGENTS.md behavioral guide, and prompt examples for use with OpenAI's Codex cloud environment. It is the only framework in this batch explicitly targeting OpenAI Codex rather than Claude Code. The setup-codex.sh script is intended to be pasted into the Codex environment's "Setup script" field, not run locally. It installs pnpm, sets up fake .env.local values for CI, and runs pnpm install --frozen-lockfile --ignore-scripts. The docs/ directory contains a PRD example and code-quality guides (twelve-factor, pragmatic). The framework is starter-minimal: 3 GitHub stars, no license, essentially documentation + a setup shell script.

differs_from_seeds: Does not fit any seed archetype — it targets OpenAI Codex, not Claude Code. Closer to agent-os (instructions-as-markdown scaffold, zero automation) but for Codex's cloud environment rather than a local tool. The AGENTS.md replaces CLAUDE.md in the Codex ecosystem. The "setup script pasted into Codex environment UI" install model is unique in the batch. Compared to all other frameworks here, this is the only Codex-native starter.

01

Overview

ACT-House-Engineering/codex-starter — Overview

Origin

Published by ACT House Engineering, 3 GitHub stars, no license. Last pushed 2025-08-09. Shell language. Single contributor implied (no contributor count resolved).

Target Platform: OpenAI Codex

This is NOT a Claude Code starter. OpenAI Codex (chatgpt.com/codex) is OpenAI's cloud-based coding agent that runs in containerized environments. The repo is designed for Codex's "Setup script" field in the Codex environment settings UI at chatgpt.com/codex/settings/environments.

Philosophy (from README)

The README gives example prompt templates for use with Codex:

"Go through the codebase and find some tasks to clean up the code" "Find and fix a file to improve using docs/code-quality/twelve-factor.md" "Generate a PRD of the following feature for me to review then I want you to build it: ..."

The code quality guides (twelve-factor, pragmatic programmer) serve as reference documents that Codex reads and applies.

Setup Model

Unlike all other frameworks in this batch, installation is not a local command:

  1. Navigate to chatgpt.com/codex/settings/environments
  2. Select or create a Codex environment
  3. Scroll to "Code Execution" section
  4. Paste chmod +x ./setup-codex.sh && ./setup-codex.sh into the "Setup script" field

The setup script runs in Codex's Docker container (based on openai/codex-universal image).

Stack

The package.json + biome.json suggest a TypeScript/JavaScript project base. The pnpm install --ignore-scripts workaround addresses an onnxruntime-node install issue.

02

Architecture

ACT-House-Engineering/codex-starter — Architecture

Distribution

Standalone GitHub repository. Intended to be cloned into a Codex environment or used as a template.

Install Method

# Step 1: Navigate to Codex environment settings
# https://chatgpt.com/codex/settings/environments

# Step 2: In "Code Execution" > "Setup script" field, paste:
chmod +x ./setup-codex.sh
./setup-codex.sh

Directory Tree

ACT-House-Engineering/codex-starter/
├── AGENTS.md           (behavioral guide for Codex)
├── README.md
├── biome.json          (TypeScript linter config)
├── docs/
│   ├── code-quality/
│   │   ├── twelve-factor.md    (12-factor app guide)
│   │   └── pragmatic.md        (pragmatic programmer guide)
│   └── codex-example.md        (example prompts/results)
│   └── example_prd.txt         (PRD example)
├── package.json
└── setup-codex.sh      (Codex environment setup script)

setup-codex.sh Content

#!/bin/bash
# Runs inside Codex's Docker container (openai/codex-universal image)

git log -1  # Show latest commit for version context

# Create .env.local with fake values to pass CI checks
echo "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_Y2xlcmsuZXhhbXBsZS5jb20k" > .env.local
echo "CLERK_SECRET_KEY=sk_test_Y2xlcmsuZXhhbXBsZS5jb20k" >> .env.local
echo "NEXT_PUBLIC_CONVEX_URL=https://example.convex.cloud" >> .env.local

# Update pnpm
curl -fsSL https://get.pnpm.io/install.sh | bash -

# Install deps (--ignore-scripts due to onnxruntime-node issue)
pnpm install --frozen-lockfile --ignore-scripts

Target Runtime

OpenAI Codex cloud environment (Docker container based on openai/codex-universal).

Config Files

  • AGENTS.md — behavioral instructions for Codex agent
  • biome.json — linting/formatting config
  • package.json — Node.js dependencies
03

Components

ACT-House-Engineering/codex-starter — Components

Commands

None (no slash commands, no Claude Code commands — this is a Codex starter, not Claude Code).

Skills / Agents

None in the Claude Code sense. AGENTS.md provides behavioral instructions for Codex.

Hooks

None.

Scripts (1)

  • setup-codex.sh — Codex environment setup; installs pnpm, creates fake .env.local, runs pnpm install; executed in Codex Docker container

Reference Docs (the actual value)

  • docs/code-quality/twelve-factor.md — 12-factor app methodology; used as reference in prompts like "Find and fix a file to improve using docs/code-quality/twelve-factor.md"
  • docs/code-quality/pragmatic.md — Pragmatic Programmer principles; used as reference
  • docs/example_prd.txt — example PRD for testing the "Generate a PRD then build it" workflow
  • docs/codex-example.md — example Codex prompts and outputs

AGENTS.md

Behavioral guide for Codex (equivalent to CLAUDE.md):

# Contributor Guide

## Commands
- Install deps command - `pnpm install`
- Lint - `pnpm lint`

## Dev Environment Tips
- Run `pnpm lint` to verify the code is ready to commit

## Commit instructions
- Use Semantic Commit Messages
- Example: "feat: add login route"

Minimal — just defines commands, lint, and commit format. No elaborate behavioral instructions.

External References

README links to:

  • OpenAI Codex documentation: https://platform.openai.com/docs/codex
  • Codex Docker image: https://github.com/openai/codex-universal
05

Prompts

ACT-House-Engineering/codex-starter — Prompts

Verbatim Excerpt 1: Code quality prompt pattern (from README)

Find and fix a file to improve using docs/code-quality/twelve-factor.md

Prompting technique: Reference-file-grounded instruction. The prompt explicitly names a reference document (twelve-factor.md) that provides the evaluation criteria. This is a "read the standard, apply it" pattern — Claude/Codex reads the methodology document and uses it to evaluate existing code.

Verbatim Excerpt 2: Type safety improvement prompt (from README)

Go through the files in the tablecn dir and try removing "as" type casting and "any" types so that we have better type safety.

If an "as" or "any" can't be removed add a comment explaining why

- Be sure to correctly encode comment in JSX
- Leave "as const" as that's very type safe
- If you have to replace an instance of "as" with one or more instances of as then just leave it alone

Success is less "as" or "any" statements than before and passing typechecks

Prompting technique: Explicit success criteria definition ("Success is less 'as' or 'any' statements than before and passing typechecks"). Handles edge cases explicitly (when "as" can't be removed, add a comment). Distinguishes between safe and unsafe uses of as (as const is safe). This is the most technically precise prompt in the framework.

Verbatim Excerpt 3: AGENTS.md behavioral guide

# Contributor Guide

(These rules apply to the entire codebase so should not be very opinionated)

## Commands
- Install deps command - `pnpm install`
- Lint - `pnpm lint`

## Dev Environment Tips
- Run `pnpm lint` to verify the code is ready to commit

## Commit instructions
- Use Semantic Commit Messages
- Example: "feat: add login route"

Prompting technique: Minimal convention guide. "Should not be very opinionated" is an explicit anti-constraint. Conventional Commits format instruction with a concrete example.

09

Uniqueness

ACT-House-Engineering/codex-starter — Uniqueness

differs_from_seeds

Does not fit any seed archetype — uniquely targets OpenAI Codex (cloud agent) rather than Claude Code or any local AI tool. The closest seed is agent-os (markdown instructions scaffold, minimal automation) but even agent-os is Claude Code-specific. The "paste setup script into Codex environment UI" install model is unlike any seed's install method. The reference-doc-grounded prompting pattern ("using docs/code-quality/twelve-factor.md") is a technique not explicitly modeled in any seed. This framework is essentially a template for getting OpenAI Codex running on a TypeScript/pnpm project, not an architectural framework.

Positioning

Minimal starter demonstrating OpenAI Codex usage for a specific tech stack (TypeScript, pnpm, Convex, Clerk). Published by ACT House Engineering as a learning example. The docs/example_prd.txt and docs/codex-example.md suggest educational intent.

Observable Failure Modes

  1. Platform-specific: Only works with OpenAI Codex cloud environment. Cannot be adapted to Claude Code without replacing the entire setup model.
  2. No license: No license file.
  3. onnxruntime-node workaround: --ignore-scripts in pnpm install is a workaround for a known issue; may break packages that need install scripts.
  4. Hardcoded fake credentials: .env.local with hardcoded fake keys is a CI workaround. Real projects need to replace these.
  5. Very low signal: 3 stars, last commit 2025-08-09 — may be obsolete as OpenAI Codex evolves.

Category Note

The only OpenAI Codex starter in this batch. Included likely because Codex is a competitor/complement to Claude Code in the AI coding agent space. The codex-second-brain-starter (trilogy-group) is also Codex-targeted — compare those two.

04

Workflow

ACT-House-Engineering/codex-starter — Workflow

Setup Phases

Phase Action Artifact
1. Create Codex environment Navigate to chatgpt.com/codex/settings/environments Environment created
2. Configure setup script Paste setup-codex.sh invocation Script registered
3. Submit task to Codex Type prompt in Codex chat Codex executes in container

Example Workflows

PRD → Implementation

Ask: "Generate a PRD of the following feature for me to review then I want you to build it: ..."

Codex generates PRD, user reviews, then Codex implements.

Code Quality Improvement

Ask: "Find and fix a file to improve using docs/code-quality/twelve-factor.md"

Codex reads the twelve-factor guide and applies it to codebase.

Cleanup

Ask: "Go through the codebase and find some tasks to clean up the code"

Codex identifies and proposes cleanup tasks.

Type Safety Improvement

Code: "Go through the files in the tablecn dir and try removing 'as' type
casting and 'any' types so that we have better type safety.
- Be sure to correctly encode comment in JSX
- Leave 'as const' as that's very type safe
- If you have to replace an instance of 'as' with one or more instances of
  as then just leave it alone
Success is less 'as' or 'any' statements than before and passing typechecks"

Approval Gates

None defined in the framework. Codex's built-in approval model applies.

Artifacts

Artifact Type
.env.local Fake values file (CI workaround)
PRD Text file (from prompt)
Code changes Git diff (from implementation tasks)
06

Memory Context

ACT-House-Engineering/codex-starter — Memory & Context

Memory Type

None — no structured memory system.

Context Mechanism

AGENTS.md provides persistent behavioral instructions. Reference docs in docs/code-quality/ provide domain knowledge that Codex reads when referenced in prompts.

State Files

None beyond AGENTS.md and code quality reference docs.

Persistence

Session-only (Codex's built-in session handling). AGENTS.md persists across Codex sessions.

Cross-Session Handoff

No structured handoff. Codex's native session handling applies.

Notes

This framework has the simplest memory model in the batch — no memory bank, no SNAPSHOT.md, no dual-memory. The reference docs (twelve-factor.md, pragmatic.md) serve as domain knowledge that persists by being in the repository, but they are read-only reference material, not session state.

07

Orchestration

ACT-House-Engineering/codex-starter — Orchestration

Multi-Agent Support

No.

Orchestration Pattern

None — single Codex instance.

Multi-Model Usage

No — OpenAI Codex only.

Isolation Mechanism

Container — Codex runs in a Docker container (openai/codex-universal image). This is the only framework in the batch where the isolation mechanism is a real container, not because the framework implements it, but because it's the target platform's native isolation.

Execution Mode

One-shot per Codex task submission.

Hooks

None.

Consensus Mechanism

None.

Crash Recovery

None (Codex platform handles).

08

Ui Cli Surface

ACT-House-Engineering/codex-starter — UI / CLI Surface

Dedicated CLI Binary

No.

Local Web Dashboard

No. The primary interface is the Codex web UI at chatgpt.com/codex.

IDE Integration

None specified.

Codex Web Interface

The primary surface is OpenAI's Codex web UI:

  • chatgpt.com/codex/settings/environments — where the setup script is pasted
  • Codex chat interface — where prompts are submitted

Setup Script Surface

setup-codex.sh runs in the Codex container's environment. Users never see this running — it's a background setup step before their session starts.

Observability

git log -1 in the setup script logs the latest commit to show Codex's context. No other observability.

Linting

biome.json configures Biome linter/formatter. pnpm lint runs it. This is the only quality tool in the framework.

Related frameworks

same archetype · same primary tool · same memory type

Context-Engineering Handbook ★ 9.0k
A13 Methodology

Provides a first-principles, research-grounded vocabulary and learning path for context engineering — the discipline of designing…

walkinglabs/learn-harness-engineering ★ 6.6k
A13 Methodology

Teach harness engineering from first principles (12 lectures + 6 projects) and provide a scaffolding skill (harness-creator) that…

Awesome Harness Engineering (walkinglabs) ★ 2.7k
A13 Methodology

Curate the authoritative reference list of articles, benchmarks, and tools for harness engineering — the practice of shaping the…

cline-memory-bank (nickbaumann98) ★ 581
A13 Methodology

Custom instructions + 6-file hierarchical Markdown memory bank so Cline maintains full project context across sessions, with a…

FPF (First Principles Framework) ★ 372
A13 Methodology

Provides a formal pattern language for making reasoning explicit, traceable, and publishable in mixed human/AI engineering work —…

nexu-io/harness-engineering-guide ★ 134
A13 Methodology

Provide a practical, code-first reference guide to harness engineering — from first principles to production patterns —…