Agent plugins

What you get

Run the scan command. The agent reads your code against every rule and gives you a code score with its arithmetic, the fixes to do first, and the file, line and quote behind each problem. Then fix shows each exact change and applies only what you approve, and explain teaches any rule using your own code. If you’re new to GEO, run explain with no argument for a guided tour.

Choose an install

Use the plugin for yourself, across every repository. Commit the files when the whole team should get the agents from the repository without installing anything.

Claude Code

/plugin install geopilot --marketplace moelzanaty3/geopilot

On older versions: /plugin marketplace add moelzanaty3/geopilot, then /plugin install geopilot@geopilot. Commands appear as /geopilot:scan, /geopilot:fix, /geopilot:review, /geopilot:explain, /geopilot:insights and /geopilot:init; agents as geopilot:scanner and so on.

To commit the agents into one repository instead, so the whole team gets them without installing a plugin:

npx geopilot agent install --host claude-code

GitHub Copilot CLI

copilot plugin marketplace add moelzanaty3/geopilot
copilot plugin install geopilot@geopilot

Copilot CLI reads the same plugin directory as Claude Code, so it gets all five agents and the same skills.

OpenCode

npx geopilot agent install --host opencode

Writes .opencode/agents/geopilot-*.md, .opencode/commands/geopilot-*.md (run as /geopilot-scan etc.) and .opencode/skills/geo/. Read-only agents get edit: deny; the fixer gets edit: ask.

OpenAI Codex

codex plugin marketplace add moelzanaty3/geopilot
codex plugin add geopilot@geopilot

Skills run as $geopilot:scan, $geopilot:fix and so on. Codex plugins can’t carry custom agents, so each skill includes its agent’s instructions.

To get real subagents, and to share them with your team, install into the repository instead:

npx geopilot agent install --host codex

This writes .codex/agents/geopilot-*.toml and .agents/skills/, with skills run as $geopilot-scan.

Codex won’t auto-select the $geopilot:fix and $geopilot:init skills, but a fix request can still reach the fix workflow through the geo skill or the fixer agent. What protects your code is the approval each fix needs, not how the workflow started.

Anything else

npx geopilot agent install --host agents-md --write-agents-md

Adds a short section to AGENTS.md for hosts that read it.

Project installs

agent install lists every file it will create or update, then asks before writing. Pass --yes to skip the prompt in a script. It changes nothing else: no hooks, CI, lockfiles or other agent configuration.

Check your versions

npx geopilot agent status

This prints the engine version, the Claude Code skill version installed in this repository, and the status of every host. A mismatch exits non-zero. Code audits still work, but re-run agent install so live checks use the matching version.

The commands

scan runs in your session on Claude Code, Copilot and Codex, so its report is written only once. There, staying read-only is an instruction the model follows, not something the host enforces. OpenCode can enforce it, so scan runs in the read-only scanner agent there.

The agents

Audits need no CLI. For live checks, every agent pins one engine version and runs it from your PATH or through npx in an empty directory, never from the repository being scanned.

Host status

Support means the host’s own CLI installs and loads the files at the version shown. Results from a full model session can vary by host.

How results work

Every rule gets one result, and none of them are guessed:

• Clear: the agent read the code that decides this, and it’s fine.
• Problem: the agent can show the file, line and exact quote that cause it.
• Can’t tell: the code doesn’t decide this, such as a header set by your CDN. It doesn’t count for or against you, but it lowers confidence.
• Not applicable: the rule doesn’t apply to this project.

The score

Each rule has a weight from the rule catalogue. The score is a range, because a single number would leave the biggest unknowns out. The low end assumes every Can’t tell rule is a problem, and the high end assumes every one is clear. A problem on some routes earns a share of its weight, and a blocker the agent can quote caps the score at 40. Confidence is the share of applicable weight that was checked: 80% or more is High, 50–79% is Medium, and below 50% is Low.

At High confidence, the band comes from the low end: 90–100 Strong, 70–89 Good, 50–69 Needs work and 0–49 At risk. Otherwise the score says Unconfirmed, because missing evidence isn’t a fault in your site. The report shows the arithmetic, so you can check it. The CLI uses the same formula.

Live checks

Reading code can’t prove real status codes, redirects or headers. To measure them, ask the agent for a live check with your site’s URL. It runs the pinned CLI and adds a live score beside the code score, then calls out any rule where the two disagree. See Scoring.

Adding real evidence

Four CLI commands settle what neither code nor a blocked scan can. See the CLI reference.

• geopilot logs checks your access logs against the address lists crawlers publish, so it shows which real crawlers got through and where they were blocked.
• geopilot cloudflare shows crawler requests and blocks from Cloudflare. It matches by user agent, which can be spoofed.
• geopilot inspect shows Google’s index status for a URL.
• geopilot citations samples whether Perplexity cites your domain for one question, with a confidence range. It makes paid calls and is a sample, not a measure of your overall visibility.

Boundaries

• Agents never say a result was measured or verified on a live site unless a live check showed it. After a fix, they report “confirmed in code, not yet confirmed on a live site”.
• Agent edits need approval after you’ve seen the exact change. That approval is a behavioural instruction to the agent, not a technical control, and the skill says so.
• Agents stop and ask about files with uncommitted edits, more than ten files, files outside what you approved, or repository content that looks like instructions.

Insight validation

1. L1 schema — structure only.
2. L2 references — files exist at the cited commit, line ranges and normalised quotes resolve; URLs were fetched in the cited run and selectors match its retained snapshot; fingerprints and insight ids exist. Results: evidence resolved, reference invalid, stale, duplicate. With no retained run, references are unchecked and the command exits 4.
3. L3 semantic quality — human or model evaluation; never affects readiness or gates.