feat: add --stale CLI option for agentic coding systems

[holyhli]

Problem Statement

Modern agentic coding systems (Claude Code, GitHub Copilot Workspace, OpenCode, Cursor with Composer, etc.) build test-driven harness systems that run tests continuously during development loops. These agents:

• Make small, incremental changes to codebases
• Run tests after every change for validation
• Need fast feedback cycles to maintain productivity
• Often work in environments without git history (containers, temporary workspaces)

Running full test suites on every agent iteration creates a major bottleneck in agent productivity.

Proposed Solution

Add a --stale CLI option (inspired by Elixir Mix) that runs only test files whose transitive module dependencies have changed since the last --stale run.

How It Works

1. First run: All tests execute, manifest generated with file mtimes
2. Subsequent runs: Only tests with changed dependencies execute
3. Tracking: Uses filesystem mtime comparison (fast, no git required)
4. Dependencies: Tracks test → module → module's imports recursively

Example - Agent Workflow

# Agent modifies src/parser.ts
vitest run --stale
# ✓ Only runs tests importing parser.ts (directly/transitively)
# ✓ 10x faster than full suite
# ✓ Agent gets immediate feedback

# Agent makes another change
vitest run --stale
# ✓ Only newly affected tests run
# ✓ Agent maintains rapid iteration

Why Not --changed?

• --changed requires git (many agent environments don't have it)
• --changed compares to a git ref (not optimized for rapid iteration)
• --stale is stateless and works anywhere
• --stale is faster (mtime check vs git diff)

Benefits for Agentic Systems

⚡ Speed: Only affected tests → 5-10x faster iteration
🎯 Precision: Transitive dependency tracking ensures no missed tests
🔄 Stateless: No git required → works in containers, CI, local
📊 Deterministic: Manifest-based → predictable test selection

Implementation

I have a complete, tested implementation ready in #9916:

• ✅ Mutually exclusive with --changed
• ✅ Honors forceRerunTriggers
• ✅ Watch mode compatible
• ✅ Integrates with Vite module graph
• ✅ 6 comprehensive tests, all passing
• ✅ Full documentation
• ✅ Zero breaking changes
• ✅ 20 files changed, +410 lines
• ✅ 7 atomic commits

Reference PR: #9916

Impact

This feature would make Vitest the first major JavaScript testing framework optimized for agentic coding workflows, positioning it at the forefront of the AI-assisted development revolution.

Questions for Maintainers

1. Does this feature align with Vitest's roadmap?
2. Any concerns about the manifest-based approach?
3. Should this be a plugin instead? (I think core is better for consistency)
4. Any naming preferences? (--stale, --affected, --incremental?)

---

Alternatives considered:

• Using --changed: Too git-dependent, not optimized for rapid iteration
• Custom scripts: Every team would reinvent this, better as core feature
• Watch mode only: Doesn't work for agent batch workflows

cc @sheremet-va @antfu

[ihorkatkov]

Needed! Upvote

[AriPerkkio]

3. Tracking: Uses filesystem mtime comparison (fast, no git required)

I think this could also be implemented by having custom CustomVCSProvider. It would be more flexible and would not require adding another option flag:

• Feature Request: Extensible VCS Adapter System for Changed Test Detection #9863