From 0279519c5f80d5051e9bd8ad9a81811de3bf260c Mon Sep 17 00:00:00 2001 From: Nic van Dessel <51134175+nvandessel@users.noreply.github.com> Date: Fri, 27 Feb 2026 23:09:48 -0800 Subject: [PATCH 1/2] docs: add codex mcp integration guidance and templates --- AGENTS.md | 21 +++- docs/integrations/README.md | 9 +- docs/integrations/agent-prompt-template.md | 14 ++- docs/integrations/codex.md | 110 ++++++++++++++++++ .../templates/codex-agents.md.template | 42 +++++++ .../templates/floop.SKILL.md.template | 51 ++++++++ 6 files changed, 241 insertions(+), 6 deletions(-) create mode 100644 docs/integrations/codex.md create mode 100644 docs/integrations/templates/codex-agents.md.template create mode 100644 docs/integrations/templates/floop.SKILL.md.template diff --git a/AGENTS.md b/AGENTS.md index 6cd68f84..444cbc91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,8 @@ ## Floop Integration (REQUIRED) -You have persistent memory via floop. Your learned behaviors are auto-injected at session start via hooks. +You have persistent memory via floop. Learned behaviors are loaded via MCP and, +where supported, auto-injected via hooks. **When corrected, IMMEDIATELY capture it:** ``` @@ -28,6 +29,23 @@ For non-Claude agents, see `docs/integrations/agent-prompt-template.md`. - `floop_list` - List all stored behaviors - `floop_deduplicate` - Merge duplicate behaviors +### Codex Runtime Cadence (No Lifecycle Hooks) + +In Codex environments, treat these as required pseudo-hooks: + +1. **Task start**: Call `floop_active` with current `file` and `task`. +2. **Context change** (file/task/mode shift): Re-call `floop_active`. +3. **Correction received**: Immediately call `floop_learn` (no permission needed). +4. **Behavior outcome**: Call `floop_feedback` with `confirmed` or `overridden`. + +If MCP is unavailable, use CLI fallback immediately: + +```bash +floop active --file --task --json +floop learn --right "what to do instead" --wrong "what happened" --file +floop list --json +``` + --- ## Project Overview @@ -204,4 +222,3 @@ bv --robot-next # Get single top pick ``` **CRITICAL:** Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session. - diff --git a/docs/integrations/README.md b/docs/integrations/README.md index 043f2163..64a8f268 100644 --- a/docs/integrations/README.md +++ b/docs/integrations/README.md @@ -21,7 +21,7 @@ floop integrates with AI coding tools through 3 methods: | Windsurf | Yes | — | Yes (.windsurfrules) | Researched | | GitHub Copilot | Yes | — | Yes (copilot-instructions.md) | Researched | | Aider | — | — | Yes (wrapper script) | Researched | -| OpenAI Codex CLI | — | — | Yes (Skills/agents.md) | Researched | +| OpenAI Codex CLI | Yes | — | Yes (AGENTS.md + Skills) | Researched | ## Tested Integrations @@ -158,7 +158,12 @@ Or add `floop prompt` output to `.aider/conventions.md`. ### OpenAI Codex CLI -No MCP support yet. Add `floop prompt` output to `codex/agents.md` (Skills file). +Codex supports MCP, but does not expose Claude-style lifecycle hooks. Use: + +- MCP for bidirectional tool access +- `AGENTS.md` + Codex `SKILL.md` for runtime cadence (task start, context refresh, correction capture) + +Full guide: [codex.md](./codex.md) ## Generic MCP Configuration diff --git a/docs/integrations/agent-prompt-template.md b/docs/integrations/agent-prompt-template.md index e038b602..0670551d 100644 --- a/docs/integrations/agent-prompt-template.md +++ b/docs/integrations/agent-prompt-template.md @@ -72,7 +72,7 @@ If floop tools return errors about missing or uninitialized state, run ## Static Template (Read-Only) -For tools without MCP support (Aider, OpenAI Codex CLI, or any tool where you prefer a simpler setup). +For tools without MCP support (Aider, or any tool where you prefer a simpler setup). Run this command to generate a snapshot of your current behaviors: @@ -80,7 +80,7 @@ Run this command to generate a snapshot of your current behaviors: floop prompt ``` -Paste the output into your tool's instruction file (`.cursorrules`, `copilot-instructions.md`, `agents.md`, etc.). +Paste the output into your tool's instruction file (`.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, etc.). **Limitations:** Static mode is **read-only** — the agent can follow behaviors but cannot capture new corrections automatically. To capture corrections, run `floop learn` manually in your terminal: @@ -106,6 +106,16 @@ floop prompt > .cursorrules > Ensure `floop init` has been run first, or `floop prompt` will output an > initialization warning instead of behaviors. +## Codex Note + +Codex can use MCP for floop. Prefer MCP + instruction orchestration over static-only mode: + +- Add floop MCP server in Codex config +- Add Codex runtime cadence rules in `AGENTS.md` +- Optionally install a Codex skill for floop workflow enforcement + +See [codex.md](./codex.md) for setup. + ## Where to Paste See the [compatibility matrix](./README.md) for your tool's instruction file location. diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md new file mode 100644 index 00000000..1c76d920 --- /dev/null +++ b/docs/integrations/codex.md @@ -0,0 +1,110 @@ +# OpenAI Codex Integration + +## Overview + +Codex can use floop through MCP, but it does not currently expose Claude-style +lifecycle hooks (such as `SessionStart`, `PreToolUse`, `UserPromptSubmit`). + +That means Codex integrations need two layers: + +1. MCP for bidirectional floop tool access +2. Instruction orchestration (`AGENTS.md` + optional `SKILL.md`) to emulate hook cadence + +This guide shows both. + +## 1) Configure MCP + +Add floop as an MCP server in your Codex config. + +Example `~/.codex/config.toml`: + +```toml +[mcp_servers.floop] +command = "floop" +args = ["mcp-server"] +# Optional but recommended for project-local behavior stores +cwd = "/path/to/your/project" +``` + +If you prefer per-project setup, use Codex's local config equivalent and keep +`cwd` set to your project root. + +## 2) Verify MCP Is Working + +Use this checklist in a Codex session: + +1. Confirm Codex shows `floop_*` tools in its MCP tool list. +2. Ask Codex to call `floop_active` for your current file/task. +3. Confirm a structured response is returned (with `active` behaviors and `count`). +4. Ask Codex to call `floop_list` and verify the store is reachable. + +If tools are missing: + +- Confirm `floop` is in `PATH` (`which floop`). +- Confirm `floop mcp-server` runs manually in your project. +- Confirm Codex loaded the expected config file and restart Codex. + +## 3) Add Codex Orchestration Rules (No Hooks) + +Because Codex has no lifecycle hooks, add explicit runtime rules to your +project `AGENTS.md`. + +Use this template: + +- [codex-agents.md.template](./templates/codex-agents.md.template) + +These rules force the cadence hooks normally provide: + +- At task start -> call `floop_active` +- On context change (file/task/tooling mode) -> refresh `floop_active` +- On correction -> call `floop_learn` immediately +- After following or overriding behavior -> call `floop_feedback` + +## 4) Add Optional Codex Skill + +For stronger consistency, add a dedicated Codex skill: + +- [floop.SKILL.md.template](./templates/floop.SKILL.md.template) + +Recommended install location: + +`$CODEX_HOME/skills/floop/SKILL.md` + +Use project-local skills if your team prefers repository-scoped behavior. + +## 5) CLI Fallback (If MCP Is Unavailable) + +If MCP is not available in your Codex environment, keep read/write behavior via +CLI commands: + +```bash +# Load context +floop active --file --task --json + +# Learn correction +floop learn --right "what to do instead" --wrong "what happened" --file + +# Review behaviors +floop list --json +``` + +Static prompt fallback: + +```bash +floop prompt > AGENTS.md +``` + +Note: static prompt mode is read-only for the agent. New corrections must be +captured manually via `floop learn`. + +## 6) Dogfood Verification Flow + +Run this sequence to validate end-to-end behavior: + +1. Start a new Codex task and trigger `floop_active`. +2. Deliberately correct Codex and ensure it calls `floop_learn`. +3. Start a second related task and verify the new behavior appears in `floop_active`. +4. Confirm `floop_feedback` gets emitted when behavior is followed/overridden. + +If step 2 or 4 is missed, tighten your `AGENTS.md` trigger language or install +the Codex skill template. diff --git a/docs/integrations/templates/codex-agents.md.template b/docs/integrations/templates/codex-agents.md.template new file mode 100644 index 00000000..b8cdfd51 --- /dev/null +++ b/docs/integrations/templates/codex-agents.md.template @@ -0,0 +1,42 @@ +### floop + Codex Orchestration (No Lifecycle Hooks) + +Codex has floop MCP tools available, but does not provide Claude-style lifecycle +hooks. You MUST emulate lifecycle behavior by explicitly calling floop tools at +the right moments. + +#### Required Cadence + +1. Task start: + - Call `floop_active` with `file` and `task` before substantive changes. +2. Context shift: + - Re-call `floop_active` whenever file focus, task type, or implementation + mode changes. +3. User correction: + - Immediately call `floop_learn` with: + - `right` (required) + - `wrong` (optional but recommended) + - `file`, `task`, and `tags` when available + - Do not wait for user permission. +4. Behavior outcome: + - If behavior helps, call `floop_feedback` with `signal: "confirmed"`. + - If intentionally deviating, call `floop_feedback` with + `signal: "overridden"`. + +#### Reliability Rules + +- If MCP calls fail, switch to CLI fallback immediately. +- Keep working while recording learnings; do not defer correction capture. +- Prefer narrow, file/task-aware behavior retrieval over broad prompt dumps. + +#### CLI Fallback + +```bash +# Active behaviors +floop active --file --task --json + +# Learn correction +floop learn --right "what to do instead" --wrong "what happened" --file + +# Review behaviors +floop list --json +``` diff --git a/docs/integrations/templates/floop.SKILL.md.template b/docs/integrations/templates/floop.SKILL.md.template new file mode 100644 index 00000000..9dbc5388 --- /dev/null +++ b/docs/integrations/templates/floop.SKILL.md.template @@ -0,0 +1,51 @@ +--- +name: floop +description: Enforce floop behavior retrieval and correction capture cadence in hookless Codex sessions. +--- + +# floop Skill + +## Purpose + +Codex sessions do not have lifecycle hooks. This skill enforces a manual +operational loop so floop still behaves like persistent, context-aware memory. + +## Operating Loop + +1. Bootstrap context + - Call `floop_active` with the active file path and task. + - If no file is known, call with task only, then refine once file context is available. + +2. Refresh on context change + - Re-run `floop_active` when changing files, task type, or execution mode + (implementation, testing, refactor, review). + +3. Capture corrections immediately + - When corrected by user, call `floop_learn` right away. + - Include `right` always. + - Include `wrong`, `file`, `task`, and `tags` when available. + - Never wait for permission. + +4. Emit feedback signal + - If a behavior was useful: `floop_feedback` with `confirmed`. + - If you intentionally do not follow a behavior: `floop_feedback` with `overridden`. + +5. Periodic hygiene + - Use `floop_list` for visibility. + - Run `floop_deduplicate` and `floop_validate` periodically to keep quality high. + +## Fallback Mode (No MCP) + +If MCP is unavailable, use CLI equivalents: + +```bash +floop active --file --task --json +floop learn --right "..." --wrong "..." --file +floop list --json +``` + +## Non-Negotiables + +- No task should proceed without an initial `floop_active` call. +- No correction should be ignored or delayed. +- No long session should end without at least one explicit feedback signal if behaviors were used. From 13c8da7b3eca64d97106df7381b33d9059c58055 Mon Sep 17 00:00:00 2001 From: Nic van Dessel <51134175+nvandessel@users.noreply.github.com> Date: Sat, 28 Feb 2026 00:00:01 -0800 Subject: [PATCH 2/2] docs: add codex quick-install and skill maintenance steps --- docs/integrations/README.md | 14 +++++++++ docs/integrations/codex.md | 58 ++++++++++++++++++++++++++++++++++++- 2 files changed, 71 insertions(+), 1 deletion(-) diff --git a/docs/integrations/README.md b/docs/integrations/README.md index 64a8f268..235c983d 100644 --- a/docs/integrations/README.md +++ b/docs/integrations/README.md @@ -165,6 +165,20 @@ Codex supports MCP, but does not expose Claude-style lifecycle hooks. Use: Full guide: [codex.md](./codex.md) +Quick install highlights: + +```bash +cat >> ~/.codex/config.toml <<'EOF' +[mcp_servers.floop] +command = "floop" +args = ["mcp-server"] +cwd = "/path/to/your/project" +EOF + +mkdir -p ~/.agents/skills/floop +ln -sfn "$(pwd)/docs/integrations/templates/floop.SKILL.md.template" ~/.agents/skills/floop/SKILL.md +``` + ## Generic MCP Configuration For any MCP-capable tool not listed above: diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md index 1c76d920..15651335 100644 --- a/docs/integrations/codex.md +++ b/docs/integrations/codex.md @@ -12,6 +12,35 @@ That means Codex integrations need two layers: This guide shows both. +## Quick Install (Codex) + +Run from your project root: + +```bash +# 1) Ensure floop is installed +which floop + +# 2) Configure MCP in Codex (~/.codex/config.toml) +cat >> ~/.codex/config.toml <<'EOF' +[mcp_servers.floop] +command = "floop" +args = ["mcp-server"] +cwd = "/path/to/your/project" +EOF + +# 3) Install AGENTS baseline rules +cp docs/integrations/templates/codex-agents.md.template AGENTS.md + +# 4) Install floop skill via Codex skill discovery path +mkdir -p ~/.agents/skills/floop +ln -sfn "$(pwd)/docs/integrations/templates/floop.SKILL.md.template" ~/.agents/skills/floop/SKILL.md +``` + +Then restart Codex (fully quit and relaunch). + +If you already have an `AGENTS.md`, merge the template content instead of +overwriting the file. + ## 1) Configure MCP Add floop as an MCP server in your Codex config. @@ -68,7 +97,7 @@ For stronger consistency, add a dedicated Codex skill: Recommended install location: -`$CODEX_HOME/skills/floop/SKILL.md` +`~/.agents/skills/floop/SKILL.md` Use project-local skills if your team prefers repository-scoped behavior. @@ -108,3 +137,30 @@ Run this sequence to validate end-to-end behavior: If step 2 or 4 is missed, tighten your `AGENTS.md` trigger language or install the Codex skill template. + +## Skill Maintenance + +Because the recommended install uses a symlink, updates are immediate when the +template file changes in your repo. + +### Verify Skill Install + +```bash +ls -la ~/.agents/skills/floop/SKILL.md +``` + +You should see a symlink pointing to: +`docs/integrations/templates/floop.SKILL.md.template`. + +### Update + +```bash +cd /path/to/your/project +git pull +``` + +### Uninstall + +```bash +rm -f ~/.agents/skills/floop/SKILL.md +```