v0.1 beta · open source

Ship agent workflowsthat survive a fresh session.

agent-preflight scans your repo for the cheap bugs that break agent workflows — local-only paths, missing install commands, undocumented env vars. Catch them at commit, not after an hour of confused debugging.

$ npx agent-preflight@beta check .

No signup. No config. 30-second scan.

preflight-report.md
# Preflight Report
⚠2 findings (1 fail, 1 warn)
Fail
local-only-pathAGENTS.md:18
'/Users/steipete/data' won't resolve
on a fresh machine.
Warn
env-var-undocumented.mcp.json:3
'SECRET_KEY' used by MCP 'api'
but never documented.
✓AGENTS.md found · install present

// what it checks

Six high-signal checks. One sentence each.

Reproducibility over quality scoring — we don't grade your prompt-writing, we answer: if a fresh agent session opens this repo tomorrow, will the documented workflow actually run?

agents-md-missing

Missing agent entry point

No AGENTS.md / CLAUDE.md / .cursorrules — agents have no map.

local-only-path

Local-only paths

Hardcoded /home/, /Users/, C:\Users\ paths that break in fresh environments.

stale-reference

Stale references

Workflow cites a tool, skill, or MCP server that isn't declared anywhere.

install-command-missing

No install command

Setup section exists but no runnable install (e.g. npm install).

env-var-undocumented

Undocumented env vars

Env vars consumed by MCP configs but never named in setup docs.

smoke-command-missing

No smoke check

No "does it start?" command a fresh session can run to confirm setup.

// a real scan

The bug that breaks your agent, found in seconds.

A path that exists on your machine — and nowhere else. Here's what the report looks like before that fresh session ever opens the repo.

npx agent-preflight@beta check .
# Preflight Report
⚠2 findings (1 fail, 1 warn)
Fail
local-only-pathAGENTS.md:18
> '/Users/steipete/data' won't resolve on a fresh machine.
Suggested fix:
> Use repo-relative paths like ./data
> or $(pwd)/data.
Warn
env-var-undocumented.mcp.json:3
> 'SECRET_KEY' used by MCP 'api' but never documented in setup.
✓AGENTS.md found · install present · MCP config parsed

↑ this path will break in CI

// continuous preflight

Block the merge before the break.

.github/workflows/preflight.yml
name: Preflight
on: [pull_request]
jobs:
  preflight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: agent-preflight/agent-preflight@v0.1
        with:
          path: .
AP
agent-preflight-botcommented 2 minutes ago
✓No fail findings — agent workflow is reproducible.
⚠ 1 warn ·env-var-undocumented
.mcp.json:3 — 'SECRET_KEY' undocumented
Mergeablepreflight check · 4.2s

Fails the build at the severity you choose. Posts the report as a PR comment.

// early access

Get early access to hosted scans.

Private repos, scan history, PR integration. Drop your email — one message when it launches. No spam.

Or run the CLI now:npx agent-preflight@beta check .