rtk
CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies
- 87k
- Rust
- Apache-2.0
- 19 h ago

CodexOpt: Optize your Agents.MD and Skills for Codex with GEPA
Repo SuperagenticAI/CodexOpt, read from GitHub 15 min ago. SuperagenticAI has not joined Take My Repo.
SuperagenticAI/CodexOpt is a public repo on GitHub by SuperagenticAI. CodexOpt: Optize your Agents.MD and Skills for Codex with GEPA. It declares the MIT license on GitHub. It is written mainly in Python, has 23 stars and last changed on 2026-05-26. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
Benchmark and optimize AGENTS.md and SKILL.md for Codex.
CodexOpt is a lightweight CLI for benchmarking and optimizing Codex instruction assets.
It focuses on Codex instruction assets:
AGENTS.md.codex/skills/**/SKILL.md.agents/skills/**/SKILL.mdCodexOpt gives teams a repeatable workflow to:
Most teams edit AGENTS.md and SKILL.md manually, but struggle to answer:
CodexOpt turns these edits into measurable runs with artifacts you can inspect and version.
heuristic (default, local and deterministic).skillopt engine for SKILL.md files with train/validation evidence splits,
bounded edits, and validation-gated acceptance.>=3.10uv (recommended) or pipuv sync --extra dev
Run commands through the managed environment:
uv run codexopt --help
uv.lock is committed to keep dependency resolution reproducible across machines and CI.
pip install -e ".[dev]"
# 1) Create config
uv run codexopt init
# 2) Inspect what will be evaluated
uv run codexopt scan
# 3) Get baseline scores
uv run codexopt benchmark
# 4) Optimize AGENTS.md
uv run codexopt optimize agents --file AGENTS.md
# 5) Optimize skills
uv run codexopt optimize skills --glob ".codex/skills/**/SKILL.md"
# 6) Review apply impact without writing
uv run codexopt apply --kind agents --dry-run
# 7) Apply selected improvements
uv run codexopt apply --kind agents
# 8) Generate markdown summary
uv run codexopt report --output codexopt-report.md
For Codex-specific rollout workflows, including codex exec --json validation tasks, see
Using CodexOpt with Codex.
Developers use CodexOpt in the repository that contains their Codex instruction assets:
AGENTS.md.codex/skills/**/SKILL.md.agents/skills/**/SKILL.mdOptional evidence can also be added to improve benchmarking and optimization quality:
tasks.md, task lists, or JSON fixtures)issues.md or JSON exports)Typical workflow:
scan and benchmark to measure the current instruction assets.optimize agents and optimize skills to generate improved candidates..codexopt/runs/.apply --dry-run first, then apply accepted changes.Example with optional evidence configured in codexopt.yaml:
evidence:
task_files:
- tasks.md
issue_files:
- issues.md
With that config in place, benchmark and optimize use:
Today, task and issue files influence scoring and feedback. With --engine skillopt, CodexOpt
uses task evidence as train/validation splits so skill candidates must improve held-out evidence
before they are accepted. JSON task files can also define executable rollout commands; when present,
those rollout pass rates become the held-out validation gate.
Use codexopt.example.yaml as a starting point for committed team config.
codexopt --config <path-to-codexopt.yaml> <command>
initCreate a default config file.
codexopt init [--path PATH] [--force]
scanDiscover AGENTS/SKILL targets and validate shape.
codexopt scan
benchmarkScore current files using built-in heuristics.
codexopt benchmark
optimize agentsOptimize AGENTS files.
codexopt optimize agents \
[--file PATTERN] \
[--engine heuristic|reflective] \
[--reflection-model MODEL] \
[--max-metric-calls N]
optimize skillsOptimize SKILL files.
codexopt optimize skills \
[--glob PATTERN] \
[--engine heuristic|skillopt|reflective] \
[--reflection-model MODEL] \
[--max-metric-calls N]
improveOne command for Codex users: discover targets, mine starter tasks, run the reflective optimizer, and preview the diff.
codexopt improve # offline preview
codexopt improve --live # Codex-backed reflective preview
codexopt improve --live --apply # write validated changes with backups
applyApply best candidates from the latest optimization run (or a provided run id).
codexopt apply [--kind agents|skills] [--run-id RUN_ID] [--dry-run]
reportGenerate a markdown report from latest runs in state.
codexopt report [--output FILE.md]
Default codexopt.yaml:
version: 1
targets:
agents_files:
- AGENTS.md
- "**/AGENTS.md"
- "**/AGENTS.override.md"
skills_globs:
- ".codex/skills/**/SKILL.md"
- "**/.codex/skills/**/SKILL.md"
- ".agents/skills/**/SKILL.md"
- "**/.agents/skills/**/SKILL.md"
exclude_globs:
- ".git/**"
- ".codexopt/**"
- ".venv/**"
- "node_modules/**"
- "reference/**"
output:
root_dir: ".codexopt"
evidence:
task_files: []
issue_files: []
optimization:
engine: "heuristic"
min_apply_delta: 0.01
max_metric_calls: 60
reflection_model: null
skillopt_train_ratio: 0.67
skillopt_edit_budget: 24
skillopt_validation_delta: 0.01
Config notes:
targets.agents_files: glob patterns for AGENTS targets.targets.skills_globs: glob patterns for SKILL.md targets.targets.exclude_globs: paths ignored during scan.output.root_dir: run artifacts and backups location.evidence.task_files: optional markdown/json task lists used for repo-alignment scoring.evidence.issue_files: optional markdown/json issue or review exports used for theme-aware feedback.optimization.engine: default optimization engine (heuristic, reflective, or skillopt for skills).optimization.min_apply_delta: minimum score gain required to apply.optimization.max_metric_calls: legacy GEPA metric budget.optimization.reflection_model: legacy GEPA reflection model.optimization.skillopt_train_ratio: task evidence fraction used for skill candidate proposal.optimization.skillopt_edit_budget: maximum line edit operations allowed for SkillOpt candidates.optimization.skillopt_validation_delta: minimum held-out validation gain required for SkillOpt acceptance.CodexOpt computes a 0.0 to 1.0 score per file.
AGENTS scoring factors include:
SKILL scoring factors include:
name / description penalties.Each benchmarked file also includes:
Candidate transforms include:
The best candidate is selected by score delta. If delta is below min_apply_delta, original content is kept.
The maintained SkillOpt/GEPA-inspired path is --engine reflective, or the
Codex-user shortcut codexopt improve. It evaluates a candidate document on
tasks, captures textual feedback, asks an optimizer model to rewrite the
document, and accepts the rewrite only when it improves held-out validation
tasks.
Defaults stay offline and use static/verifier signals. To run the full live Codex loop, use:
codexopt improve --live
--live uses codex exec as both optimizer and judge. You can also set
reflective.optimizer_model and reflective.judge_model to codex,
openai/<model>, or another OpenAI-compatible model.
--engine gepa is deprecated. It targeted an older gepa.optimize_anything
API and now falls back with a clear warning. Use --engine reflective instead.
For SkillOpt-style skill optimization:
optimization:
engine: "skillopt"
reflection_model: "openai/gpt-5-mini" # optional; without it, heuristic proposers are used
skillopt_train_ratio: 0.67
skillopt_edit_budget: 24
skillopt_validation_delta: 0.01
Executable rollout task files can be listed in evidence.task_files:
[
{
"name": "skill-verifier",
"description": "Run a repo-local verifier against the candidate skill.",
"command": ["python", "scripts/verify_skill.py"],
"timeout_seconds": 30
}
]
Codex-backed rollout tasks can use backend: "codex" and codex_prompt:
[
{
"name": "codex-skill-task",
"backend": "codex",
"description": "Run Codex against the candidate skill.",
"codex_prompt": "Use the local skill to update CHANGELOG.md for a patch release.",
"timeout_seconds": 120,
"expected_final_response_contains": "CHANGELOG.md",
"expected_file_change": "CHANGELOG.md",
"expected_file_contains": {
"path": "CHANGELOG.md",
"contains": "Patch"
}
}
]
CodexOpt evaluates those commands in a temporary copy of the repo with the candidate SKILL.md
written in place, then records pass/fail details in optimize.json. For Codex-backed rollouts,
CodexOpt also parses codex exec --json events into trajectory metadata: final response,
commands, file changes, token usage, and errors.
For OpenAI-compatible reflective models, set the provider credentials and use
reflective.optimizer_model / reflective.judge_model values such as
openai/gpt-5-mini:
export OPENAI_API_KEY="your-openai-key"
For Gemini-compatible endpoints, set the credentials expected by your OpenAI-compatible
client or run through codexopt improve --live to use codex exec directly.
export GEMINI_API_KEY="your-gemini-key"
export GOOGLE_API_KEY="$GEMINI_API_KEY"
Fallback behavior:
By default, everything is written under .codexopt/:
runs/<run_id>/scan.jsonruns/<run_id>/benchmark.jsonruns/<run_id>/optimize.jsonruns/<run_id>/apply.jsonbackups/<timestamp>/... (created on non-dry-run apply)state.json (tracks latest run ids per command type)Run ids are timestamped and namespaced by command kind, for example:
20260308T184800123456Z-benchmark20260308T184812654321Z-optimize-skillsAGENTS.md and skills.scan and benchmark to establish baseline.optimize agents and/or optimize skills.optimize.json and diffs.apply --dry-run first, then apply.report and attach report to PR.AGENTS.md cleanupBefore (AGENTS.md):
## Coding Rules
Always run tests before commit.
Always run tests before commit.
Keep changes minimal.
After optimization (heuristic):
## Coding Rules
Always run tests before commit.
Keep changes minimal.
What changed:
SKILL.md missing frontmatterBefore (.codex/skills/my_skill/SKILL.md):
Use this skill for repository release checks.
Run lint, tests, and changelog validation.
After optimization (heuristic):
---
name: my-skill
description: Repository-specific workflow skill.
---
Use this skill for repository release checks.
Run lint, tests, and changelog validation.
What changed:
name from folder name.description.uv run codexopt init
uv run codexopt scan
uv run codexopt benchmark
uv run codexopt optimize agents --file AGENTS.md
uv run codexopt optimize skills --glob ".codex/skills/**/SKILL.md"
uv run codexopt apply --kind skills --dry-run
uv run codexopt apply --kind skills
uv run codexopt report --output codexopt-report.md
Files to inspect after running:
.codexopt/runs/*/scan.json.codexopt/runs/*/benchmark.json.codexopt/runs/*/optimize.json.codexopt/runs/*/apply.json.codexopt/backups/*GitHub Actions workflow is included at .github/workflows/ci.yml and runs:
uv lock --check for lockfile consistency.uv sync --extra dev for environment setup.uv build).It does not publish packages.
uv lock
uv sync --extra dev
uv run --no-sync ruff check src tests
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --no-sync pytest -q
uv build
codexopt apply says "no optimization run found"Cause:
state.json does not contain the expected latest run pointer.Fix:
uv run codexopt optimize agents
uv run codexopt apply --kind agents
Or pass an explicit run:
uv run codexopt apply --kind agents --run-id <run_id>
--engine gepa did not use GEPACause:
gepa.optimize_anything API.Behavior:
Fix:
uv run codexopt optimize agents --engine reflective
uv run codexopt improve --live
apply --dry-run says files would be applied, but nothing changedExpected behavior:
--dry-run reports candidate applications without writing files.To write changes, run again without --dry-run:
uv run codexopt apply --kind agents
If your environment blocks dependency resolution in isolated builds, use:
uv build
Some environments auto-load global pytest plugins that can break local tests. Run with plugin autoload disabled:
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --no-sync pytest -q
Cause:
optimization.min_apply_delta, orFix:
optimization.min_apply_delta in codexopt.yaml, then re-run optimize/apply.MIT. See LICENSE.
shashi@super-agentic.ai)SuperagenticAI/CodexOpt is a public repo on GitHub by SuperagenticAI. CodexOpt: Optize your Agents.MD and Skills for Codex with GEPA.
It declares the MIT license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-05-26. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.

CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies
🏕️ Reproducible development environment for humans and agents

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Reverse engineer anything with agents, from app behavior down to native binaries.
from vibe coding to agentic engineering - practice makes claude perfect
SuperClaw: Red-Team AI Agents Before They Red-Team You
Make DSPy Agentic using protocol-first approach that support the Agent Protocols like MCP, A2A

Claude Code for DSPy: Comprehensive CLI to Optimize Your DSPy Code. our AI-Powered DSPy Development Assistant

The harness interoperability layer for coding agent. Agent to Agent connect over ACP, A2A and UHP