How the AI Split Works.md

How the AI Split Works.md

AI Split

For larger refactors with lots of file changes, we can use the Auto Split feature which uses AI to group changes into logical commits. "100 file changes → 12 commits" etc. We use mostly recursive algorithms + AI to figure out the best possible split for the changes given.

Because local models like Apple Foundation Models (AFM) are constrained to tiny context windows (~4K tokens), the system is built on a highly parallel, adaptive "Divide and Conquer" pipeline

The Split Algorithm: From Chaos to Clean Commits

This is where the real engineering challenge lives. Currently, Omni uses a fixed batch size of 3 files when autoSplit is enabled:[^2]

const batchSize = autoSplit ? 3 : Math.max(1, selected.length);
const totalCommits = Math.max(1, Math.ceil(selected.length / batchSize));

This works, but it has no semantic understanding of which files belong together logically. The proposed AI-enhanced approach replaces this with a three-phase hybrid architecture:[^2]

Phase 1: Static Analysis (instant, no AI)

Before any model is called, Omni extracts metadata from the full file — not just the diff. This is the key insight: diff tells you what changed; the full file tells you why it matters.[^2]

interface FileDossier {
  path: string;
  diff: string;
  imports: string[];    // What it depends on
  exports: string[];    // What it exposes  
  fileType: 'component' | 'hook' | 'util' | 'test' | 'config' | 'type';
  detectedDomain: string;  // From path: "user", "auth", "checkout"
}

From this, Omni builds a relationship graph deterministically — import chains, test-file pairing (UserService.test.ts → UserService.ts), directory clustering. This handles 80% of grouping decisions with zero AI cost.[^2]

Phase 2: AI Refinement (fast, small prompts)

The LLM only answers questions that require judgment: Is this a feature or a fix? Do these two unrelated-looking files actually belong together? For each candidate cluster: "Should this be 1 or 2 commits?" Cross-cluster: "Do any files belong elsewhere?"[^2]

Phase 3: Message Generation (current approach)

Generate title and body per commit using the enriched context from all six sources.[^2]

Adaptive Model Strategy

The architecture scales up gracefully across model tiers:[^2]

Model Tier	Examples	Context	Strategy
Tiny (4K tokens)	Apple AFM	4K	Many micro-calls, compressed structured prompts
Medium	Ollama (Llama, Mistral)	8–32K	Batched parallel calls
Large	GPT 5.2, Opus 4.5, Gemini 3	128K–1M+	Single-pass — send everything at once

For AFM's tight 4K window, every token counts. Instead of natural language prompts, Omni uses structured formats:[^2]

[src/hooks/useUserData.ts]
+cache.get +cache.set -fetchUser direct
?type ?domain ?sum
→ feat user cache-user-fetch

This lets 3–4 files fit per call. For 47 files, the full pipeline completes in ~7 seconds. For 100 files, ~12 seconds. With GPT 5.2 or Opus 4.5, the same 47 files resolve in a single call in ~3 seconds.[^2]

The design philosophy: build for AFM first, because small models force clean decomposition. Larger models then just collapse multiple passes into one — the micro-pipeline isn't a compromise, it's the foundation.[^2]

AI Rebase: Decluttering the Commit Frenzy

On the flip side of splitting, there's squashing. The AI Rebase feature lets you select a range of messy commits, and Omni's AI groups them into streamlined logical commits — "vibe code generates commit bonanza, Omni declutters the frenzy to a neat stack of commits by removing the commit pollution" (issue #177) .

Phase 1: Static Graph Pre-Clustering (Zero AI Cost)

Before invoking AI, Omni builds a deterministic relationship graph. By locally parsing ASTs and regex import statements (e.g., detecting that UserProfile.tsx imports useUserData.ts), it groups obvious dependencies and automatically pairs test files with their implementations (e.g., grouping UserService.ts with UserService.test.ts). This instantaneous step resolves 80% of file relationships for free.
​

Phase 2: AI Refinement (The Micro-Pipeline)

For ambiguous files, Omni creates a lightweight "File Dossier" (path, diff summary, change type, domain) and feeds it to the LLM. To bypass the 4K token limit of local models, Omni runs an Ultra-Lean Pipeline:
​

Classify: Many parallel micro-calls to classify each file (feature, fix, chore) using heavily structured, non-natural language prompts (e.g., feat user cache-user-fetch).
​

Cluster: Batching 25 tiny summaries per call to let the AI determine which files belong together semantically.
​

Merge: Reconciling groups across batches.
​

Adaptive Scaling for Cloud Models

While built to survive on 4K-token local models, the architecture detects capabilities dynamically. If a user provides an API key for a massive-context model like Gemini 3.1 Pro or GPT-5.2, Omni pivots from the "Micro-Pipeline" strategy to a "Single-Pass" strategy — dumping all 47 file dossiers into a single call for superior, instantaneous relationship mapping.
​