agent-cli-starter

A minimal, opinionated starter for Claude Code and Codex CLI — one source of truth, one-command migration between them.

한국어 README

Why this exists

Claude Code reads CLAUDE.md and .claude/. Codex CLI reads AGENTS.md and .codex/. They have similar runtime models — agents, skills, hooks — but no shared starter.

This repo gives you:

• One source (CLAUDE.md + .claude/) that generates the Codex mirror on demand.
• 3 agents (orchestrator, executor, quality reviewer) that work in both CLIs.
• 4 workflow skills (brainstorm → plan → execute → verify) that scale from one-line fixes to multi-day features.
• 2 safety hooks (session context loader + destructive-command blocker).
• A catalog of 13 optional skills you can pull in à la carte.

If you have a Claude Code project and want to also use Codex (or vice versa), you do not rewrite anything. One command syncs both.

30-second install

git clone https://github.com/youngjin39/agent-cli-starter.git my-project
cd my-project
bash setup.sh

The installer asks one question: which CLI? Claude only, Codex only, or Both.

Migration between CLIs

Already on Claude and want to add Codex? One command:

bash scripts/generate-codex.sh

That regenerates AGENTS.md and .codex/ from your existing source. Codex picks them up natively. No manual rewrite.

The reverse direction works the same way — Codex users get Claude support by editing source files Claude reads (CLAUDE.md, .claude/) which the script keeps in sync.

What's included

Area	Bundled (curated)	Catalog (à la carte)
Agents	main-orchestrator, executor-agent, quality-agent	—
Workflow skills	brainstorming, writing-plans, verification, code-review	—
Engineering skills	—	testing, ux-ui-design, runner, git-commit, security-review, dependency-audit, release-prep
Diagnostics	—	project-doctor, self-audit, deep-interview, ai-readiness-cartography, ai-ready-bluebricks-development, improve-token-efficiency
Hooks	SessionStart, PreToolUse	(extend in your fork)

Bundled = always installed. Catalog = pull in only when you need them.

Adding a catalog skill

bash scripts/add-skill.sh testing

Copies catalog/skills/testing/SKILL.md into .claude/skills/ and regenerates the Codex mirror so both CLIs see it.

File layout

.claude/                    # Claude Code source (canonical)
  agents/                   #   3 agents
  skills/                   #   4 workflow skills
  hooks/                    #   2 safety hooks + shared lib
.codex/                     # Codex CLI mirror (generated)
catalog/skills/             # 13 optional skills (not installed by default)
scripts/
  setup.sh                  # First-run installer (in repo root)
  generate-codex.sh         # Sync Claude → Codex
  add-skill.sh              # Pull a catalog skill into the bundled set
docs/
  quickstart.md             # First-session walkthrough
  claude-vs-codex.md        # CLI comparison + migration guide
  skill-catalog.md          # Browseable skill index
examples/                   # Anonymized end-to-end scenarios
  01-new-flutter-app/
  02-add-codex-to-existing-claude/
  03-pull-catalog-skill/
tasks/                      # Durable task state (plan, lessons, sessions, handoffs)
CLAUDE.md                   # Source contract for both CLIs
AGENTS.md                   # Codex entry point (generated from CLAUDE.md)

How the agents work

The starter ships three agents that match the workflow:

• main-orchestrator classifies each request: simple → execute inline; complex → route through the workflow pipeline; broad-scope review → delegate to quality-agent.
• executor-agent runs approved multi-step plans with checkpoints.
• quality-agent does read-only adversarial review when explicitly requested or when ≥4 issues are detected.

You usually only talk to main-orchestrator. The others are invoked by it.

How the workflow skills work

Skill	When it fires
brainstorming	Real design forks, new features, architecture changes
writing-plans	Multi-step execution that needs checkpointed steps
verification	Completion gates with evidence
code-review	PRs, merge checks, post-completion review

Simple tasks (1~2 steps) skip the pipeline and run inline.

Comparison: Claude Code vs Codex CLI

Concern	Claude Code	Codex CLI
Vendor	Anthropic	OpenAI
Entry file	CLAUDE.md	AGENTS.md
Sub-agents	.claude/agents/*.md	.codex/agents/*.toml
Skills	.claude/skills/*/SKILL.md	.codex/skills/*/SKILL.md
Hooks dir	.claude/hooks/	.codex/hooks/
Hook config	.claude/settings.json (declarative)	.codex/hooks.json + features.codex_hooks=true in .codex/config.toml
Native hook events	SessionStart, PreToolUse, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, Stop, SessionEnd	All of the above except SessionEnd
Edit tool input	tool_input.file_path	apply_patch envelope, paths in tool_input.command
IDE plugins	VS Code, JetBrains	Editor-agnostic CLI
MCP support	Yes	Yes

Decision criteria

If you want…	Pick
IDE integration (VS Code, JetBrains)	Claude Code
Pure CLI workflow, scriptable in pipelines	Codex CLI
Maximum hook coverage (incl. SessionEnd)	Claude Code
Compare model behavior on the same task	Both (one source of truth, two CLIs)
Already on one and curious about the other	Both — migration is one command

Full comparison and migration guide: docs/claude-vs-codex.md.

Roadmap

• More skills in the catalog (security review, dependency audit, deploy, observability)
• Optional MCP server presets (Context7, Sequential Thinking, Browser, Knowledge Wiki)
• Project-type templates (Flutter, Next.js, Python, Rust, Go)

Contributing

Bug reports, doc fixes, and new catalog skills are welcome. See CONTRIBUTING.md.

The single rule: edit source files (CLAUDE.md, .claude/), then run bash scripts/generate-codex.sh. CI checks that AGENTS.md and .codex/ stay in sync, so out-of-sync PRs fail automatically.

License

MIT.