feat: expose --max-cost CLI flag with cost threshold warnings

[rubenmarcus]

Summary

• Exposes the existing maxCost infrastructure as a --max-cost <amount> CLI flag
• Opt-in only (no default limit) — won't break existing long-running loops
• Adds cost threshold warnings at $2, $5, $10 when no budget is set
• Users see: ⚠ Estimated cost has reached $5. Use --max-cost to set a budget limit.

Context

User feedback: spent $10 on a simple task with no visibility into costs. The maxCost plumbing existed in executor.ts and cost-tracker.ts but was never wired to the CLI.

Test plan

• ralph-starter run --help shows --max-cost option
• ralph-starter run --max-cost 1 "test" stops loop when cost reaches $1
• Without --max-cost, warnings appear at $2/$5/$10 thresholds
• pnpm build compiles cleanly
• pnpm test:run passes all 171 tests

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

Issue Linking Reminder

This PR doesn't appear to have a linked issue. Consider linking to:

• This repo: Closes #123
• ralph-ideas: Closes multivmlabs/ralph-ideas#123

Using Closes, Fixes, or Resolves will auto-close the issue when this PR is merged.

---

If this PR doesn't need an issue, you can ignore this message.

[github-actions]

✔️ Bundle Size Analysis

Metric	Value
Base	1927.54 KB
PR	1928.82 KB
Diff	1.28 KB (0%)

Bundle breakdown

156K	dist/auth
32K	dist/automation
4.0K	dist/cli.d.ts
4.0K	dist/cli.d.ts.map
16K	dist/cli.js
12K	dist/cli.js.map
492K	dist/commands
28K	dist/config
4.0K	dist/index.d.ts
4.0K	dist/index.d.ts.map
4.0K	dist/index.js
4.0K	dist/index.js.map
560K	dist/integrations
84K	dist/llm
736K	dist/loop
188K	dist/mcp
32K	dist/presets
92K	dist/setup
36K	dist/skills
392K	dist/sources
76K	dist/ui
84K	dist/utils
336K	dist/wizard

[greptile-apps]

Greptile Summary

This PR exposes the existing maxCost infrastructure as a user-facing --max-cost CLI flag and adds helpful cost threshold warnings.

Key Changes:

• Added --max-cost <amount> CLI option in src/cli.ts using parseFloat parser
• Threaded maxCost through RunCommandOptions interface and passed to loop executor
• Added proactive warnings at $2, $5, $10 thresholds when no budget is set
• Warnings only appear when --max-cost is not specified, avoiding noise for budget-conscious users

Implementation Quality:

• Correctly integrates with existing CostTracker.isOverBudget() method (already tested)
• Warning logic uses prevTotal comparison to ensure warnings fire exactly once per threshold
• Follows existing CLI option patterns (parseFloat, descriptive help text)
• Opt-in design preserves backward compatibility - no breaking changes

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are minimal, well-contained, and integrate cleanly with existing infrastructure. The CostTracker.isOverBudget() method is already tested. Warning logic is straightforward with proper threshold crossing detection. No breaking changes, purely additive feature.
• No files require special attention

Important Files Changed

Filename	Overview
src/cli.ts	Added --max-cost CLI flag with parseFloat parser, following existing option patterns
src/commands/run.ts	Added maxCost to interface and passed through to executor, clean integration
src/loop/executor.ts	Implemented threshold warnings at $2/$5/$10 when no budget set, clean logic with no side effects

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User runs CLI with --max-cost flag] --> B[cli.ts parses flag with parseFloat]
    B --> C[run.ts receives maxCost in options]
    C --> D[maxCost passed to executor.ts LoopOptions]
    D --> E[CostTracker initialized with maxCost config]
    E --> F[Loop iteration executes]
    F --> G[CostTracker.recordIteration tracks cost]
    G --> H{maxCost set?}
    H -->|Yes| I[CostTracker.isOverBudget checks budget]
    H -->|No| J[Check threshold crossings]
    I -->|Over budget| K[Break loop with cost_ceiling exit]
    I -->|Under budget| L[Continue loop]
    J -->|Crossed $2/$5/$10| M[Display yellow warning with --max-cost tip]
    J -->|No crossing| L
    M --> L[Continue loop]
    L --> F

Loading

_{Last reviewed commit: 9164b09}