ai-rail 0.1.0a14

A local-first workflow rail and portable project brain for AI-assisted development.

AI Rail

Never explain your project twice to AI.

AI Rail is a local-first CLI that keeps AI-assisted development focused, repeatable, and safe.

It gives every Git repo a portable project brain, a simple daily workflow, and scoped prompts for tools like ChatGPT, Codex, Claude, Cursor, and Aider - so you can move between AI tools without re-explaining the codebase, losing context, or letting the coding agent drift into unrelated files.

rail n  -> start the next scoped task
rail v  -> review, run local checks, and create an audit prompt
rail s  -> safely commit, push, close, and sync
rail h  -> continue in a new AI chat with full project context

AI Rail keeps the coding agent on the active issue, keeps an AI reviewer (ChatGPT, Claude, or any LLM) in the audit loop, and lets your own machine run the tests - saving tokens, reducing over-coding, and making AI development feel controlled instead of chaotic.

Prerequisites

• Python 3.10+ and pipx
• Git with a configured remote
• GitHub CLI (gh) installed and authenticated (gh auth login)

AI Rail uses Git for repository state and delegates GitHub Issue operations to gh. Run gh auth login before using AI Rail on a new machine.

Who This Is For

AI Rail is for developers who:

• use more than one AI coding tool on the same repo
• want GitHub Issues to be the task source of truth
• want repeatable prompts, review packs, checks, and handoffs
• prefer local-first tooling over hosted workflow state
• work solo or in small repos where conservative commit safety matters

What AI Rail Is Not

AI Rail is not:

• an AI model, agent runtime, or hosted service
• a replacement for Git, GitHub Issues, or your test suite
• a project management system for large teams
• a tool that sends code to a remote service by itself
• a way to bypass review, checks, or secret-file safety

Install

AI Rail is currently alpha software.

Recommended public install:

pipx install ai-rail
rail --version
rail demo

If pipx is not installed yet:

python -m pip install --user pipx
python -m pipx ensurepath

Restart your terminal, then run:

pipx install ai-rail

Latest source from GitHub:

pipx install git+https://github.com/afshinsb/ai-rail.git
rail --version

Contributor install from this source checkout:

git clone https://github.com/afshinsb/ai-rail.git
cd ai-rail
python -m pip install -e ".[dev]"
rail --version

Quick Demo

Print the built-in walkthrough:

rail demo

Try the bundled demo app:

cd examples/demo-todo
rail init --stack node --project-name "AI Rail Demo TODO"
rail doctor
npm run check
# requires: gh auth login
gh issue create --title "Add todo body validation" --body-file issues/001-add-body-validation.md
rail next --copy

Full Workflow

For a new repo with no scoped issues yet:

rail plan --copy
# paste into a GitHub-connected AI agent

The AI creates or updates one GitHub roadmap issue as the remote roadmap mirror and creates only the first active execution slice as GitHub Issues.

rail import
# import the roadmap issue into local .rail/PROJECT.md

.rail/PROJECT.md is the full local project memory and roadmap brain. GitHub Issues are the active task execution queue, not the entire long-term roadmap.

Then work one issue at a time:

rail n
# paste into coding agent

rail v
# paste into AI reviewer

rail s "type(scope): message"

After several shipped issues, audit and update the phase:

rail phase --copy
# paste into a GitHub-connected AI reviewer/agent

The phase audit updates project memory, checks completed work against the roadmap, and adjusts upcoming phases when needed.

rail import
# refresh local .rail/PROJECT.md from the updated roadmap issue

Then continue:

rail n

60-Second Quickstart

Inside any Git repo:

rail init --stack node --project-name "My Project"
rail doctor
rail resume

Daily loop:

rail next --copy
# paste/run the generated prompt in your AI coding tool
rail verify --copy
# paste the generated review prompt into any AI reviewer for audit
rail ship "type(scope): message"

Short alias loop:

rail n
# paste/run the generated prompt in your AI coding tool
rail v
# paste the generated review prompt into any AI reviewer for audit
rail s "type(scope): message"

rail verify runs checks and saves a verified snapshot of the reviewed diff. rail ship trusts that snapshot when the working tree still matches it, so the normal ship path does not rerun checks. Use rail ship --recheck "type(scope): message" when you intentionally want checks rerun during ship.

When switching AI tools or opening a new chat:

rail snapshot
rail handoff --for chatgpt --include-review --include-checks --copy

To update tool-specific AI instruction files from the same project brain:

rail export

Core Commands

Command	Purpose
rail init	Add AI Rail files to a repo
rail resume	Show where you stopped
rail plan	Generate a GitHub-connected AI prompt to create a phased issue roadmap
rail import	Import the GitHub roadmap issue into local .rail/PROJECT.md
rail phase	Generate a GitHub-connected AI prompt to audit/update the current roadmap phase
rail next	Start the next issue and generate the first prompt
rail handoff	Generate portable context for another AI session/model
rail verify	Capture review info, run checks, and generate an audit prompt
rail ship	Commit, push, close the issue, mark done, and sync
rail snapshot	Refresh .rail/brain/ project-brain files
rail export	Generate AGENTS.md, CLAUDE.md, Cursor rules, AIDER.md, and Copilot instructions
rail demo	Print the public demo script
rail release-check	Check packaging/docs readiness

Common aliases are thin wrappers over the long commands: rail r for resume, rail n for next --copy, rail p for plan --copy, rail ph for phase --copy, rail im for import, rail v for verify --copy, rail s for ship, rail snap for snapshot, rail h/hc/hg/hl for handoffs, rail x/xd/xf for exports, and rail rc for release-check.

Detailed commands such as rail start, rail prompt, rail review, rail checks, rail commit, rail issue-close, rail done, and rail sync remain available for manual control.

For Node repos, rail init --stack node inspects package.json scripts and chooses the first available check command from check, typecheck, lint, test, then build. You can override checks manually:

rail checks --run "npm run typecheck"
rail checks --run "npm run typecheck" --run "npm run lint"

Portable Project Brain

.rail/PROJECT.md is the full local project memory, roadmap brain, phase tracker, and next-task direction file. The GitHub roadmap issue is the remote roadmap mirror. GitHub implementation issues are only the active execution queue.

.rail/PROJECT.md may contain human-readable context, but roadmap task state lives in exactly one AI RAIL ROADMAP START/END block. Rail only updates task status inside that strict block. Task lines use - [ ] ISSUE | TASK_ID | TITLE, where ISSUE is #123 for active GitHub issues or TBD for future tasks. The phase AI creates the next issue slice and replaces TBD with issue numbers during rail phase --copy / rail import.

rail snapshot writes:

.rail/brain/PROJECT.md
.rail/brain/CURRENT_TASK.md
.rail/brain/STATUS.md
.rail/brain/RECENT_HISTORY.md
.rail/brain/HANDOFF.md

rail handoff --for codex|chatgpt|claude|cursor|aider --copy turns that brain into a paste-ready handoff so a new AI session can continue from the current project state.

Tool-Specific Exports

rail export turns the single AI Rail project brain into files that different AI coding tools already know how to read:

AGENTS.md
CLAUDE.md
AIDER.md
.cursor/rules/ai-rail.mdc
.github/copilot-instructions.md

Exports are safe by default. AI Rail updates its own managed block when markers are present, but refuses to overwrite existing human files unless you pass --force, which first writes a .rail.bak backup.

Safety Defaults

rail ship refuses unsafe commits by default when:

• there is no passing verified snapshot from rail verify
• files changed after the last verified snapshot
• configured checks changed after the last verified snapshot
• dangerous/generated files such as .env, keys, local databases, node_modules/, dist/, or .rail/state/ are changed

Escape hatches exist for advanced users, but the normal path is intentionally conservative.

Local-First Privacy

AI Rail does not send your code anywhere by itself. It shells out to git, gh, and your configured local checks.

Security: rail verify runs the check commands configured in .rail/config.json using the system shell. Always review .rail/config.json in repositories you did not author before running rail verify or rail checks.

By default, .rail/state/history.jsonl is ignored by git to avoid committing personal workflow history into team repos.

License: Apache License 2.0.

Author

• Afshin Saberi
• GitHub: https://github.com/afshinsb
• Website: https://theafshin.com

Docs

• Quickstart
• Install
• Commands
• Workflows
• Architecture
• Release checklist
• Roadmap