command-preflight

Privacy-first command checks for coding-agent CLIs.

command-preflight reduces wasted retries caused by shell syntax, path, executable, and cross-shell mistakes. It is designed for Codex CLI, Claude Code, and other MCP-capable terminal agents.

The default client is local-only:

• no account or API key
• no telemetry or network calls
• no command execution from the preflight tool
• redaction and error fingerprints are generated on the host

Install

The latest binaries are published on the GitHub Releases page.

Windows users should download the matching ZIP, extract every file, and double-click INSTALL.cmd. It installs the binary under %LOCALAPPDATA%\CommandPreflight, installs the bundled Skills, and registers MCP for any installed Codex or Claude Code CLI. It asks separately before enabling community lookup or moderated reporting. Do not double-click command-preflight.exe as an installer; it is a command-line program.

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/cocojojo5213/command-preflight/main/scripts/install.sh | sh

PowerShell:

irm https://raw.githubusercontent.com/cocojojo5213/command-preflight/main/scripts/install.ps1 | iex

To explicitly opt in to the project-maintained read-only knowledge lookup during setup:

$env:COMMAND_PREFLIGHT_KNOWLEDGE_URL='https://preflight.52131415.xyz'; irm https://raw.githubusercontent.com/cocojojo5213/command-preflight/main/scripts/install.ps1 | iex

The installer keeps lookup offline when that variable is absent. To build from source:

go install github.com/cocojojo5213/command-preflight/cmd/command-preflight@main

Use directly

command-preflight preflight --shell bash --command "printf '%s\\n' ok" --json
command-preflight fingerprint --shell powershell --command "git checkout" --stderr "unknown option" --exit-code 129
command-preflight doctor

Exit codes are 0 for passed, 1 for failed, and 2 for review.

Connect a CLI

The installer runs the equivalent setup automatically. To configure it later, use:

Codex:

codex mcp add command-preflight -- command-preflight mcp

Claude Code:

claude mcp add --scope user command-preflight -- command-preflight mcp

See integrations for generic MCP configuration and Skill installation.

To configure the optional public lookup for both clients in one step:

command-preflight setup --client both --knowledge-url https://preflight.52131415.xyz --apply

Community reporting is a separate explicit opt-in. When enabled, the MCP tool can submit a verified resolution to the server moderation queue:

command-preflight setup --client both \
  --knowledge-url https://preflight.52131415.xyz \
  --report-url https://preflight.52131415.xyz \
  --enable-reporting --apply

Reports contain only the public fingerprint, a short redacted fix summary, and a safe verification step. They never contain the original command, paths, environment variables, credentials, or terminal output.

If you are asking an AI agent to install this project, give it the repository URL and ask it to detect the host OS, use the release installer, run doctor, and verify the MCP registration. Keep cloud lookup disabled unless you explicitly want the read-only endpoint.

The Codex Skill is installed under $CODEX_HOME/skills or ~/.codex/skills by default. Set COMMAND_PREFLIGHT_CODEX_SKILL_DIR for a non-standard layout.

Optional cloud knowledge service

The same repository also builds command-preflight-server. It is a small read-only-by-default HTTP service for curated, privacy-preserving error knowledge and an optional moderated report queue. It is not required by the local client.

The project currently maintains a public TLS endpoint:

https://preflight.52131415.xyz

It accepts GET lookups by public fingerprint ID. When reporting_enabled is true, explicitly opted-in clients may POST constrained reports into a private moderation queue; public PUT requests still return 403. A report is not queryable until an operator approves and separately publishes it. Cloudflare handles normal request metadata such as an IP address; the application does not accept or persist original commands, paths, environment variables, terminal output, accounts, client IP addresses, or user-agent strings. Forks and private deployments can use their own endpoint.

Start it with Docker Compose:

git clone https://github.com/cocojojo5213/command-preflight.git
cd command-preflight
docker compose up -d --build
curl -fsS http://127.0.0.1:8787/healthz

The Compose setup binds to localhost, stores data in a Docker named volume, and disables report submission by default. The container is non-root, read-only, capability-free, resource-limited, and runs on a dedicated bridge without IP masquerading or inter-container forwarding. Put a TLS-terminating reverse proxy or Cloudflare Tunnel in front of it before exposing it to a network. To deliberately change the container listen address, copy .env.example to .env and set COMMAND_PREFLIGHT_BIND; to publish only on a private Tailnet interface, set COMMAND_PREFLIGHT_PUBLISHED_BIND to that IP and port. Do not expose the moderation API without a strong admin token and a private access boundary. A host bind mount can be selected with COMMAND_PREFLIGHT_DATA_VOLUME=./data (the directory must be writable by container UID 65532). Public reporting also has global per-minute and per-UTC-day caps, but a public edge rate limiter remains required.

Lookups contain only a public fingerprint ID:

curl -fsS http://127.0.0.1:8787/v1/knowledge/cp1-0123456789abcdef0123

Enable a local lookup explicitly by setting the URL (the default remains offline):

export COMMAND_PREFLIGHT_KNOWLEDGE_URL=http://127.0.0.1:8787
command-preflight lookup --fingerprint-id cp1-0123456789abcdef0123 --json

For the public endpoint:

export COMMAND_PREFLIGHT_KNOWLEDGE_URL=https://preflight.52131415.xyz
command-preflight lookup --fingerprint-id cp1-0123456789abcdef0123 --json

The lookup sends only the cp1-... ID. It never sends commands, environment variables, paths, or terminal output. Reporting remains off unless COMMAND_PREFLIGHT_REPORTING=on is explicitly configured. The public report endpoint creates only pending queue records; the authenticated moderation API is responsible for approve/reject/hold decisions and publication.

Development

go test ./...
go run ./cmd/command-preflight doctor
go run ./cmd/command-preflight mcp

See the cloud deployment guide, the architecture, and the privacy model before enabling an opt-in lookup or reporting adapter.

Status

This is an early open-source MVP. Shell parsing and CLI grammar are inherently platform- and version-specific; a successful preflight is not permission to skip normal approvals or postcondition checks.

Acknowledgements

Command Preflight recognizes and appreciates the LINUX DO community for fostering open discussion, mutual support, and practical technical sharing.