Skip to content

codex-plugin.md

Latest commit

 

History

History
85 lines (59 loc) · 3.2 KB

codex-plugin.md

File metadata and controls

85 lines (59 loc) · 3.2 KB

Codex Plugin

fclt ships a first-party Codex plugin at:

plugins/fclt/

The plugin is for agent-led operation. After install, Codex gets focused skills for setup, writeback, evolution, and capability review, plus an MCP server wrapper that exposes common fclt CLI actions as tools.

What It Includes

  • fclt-setup: install, update, inspect, initialize, and repair fclt setup.
  • fclt-writeback: record and review durable writebacks from real work.
  • fclt-evolution: turn repeated writeback into reviewed capability proposals.
  • fclt-capability-review: inspect global/project capability roots and scope changes.
  • fclt MCP server: stdio wrapper around the installed fclt CLI.

The MCP wrapper intentionally delegates to the local fclt binary instead of duplicating core logic. Set FCLT_BIN if Codex should call a specific binary.

MCP Tools

The plugin exposes:

  • fclt_status
  • fclt_doctor
  • fclt_paths
  • fclt_init_operating_model
  • fclt_writeback_add
  • fclt_writeback_review
  • fclt_evolve

These tools are thin wrappers around CLI commands and return command output. Mutating tools still rely on the normal fclt safety model: dry-run first when available, review broad changes before apply, and preserve existing user guidance.

Install In Codex

Use the narrow setup command for normal installs:

fclt setup codex-plugin

That updates only the local fclt plugin payload under ~/plugins/fclt and merges an entry into ~/.agents/plugins/marketplace.json. The default marketplace name is hack-local; if the marketplace file already has a non-empty name, fclt preserves it and installs from that name. The generated entry uses Codex schema-valid policy values, including installation: "AVAILABLE" and authentication: "ON_INSTALL".

When the codex command is available, setup runs codex plugin add fclt@<marketplace> --json. Codex installs the plugin cache under ~/.codex/plugins/cache/<marketplace>/fclt/ using its own version directory.

It does not enter managed mode, adopt Codex state, render ~/.codex/AGENTS.md, or touch existing Codex skills/rules/config.

Useful flags:

fclt setup codex-plugin --dry-run --json
fclt setup codex-plugin --no-codex-install

Use managed sync only when you intentionally want fclt to render broader Codex tool files:

fclt manage codex --global
fclt sync codex --global

For local plugin development, run the lightweight checks that ship with the repository:

node plugins/fclt/scripts/fclt-mcp.cjs --self-test
bun run check

Recommended Agent Use

Use the plugin skills as the first interface. Use MCP tools when a Codex workflow benefits from structured calls for status, doctor, paths, writeback, or evolution review.

For proposal triage, call fclt_evolve with action: "assess" before proposing when a target is known. Assessment is read-only and returns the recommendation, source writebacks, active proposal ids, quality checklist, suggested commands, and the next agent instruction.

Do not create writeback/evolution noise. Record strong signal, group repeated signal, assess readiness, then propose the smallest concrete capability change only when evidence repeats or the missing capability is clear.