[Paper] Runnable Directories: The Solution to the Monorepo vs. Multi-repo Debate

Source: arXiv - 2512.03815v1

Overview

The paper introduces Causify Dev, a hybrid code‑base organization model that replaces the classic monorepo vs. multi‑repo tug‑of‑war with a new primitive: the runnable directory. By treating each directory as a self‑contained, independently executable unit, the authors claim you can keep the consistency of a monorepo while enjoying the isolation and modularity of separate repositories—without the usual tooling headaches.

Key Contributions

• Runnable Directory Concept – Defines a directory that bundles source, build scripts, tests, and deployment descriptors into a single, executable unit.
• Thin Unified Environment – A lightweight shared runtime (e.g., a minimal Docker image) that all runnable directories inherit, guaranteeing consistent tool versions across the whole codebase.
• Container‑First CI/CD Workflow – Uses Docker‑based pipelines that automatically spin up isolated environments per runnable directory, simplifying dependency management and parallel execution.
• Hybrid Repository Layout – Demonstrates how a single Git repository can host many runnable directories, preserving monorepo benefits (single source of truth, atomic commits) while avoiding its scalability bottlenecks.
• Empirical Evaluation – Benchmarks on a real‑world microservice suite show up to 40 % faster CI builds and a 30 % reduction in dependency‑related failures compared to a traditional monorepo setup.

Methodology

1. Design of Runnable Directories – The authors built a specification that each directory must contain:
   • causify.yaml (metadata, dependencies, entry point)
   • Dockerfile (or a reference to the shared thin image)
   • Standard sub‑folders (src/, test/, deploy/)
2. Implementation of Causify Dev – A CLI tool parses the metadata, generates per‑directory Docker images, and registers them with a central orchestrator that drives CI pipelines.
3. Experimental Setup – They migrated an existing 12‑service, 250 k LOC monorepo (Java, Node.js, Python) to the runnable‑directory model. CI pipelines were run on GitHub Actions and Jenkins for both the original monorepo and the Causify Dev version.
4. Metrics Collected – Build time, test flakiness, dependency conflict incidents, and developer onboarding time (measured via a short survey).

Results & Findings

The data suggest that isolating each service’s environment eliminates most of the “dependency hell” that plagues large monorepos, while the shared thin image keeps version drift in check. Developers also reported feeling more confident making changes because the unit under test is clearly bounded.

Practical Implications

• Faster CI/CD – Teams can parallelize builds at the directory level without worrying about cross‑contamination, cutting feedback loops.
• Simplified Tooling – No need for complex workspace managers (e.g., Bazel, Lerna) to enforce isolation; Docker does the heavy lifting.
• Easier Scaling – Adding a new microservice is as simple as dropping a new runnable directory into the repo, avoiding the overhead of creating a brand‑new repo and managing access controls.
• Consistent Environments – The thin shared image guarantees that every developer, CI runner, and production deployment uses the exact same base tools (compiler versions, linters, etc.).
• Gradual Migration Path – Existing monorepos can be refactored incrementally: convert one module at a time into a runnable directory, reducing risk.

Limitations & Future Work

• Docker Overhead – While containers provide isolation, the extra layer can increase local dev startup time for very small utilities; the authors suggest lightweight alternatives (e.g., podman or nerdctl) as future optimizations.
• Cross‑Directory Coupling – The model assumes relatively loose coupling; tightly coupled components may still need shared libraries, which re‑introduces some monorepo‑style coordination.
• Tooling Maturity – Causify Dev is a prototype; broader adoption will require richer IDE integrations, better support for non‑Docker runtimes (e.g., Windows native builds), and more extensive documentation.
• Empirical Generalization – The evaluation focuses on a single large codebase; future studies should test the approach across different languages, domains (e.g., data‑science pipelines), and organization sizes.

Bottom line: Runnable directories offer a pragmatic middle ground that lets developers keep a single source of truth while enjoying the safety and speed of isolated builds. If your team is wrestling with monorepo scalability or the administrative overhead of a sprawling multi‑repo landscape, Causify Dev is worth a look.

Authors

• Shayan Ghasemnezhad
• Samarth KaPatel
• Sofia Nikiforova
• Giacinto Paolo Saggese
• Paul Smith
• Heanh Sok

Paper Information

• arXiv ID: 2512.03815v1
• Categories: cs.SE
• Published: December 3, 2025
• PDF: Download PDF