FluxCapacitor: A Git-Aware Filesystem Timeline for Supervising AI Coding Agents

Hook

When your AI coding agent silently rebases your feature branch while simultaneously reformatting 847 files in a different repository, do you know which change came first? Or why your tests suddenly started failing?

Context

The explosion of autonomous coding agents—Cursor, Aider, Claude Code, GitHub Copilot Workspace—has created an observability gap. These tools edit files, commit changes, and switch branches faster than humans can track, often across multiple repositories simultaneously. Traditional solutions fall short: IDE file watchers only see changes within their own editor, git log shows committed history but misses live modifications, and agent-specific logging requires trusting what the agent reports rather than observing ground truth.

FluxCapacitor takes a different approach: it passively observes filesystem changes at the OS level, reconstructs Git operations by parsing .git directory structures directly, and presents everything in a persistent terminal timeline. Instead of wrapping agent processes or requiring SDK integration, it simply watches what happens on disk—making it work identically whether changes come from Cursor, manual vim edits, or a bash script. For teams experimenting with multi-agent workflows who need to understand what changed, when, and in which repository without modifying their toolchain, this architectural choice trades some precision for universal compatibility.

Technical Insight

FluxCapacitor's architecture centers on three decoupled subsystems connected by async channels: platform-native filesystem notification ingestion, Git operation inference from raw filesystem events, and a Ratatui-based terminal renderer with bounded memory guarantees.

The notification layer wraps FSEvents (macOS), inotify (Linux), and ReadDirectoryChangesW (Windows) behind a unified async interface. When you start monitoring a workspace, FluxCapacitor registers recursive watches and funnels events into per-workspace MPSC channels. Critically, it detects notification queue overflows—a real problem when npm install creates 50,000 files in two seconds—and injects explicit INTEGRITY warnings into the event stream rather than silently dropping data:

// Simplified from the notification handler
match platform_watcher.recv_timeout(Duration::from_millis(100)) {
    Ok(events) => {
        for event in events {
            if event.flag.contains(ITEM_OVERFLOW) {
                tx.send(TimelineEvent::IntegrityGap {
                    workspace: workspace_id.clone(),
                    reason: "Filesystem notification buffer overflow",
                }).ok();
            }
            debouncer.push(event);
        }
    }
    Err(RecvTimeoutError::Disconnected) => break,
}

This design acknowledges that filesystem notifications are best-effort and surfaces observability failures as first-class data in the UI. Users see [INTEGRITY GAP] markers in the timeline and know to manually verify changes rather than trusting an incomplete view.

The Git inference engine is where things get interesting. Instead of shelling out to git status or git log, FluxCapacitor watches for specific paths within .git directories and parses them directly. When .git/refs/heads/main changes, it reads the new commit SHA. When .git/index updates, it diffs the staging area structure. When .git/ORIG_HEAD appears during a rebase, it correlates that with subsequent ref changes to reconstruct the operation:

// Pseudocode showing Git operation detection
if path.ends_with(".git/refs/heads/*") {
    let branch = extract_branch_name(path);
    let new_sha = fs::read_to_string(path)?;
    
    // Check if this is a checkout vs. a commit
    if git_head_matches(new_sha) {
        emit(GitOp::Checkout { branch, sha: new_sha });
    } else {
        emit(GitOp::Commit { branch, sha: new_sha });
    }
} else if path.ends_with(".git/ORIG_HEAD") {
    // ORIG_HEAD appears during rebase/merge operations
    pending_operation = Some(ReflogOperation::Rebase);
} else if path.ends_with(".git/index") {
    let index = parse_git_index(path)?;
    emit(GitOp::Stage { files: index.entries() });
}

This heuristic approach works remarkably well for common operations—commits, checkouts, merges, rebases—but breaks down with exotic workflows. Submodule updates, LFS pointer changes, or custom Git hooks that modify .git structures in unexpected ways can produce incomplete timeline entries. The trade-off is speed and zero dependencies: no git executable required, no subprocess spawning overhead, and consistent behavior across environments where git might be configured differently.

The rendering layer uses Ratatui to build a TUI with workspace multiplexing. Each monitored repository gets a persistent visual lane, and events are color-coded by type: blue for Git operations, yellow for file modifications, red for deletions, and orange for integrity gaps. The ring buffer implementation maintains bounded memory—200,000 path entries and 64MB of file content snapshots by default—evicting old data when limits are hit:

struct TimelineBuffer {
    events: VecDeque<TimelineEvent>,
    snapshots: LruCache<PathBuf, FileSnapshot>,
    max_events: usize,
    max_snapshot_bytes: usize,
}

impl TimelineBuffer {
    fn push_event(&mut self, event: TimelineEvent) {
        if self.events.len() >= self.max_events {
            self.events.pop_front(); // Evict oldest
        }
        self.events.push_back(event);
    }
    
    fn store_snapshot(&mut self, path: PathBuf, content: String) {
        let size = content.len();
        while self.current_snapshot_bytes + size > self.max_snapshot_bytes {
            if let Some((_, evicted)) = self.snapshots.pop_lru() {
                self.current_snapshot_bytes -= evicted.content.len();
            } else {
                break; // Can't evict more, reject snapshot
            }
        }
        self.snapshots.put(path, FileSnapshot { content, timestamp: Instant::now() });
        self.current_snapshot_bytes += size;
    }
}

This memory model prevents runaway growth during large refactors—an agent reformatting an entire codebase won't crash the process—but means historical diffs eventually disappear. For agent supervision workflows where you care about recent activity more than complete history, this trade-off works. For forensic analysis or compliance logging, you'd need a different tool.

The decoupled architecture shines with concurrent multi-agent scenarios. If Cursor is editing frontend code in one repository while Aider refactors backend services in another, FluxCapacitor shows both timelines side-by-side with synchronized timestamps. You can see that the frontend agent added a new API client three seconds before the backend agent renamed the endpoint, revealing causality that neither agent's individual log captures.

Gotcha

Platform notification reliability is the Achilles' heel. FSEvents on macOS coalesces rapid changes, inotify on Linux has per-user watch limits (typically 8,192 directories), and ReadDirectoryChangesW on Windows buffers aggressively. This means high-velocity operations—cargo build with 10,000 intermediate artifacts, npm install creating nested node_modules—frequently trigger integrity gaps. FluxCapacitor reports these gaps honestly, but you still lose observability during the most chaotic moments when you need it most. The documentation acknowledges Linux and Windows support is 'smoke test only,' suggesting macOS is the primary target and cross-platform parity is aspirational.

Git operation inference is inherently heuristic. By parsing .git internals directly, FluxCapacitor gains speed but loses validation. Exotic workflows break the assumptions: submodule updates modify .git/modules in ways the parser doesn't expect, worktree operations create filesystem links that confuse path tracking, and custom merge drivers or clean/smudge filters mean the .git/index doesn't reflect actual working tree state. If your agents use advanced Git features heavily, the timeline will have blind spots. There's no git executable fallback for ambiguous cases—you either get a parsed event or silence, making this tool less suitable for complex monorepos with heavy Git automation.

Verdict

Use FluxCapacitor if you're supervising multiple AI coding agents across different repositories, need Git-aware timelines without modifying agent workflows, or want process-agnostic observability that works identically for Cursor, Aider, and manual edits. It's particularly valuable for teams experimenting with agent-driven development who need to debug cross-repo coordination issues or verify what actually changed when an agent reports success. Skip it if you're working solo in a single repository where IDE file history suffices, your platform has unreliable filesystem notifications (high-churn monorepos on Linux), you need legally-defensible audit logs rather than best-effort timelines, or you depend on exotic Git workflows like submodules and worktrees that break the inference heuristics. The alpha status and cross-platform caveats mean this is an observability experiment, not production infrastructure—but it's the only tool attempting this specific architectural niche of Git-aware, multi-workspace, agent-agnostic filesystem observation.