FM-Agent Plugin

This plugin integrates FM-Agent into Claude Code or codex for automated code reasoning and bug repair.

Prerequisites

• Ubuntu 22.04+ or compatible Linux distribution
• Python 3.10+

How to install

For Claude Code:

claude
/plugin marketplace add fmagent-project/FM-Agent-Plugin
/plugin install fm-agent-plugin@fm-agent-plugin

For codex:

codex plugin marketplace add fmagent-project/FM-Agent-Plugin
codex plugin add fm-agent-plugin@fm-agent-plugin

Important Note:
FM-Agent launches nested model sessions through the configured backend. In local CLI backend mode it uses codex exec from Codex sessions and claude -p from Claude Code sessions, and those sessions must be able to read the target project and write fm_agent/ artifacts. To use FM-Agent properly, set codex permissions to Full Access.

/permissions
[Choose: Full Access]

Available Commands

Command	Description
/fm-agent:install	Clone FM-Agent to the plugin data directory
/fm-agent:config	Show/modify FM-Agent configuration
/fm-agent:preflight	Check the environment is ready before running analysis
/fm-agent:auto-fix	Run FM-Agent verification-repair loop for the whole codebase
/fm-agent:run-full	Execute full-project FM-Agent analysis on current project without repairing bugs (background)
/fm-agent:run-incremental	Execute incremental FM-Agent analysis on current project without repairing bugs (background)
/fm-agent:diagnose	View bug analysis results
/fm-agent:help	Show help information

install

Clone FM-Agent from official repository to the plugin data directory ($HOME/.fm-agent-plugin/FM-Agent/):

git clone https://github.com/fmagent-project/FM-Agent.git

Then run $HOME/.fm-agent-plugin/FM-Agent/install.sh to install dependencies.

config

Read and modify FM-Agent settings stored in $HOME/.fm-agent-plugin/FM-Agent/.env (loaded by FM-Agent via dotenv at runtime).

Workflow:

• If .env does not exist, create it with default values
• List the current .env values as a table
• Ask whether to modify any settings; if yes, use AskUserQuestion (multi-select) to let the user pick which settings to modify and prompt for each new value
• After writing changes, verify the selected backend. In local CLI backend mode, LLM_API_KEY is not required; in upstream OpenCode/API mode, verify LLM_API_KEY.

Configurable settings (all stored in .env):

• LLM_API_KEY - OpenRouter API key (required only for upstream OpenCode/API mode)
• LLM_API_BASE_URL - OpenRouter API endpoint (default: https://openrouter.ai/api/v1)
• LLM_MODEL - Optional model passed to codex exec or claude -p; leave empty to use the selected CLI default
• LLM_EFFORT - Optional reasoning effort passed to codex exec or claude -p; leave empty to omit the effort flag
• FM_AGENT_MODEL_BACKEND - opencode, auto, codex-cli, or claude-cli (default: opencode)
• OPENCODE_MODEL_PROVIDER - Model provider used by OpenCode (default: openrouter)

preflight

Verify the runtime environment is ready before FM-Agent analysis. Both run-full and run-incremental run this automatically as their first shared setup step, so all analysis modes go through the same gate; it can also be invoked directly with /fm-agent:preflight.

Checks (blocking fail vs non-blocking warning):

• FM-Agent installed at $HOME/.fm-agent-plugin/FM-Agent (fail)
• .env present and selected backend configured — LLM_API_KEY for opencode, or the matching CLI on PATH for codex/claude/auto (fail)
• uv available on PATH (fail)
• Python >= 3.10 (fail)
• Current directory is a git repository (fail)
• FM-Agent dependency lockfiles (pyproject.toml, uv.lock) present (warning)
• Supported source files present under the current directory (warning)

Behavior:

• All checks pass: proceed silently
• Interactive session with issues: choose to proceed, ignore permanently, or quit
• Non-interactive session (CI, or --non-interactive): warnings proceed with logging; a blocking failure aborts the run
• Permanently ignored checks are remembered in $HOME/.fm-agent-plugin/env-check-ignore; adding a new check only requires editing the preflight skill, not the run skills

auto-fix

Run the FM-Agent verification-repair-review loop with /fm-agent:auto-fix [<intent-msg>].

Usage and constraints:

• The loop starts from the current project working tree
• The loop runs one FM-Agent verification round first: run-full if fm_agent/ is missing, or run-incremental --incremental if fm_agent/ and fm_agent/version.log exist
• If <intent-msg> is provided and incremental verification is selected, auto-fix passes it to run-incremental --incremental <intent-msg>
• The skill asks for the maximum number of coding-agent repair rounds before starting session state changes
• If FM-Agent reports bugs, the plugin launches one dedicated coding-agent repair sub-session for the full bug batch
• After each repair round, the plugin launches one dedicated reviewer sub-session to decide whether the reported bugs are fixed
• If the reviewer passes the repair, the loop exits; if the reviewer returns feedback, the next coding-agent round receives that feedback and continues repairing
• Coding-agent repairs stay in the working tree only; the auto-fix loop does not auto-commit repair changes
• Only one auto-fix session may be active per repository at a time

Session artifacts live under ./fm_agent_plugin/:

• ./fm_agent_plugin/auto-fix-<session-id>.json - Machine-readable session state
• ./fm_agent_plugin/auto-fix-<session-id>.md - Human-readable session log
• ./fm_agent_plugin/auto-fix-active.json - Active-session lock

run-full

Execute full-project FM-Agent analysis from the plugin data directory against the current project directory (./):

• Verify $HOME/.fm-agent-plugin/FM-Agent/.env exists and the selected backend is configured. In local CLI backend mode, do not require LLM_API_KEY.
• For full-project analysis, if ./fm_agent/ already exists, ask the user whether to resume (continue with --resume) or start fresh (run without --resume; FM-Agent handles prior-output cleanup).
• Launch as a background task so the session is not blocked
• Schedule periodic polling via the loop skill to detect completion, then notify the user with success or failure.

The skill also exposes an orchestration mode used exclusively by /fm-agent:auto-fix to run a single deterministic full-project verification round synchronously, with no resume/fresh prompts and no background polling.

run-incremental

Execute incremental FM-Agent analysis from the plugin data directory against the current project directory (./):

• Usage: /fm-agent:run-incremental --incremental [<intent-msg>]
• Verify $HOME/.fm-agent-plugin/FM-Agent/.env exists and the selected backend is configured. In local CLI backend mode, do not require LLM_API_KEY.
• Generate the intent file from optional user-provided intent plus exported summaries for commits after the last analyzed commit recorded in fm_agent/version.log through HEAD
• Run FM-Agent with --incremental <generated-intent-file>
• Launch as a background task so the session is not blocked

The skill also exposes an orchestration mode used exclusively by /fm-agent:auto-fix to run a single deterministic incremental verification round synchronously, with no background polling.

diagnose

Read FM-Agent output from ./fm_agent/:

• Summary first: Show bug_validation/summary.json with totals
• Details on request: Show individual bug reports (<source>--<function>.md)
• Bug reports include: specification claim, actual behavior, code evidence, trigger condition, probe script, probe output

Output Directory

Analysis results in ./fm_agent/:

• bug_validation/summary.json - Aggregated summary
• bug_validation/<source>--<function>.md - Bug detail reports
• bug_validation/<source>--<function>.result.json - Machine-readable results

Supported Languages

Rust, C, C++, Python, Java, Go, CUDA, JavaScript, TypeScript, ArkTS