Get started fast.

AgentFlight runs on Node.js 20 or newer (macOS, Linux, Windows) through npx, with no install scripts and no API key. Run init from the root of the repo you want to record. It writes a local .agentflight/ directory and nothing else.

A full session runs from the first agent prompt to a reviewable handoff:

npx agentflight@latest init
npx agentflight@latest start --task "Add password reset flow"

# Run Codex, Claude Code, Cursor, or your coding agent normally

npx agentflight@latest verify -- npm test
npx agentflight@latest snapshot --note "Initial implementation verified"
npx agentflight@latest status
npx agentflight@latest report
npx agentflight@latest replay
npx agentflight@latest resume

AgentFlight ships a small vocabulary the rest of the page reuses.

• Session. A recorded unit of work. start opens one with the task title, git branch, commit, dirty state, package manager, and detected tools.
• Event. A timeline entry: session start, a verification attempt, a snapshot, or a generated artifact. Each session keeps an ordered events list.
• Verification evidence. What verify captures when it runs a command: the command, timestamps, duration, exit code, pass or fail status, and the stdout and stderr file paths.
• Snapshot. A checkpoint recorded by snapshot --note "...": git state, changed files, risk level, verification summary, and your note.
• Risk. A rough category for the changed files (for example dependency, backend, or unknown), paired with the next safest action.
• Proof report. The Markdown file report writes: task, timeline, changed files, risk, verification evidence, a recommendation, and the next action.
• Replay. The self-contained HTML file replay writes: session events, snapshots, verification cards, changed-file groups, and readiness.
• Resume prompt. The Codex or Claude-ready prompt resume writes: current state, latest snapshot, verification state, proof gaps, next action, and guardrails.
• .agentflight/. The local directory that holds all of the above. Runtime data is git-ignored by default.

agentflight start --task "..." opens a session and writes the current handoff. It records the task title, git branch, commit, dirty state, package manager, and which coding tools are available, so every later artifact has context.

Run your coding agent normally after this. AgentFlight does not drive the agent or edit your code. It records what happens around it.

agentflight verify -- <command> runs a proof command and records the command, timestamps, duration, exit code, pass or fail status, and the stdout and stderr paths under .agentflight/evidence/. Use the check your project already runs.

agentflight verify with no command runs the commands listed in .agentflight/config.json. AgentFlight does not claim a test passed unless the command actually passed.

agentflight status answers what changed, how risky it is, what proof exists, what proof is missing, and what to do next. It groups changed files by rough risk area and points at the next safest command.

agentflight snapshot --note "..." records the current git state, changed files, risk level, and verification summary as a timeline event, with your note attached. Snapshots are how the replay and the resume prompt show progress through a session instead of only its final state.

agentflight report writes a Markdown proof report with the task, timeline, changed files, risk, verification evidence, a recommendation, and the next action. agentflight replay writes a self-contained HTML timeline you open in a browser: session events, snapshots, verification cards, and changed-file groups.

Both are local files under .agentflight/reports/, and neither uploads anything.

agentflight resume prints and saves a continuation prompt for the next agent or reviewer. It includes the task, latest snapshot, verification state, proof gaps, the next action, and guardrails that keep the work scoped: stay on the current task, do not claim completion without proof, and run verification before declaring success.

agentflight doctor checks Node, npm, git, your package manager, config, writable paths, the current session, ProjScan, AgentLoopKit, and common scripts. Run it first if a command misbehaves.

init creates a .agentflight/ directory in your repo:

• config.json holds local-first project settings, and is not git-ignored, so you can commit your defaults.
• sessions/ holds session metadata and the events timeline.
• current/ holds the active session, handoff, and resume prompt.
• reports/ holds Markdown proof reports and HTML replays.
• evidence/ holds stdout and stderr from captured verification runs.

Runtime data under sessions/, current/, reports/, and evidence/ is git-ignored by default. Reports include filenames and summaries, not full source diffs.

AgentFlight integrates with two open engines from Baseframe Labs: ProjScan for repo intelligence and risk signals, and AgentLoopKit for task discipline, verification evidence, and handoffs. Both are optional. When either tool is missing, AgentFlight keeps recording the session.

AgentFlight is local-first and deliberately narrow.

• No telemetry, no login, no cloud sync, and no source upload.
• No LLM calls. AgentFlight records and reports. It does not generate code.
• Verification commands run only when you invoke verify or a configured command. Nothing runs in the background.
• It reads git status and package metadata and writes its own artifacts under .agentflight/. It does not edit your source.
• Reports include filenames and summaries by default, not full code diffs.
• Apache-2.0 licensed. upgrade, license, and login are placeholders today, and AgentFlight Pro and Team do not exist yet.