Getting Started

Install Propel, run setup on your laptop or your cluster, and start working. You will not need to learn a single command to get the pipeline running.

1. Install Propel

Clone the repository and install it in editable mode:

git clone https://github.com/KevinBian107/propel.git
cd propel

pip install -e .      # inside an activated conda env or virtualenv

The install is editable: changes you make to the repo take effect immediately, which matters because Propel is meant to be customized.

2. Set Up — Local or Cluster

Run propel with no arguments:

propel

It checks for git, Claude Code and Codex, installs what's missing, signs you in, and installs Propel into your project. There are two versions of this step. propel picks one from the machine it's running on and says which in one line. It never asks.

Both versions install Claude Code and Codex the same way, with the vendors' own native installers. These are single binaries in ~/.local/bin. They need no Node, no npm and no sudo, which matters on a cluster where you can't install system packages:

curl -fsSL https://claude.ai/install.sh | bash          # Claude Code
curl -fsSL https://chatgpt.com/codex/install.sh | sh    # Codex

Propel downloads each script to a file before running it, so a failed download is reported as a failure rather than looking like success. Node.js only matters if you want the optional claude-hud status-line plugin.

Local: the Setup Console

A page opens in your browser. It shows what you already have and offers a button for everything you don't:

• git: installed with Homebrew when it's available, otherwise a link to the download page
• Claude Code: the native installer, then a terminal opens for the sign-in
• OpenAI Codex: the second model. Native installer, then a terminal opens for the OAuth flow
• Plugins: claude-hud and code-review, each with its publisher named. Never installed without a click
• Propel itself: one click installs it into the project you're in

The two logins genuinely need a terminal. A browser page can't provide a TTY, so the console opens a real one already running the right command instead of pretending. If it can't, it shows you the command to paste.

Cluster: Terminal Setup

On a machine with no display, propel runs the same checklist in the terminal. Nothing needs to be forwarded and there's no page to open:

$ propel
No display here (cluster, container or SSH), so setup runs in the terminal.

  ✓ git            git version 2.43.0
  ✗ Claude Code    not installed
  – OpenAI Codex   not installed  (optional)
  ...

  Claude Code is not installed (required).
    Installer: curl -fsSL https://claude.ai/install.sh | bash  ->  ~/.local/bin
  Install Claude Code now? [Y/n]

It asks before every change, in this order:

1. Install Claude Code (required) and Codex (optional) with the native installers.
2. PATH: Claude's installer doesn't edit your shell config. If ~/.local/bin isn't on your PATH, setup offers to add one line to ~/.bashrc (or ~/.zshrc). Propel itself finds the tools there either way.
3. Sign in, inline: claude auth login, then codex login --device-auth. Each prints a URL and a code. Open the URL on any device, your laptop included, and approve it. The cluster never needs a browser.
4. Plugins: the default is No. A plugin runs its publisher's code in your sessions, so that call stays yours.
5. Install Propel into the current project (propel init).

There's no browser pop-up on a cluster; that's expected. If you skip a sign-in, the closing summary repeats the command to run. It's safe to re-run. Each run picks up whatever is still missing. If stdin isn't a terminal (a notebook !propel, a batch job, a pipe), it changes nothing: it prints the checklist and the exact commands to run, and exits 0.

Or Do It by Hand

Everything either version does, as commands:

curl -fsSL https://claude.ai/install.sh | bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
claude auth login
codex login --device-auth
cd /path/to/your/project
propel init

propel init, from any of the three paths, does the same thing:

• Copies all skills, agents, commands, hooks and scripts into .claude/
• Configures four hooks in settings.local.json: session context, working memory, the per-turn routing card, and the PostToolUse auditor dispatch that fires after every source edit
• Seeds .propel/codex.json with the dual-model layer enabled
• Adds scratch/, sessions/, .propel/, .claude/, and propel/ to .gitignore

3. Start Claude and Describe Your Problem

Launch Claude Code in your project:

claude

Then just say what you're working on. There is no setup step inside the session, no mode to pick, and no skill to name.

Mode Selection Happens For You

Propel reads your first message, picks one of the four modes, and says which and why in a single line:

You:     loss goes NaN around step 500, here's the trace

Claude:  Debugger Mode — specific wrong behavior with an
         expectation attached. (/switch any time.)

It switches again on its own when the work crosses a boundary, and always tells you. /switch overrides it whenever you disagree — and if you do, that correction gets noted, because it's signal about where the inference went wrong.

Prefer to choose explicitly? Run /intro. That's the one place the four-mode menu still appears, along with the full tour of commands, skills and agents.

The Second Model

If Codex is installed and signed in, it is consulted automatically at every gate. You'll see a line like:

◆ Consulting Codex — Gate 2 (design): "Propose the strongest
  alternative and name the failure mode this design doesn't address."

If it isn't set up, Propel says so once and runs single-model. It never blocks. See Codex — Two Models, or turn it off with /disable-codex.

/intro: The Full Tour

Run it any time for the complete list of commands, skills, and agents, and what each one is triggered by.

Drafts Your CLAUDE.md

If you have an existing codebase, Propel scans it and generates a project-specific .claude/CLAUDE.md with code style, conventions, and structure already filled in. If you're starting from an empty repo, it seeds a minimal CLAUDE.md that grows progressively as you work — Gate 0 answers fill in research context, first code written fills in conventions, investigations fill in domain pitfalls.

Project Customization (Optional)

Analyzes your codebase to build a persistent profile in .propel/ that captures naming conventions, domain context, commit patterns, and more. Claude references this silently on every session start, so you don't have to re-explain your conventions. Takes ~2–3 minutes; you can also run it anytime by saying "customize Propel".

What Happens Next

Describe what you want to do, and Propel walks the pipeline. Every step below happens without you asking for it:

1. Ask scoping questions (Gate 0) — one at a time, before investigating
2. Ground the work (Q0) — which repo, which paper, which reference to adapt from
3. Scaffold an investigation — several investigator subagents in parallel, into scratch/{date}-{name}/README.md
4. Present findings (Gate 1) — with a Codex consult folded in
5. Propose a plan (Gate 2) — and Codex's strongest alternative to it
6. Audit each component (Gate 3) — auditors named by a hook, plus Codex on substantive diffs
7. Present diagnosis (Gate 4) — before any bug fix, with competing explanations

Example First Session

You:  I want to implement residual vector quantization from this paper [link]

Claude: Engineer Mode — there's something to build, so the full
        pipeline applies. (/switch any time.)

        [Gate 0 fires — asks scoping questions one at a time]
        "Are you replacing the existing VQ entirely, or adding RVQ as
         an alternative?"
        "What depth? Is 2 a hard choice or should it support arbitrary
         depth?"
        ...

You:  [answer questions]

Claude: [writes scope statement, gets confirmation]
        [dispatches 4 investigators in parallel]
        [creates scratch/2026-09-19-rvq/README.md]
        ◆ Consulting Codex — Gate 1: "What should this
          investigation have checked and didn't?"
        [Gate 1 — presents findings, tagged [claude]/[codex]/[both]]

You:  [make design decisions]

Claude: [research-design produces paper-to-code mapping]
        [writing-plans breaks into micro-tasks]
        ◆ Consulting Codex — Gate 2: "Propose the strongest
          alternative and the failure mode this doesn't address."
        [Gate 2 — presents plan + Codex's alternative as YOUR choice]

You:  go

Claude: [implementer builds component 1]
        [spec-reviewer checks it against the plan]
        [hook names the auditors; they run in parallel]
        [Gate 3 — merged audit card, attributed by source]
        ...

Key Slash Commands

All Propel commands are marked with [Propel] in their description.

What to Do After /clear

When you clear context mid-session, follow these steps to resume cleanly:

1. Run /primer to reload project context
2. Read your investigation README: scratch/{investigation}/README.md
3. Check the plan for where you left off: scratch/{investigation}/plan.md
4. Continue from the "Next Steps" section