ai-rail 0.1.0a17

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

AI Rail

AI Rail is a local CLI for keeping AI coding work scoped, reviewable, and easy to resume.

AI coding agents can drift, edit too much, skip checks, or lose context between chats. AI Rail gives your Git repo a local project brain and a safe one-issue-at-a-time workflow, so tools like ChatGPT, Codex, Claude, Cursor, and Aider can work from the same source of truth.

It is not a hosted service and it does not run AI models. It runs on your machine, shells out to git, gh, and your local checks, and gives you paste-ready prompts for the AI tools you already use.

pipx install ai-rail
rail init
rail plan --copy
rail import
rail n
rail v
rail s "type(scope): message"

Alpha Status

AI Rail is public alpha software. It is intended for developers who are comfortable with Git, GitHub Issues, and local command-line tools. The default workflow is conservative: it tries to protect your repo from stale reviews, stale checks, unsafe files, and accidental broad changes.

Install

Prerequisites:

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

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

5-Minute 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
gh issue create --title "Add todo body validation" --body-file issues/001-add-body-validation.md
rail n

rail n starts the next issue and copies the implementation prompt when clipboard support is available. Paste that prompt into your AI coding tool.

Normal Workflow

Inside a Git repo, initialize AI Rail:

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

For a new repo with no scoped GitHub Issues yet, create the roadmap and first issue slice:

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

The planning AI creates or updates one GitHub roadmap issue labeled ai-rail-roadmap. That issue stays open as the remote .rail/PROJECT.md memory mirror; normal implementation task issues are the ones AI Rail closes after shipping. The strict PROJECT.md roadmap block should never list the roadmap mirror issue itself as a task.

Then work one issue at a time:

rail n
# paste/run the generated prompt in your AI coding tool

rail v
# paste the generated review prompt into an AI reviewer

rail s "type(scope): message"

After several shipped issues, ask a planning/review AI to audit the phase, update the roadmap issue, and create the next slice:

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

Long command names are available too:

rail next --copy
rail verify --copy
rail ship "type(scope): message"

Core Commands

Command	Purpose
rail init	Add AI Rail files to the current 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 prompt to audit/update the current roadmap phase
rail next / rail n	Start the next issue and generate the first coding prompt
rail verify / rail v	Capture review info, run checks, and generate an audit prompt
rail ship / rail s	Commit the issue branch, merge/push default, close the issue, and mark done
rail handoff	Generate portable context for another AI session/model
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 walkthrough
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, lint, typecheck, then test. You can override checks manually:

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

Safety Model

AI Rail is designed for small, reviewable steps:

• rail next starts one GitHub issue at a time.
• rail verify captures the reviewed diff, runs configured local checks, and saves a verified snapshot.
• rail ship trusts that snapshot only when the working tree and configured checks still match.
• rail ship closes the GitHub issue only after default-branch integration succeeds.
• Dangerous or generated paths such as .env, keys, local databases, node_modules/, dist/, .rail/brain/, and .rail/state/ are blocked by default.

Use rail ship --recheck "type(scope): message" when you intentionally want checks rerun during ship. Escape hatches exist for advanced users, but the normal path is intentionally conservative.

Project Brain, Handoff, And Export

.rail/PROJECT.md is the local project memory and roadmap brain. The GitHub roadmap issue is the remote roadmap mirror. GitHub implementation issues are the active execution queue, not the whole long-term roadmap.

rail snapshot writes portable context into:

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

Use handoff when switching tools or opening a new chat:

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

Use export when you want tool-specific instruction files from the same project brain:

rail export --dry-run
rail export

Generated targets:

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

Exports are guarded. 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 numbered .rail.bak.N backup.

Privacy

AI Rail does not send your code anywhere by itself. It shells out to git, gh, and your configured local checks. You decide what generated prompts, handoffs, review packs, and exports to paste into AI tools.

Privacy note: rail snapshot, handoff, and rail export can include active issue body text, project state, current task details, changed file names, and generated .rail/brain/ context. Review generated files before sharing or committing them.

Security note: rail verify and rail checks run 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 them.

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

Who This Is For

AI Rail is for developers who:

• use one or more AI coding tools 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

AI Rail is not an AI model, agent runtime, hosted service, replacement for Git, or replacement for your test suite.

Docs

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

Author

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

License

Apache License 2.0.