Architecture of shepherd-agents/shepherd
shepherd-agents/shepherd is 1,841 source files holding 27,182 symbols across 12 modules, written mainly in Python, Shell, Makefile. The largest module is shepherd, with 1,113 files, and 17 files are entry points into the dependency graph.
How shepherd fits together
Work enters through a task, which is a plain Python function whose signature declares per repository whether it has ReadOnly or ReadWrite access to a GitRepo. The shepherd module, the largest module with 1113 files, holds the Python surface, and shepherd/packages/dialect/src/shepherd_dialect/workspace_control/workspace.py is a hotspot file in its workspace control code, where bindings are created and runs are started. The vcs-core module, with 450 files, provides the version control layer, and vcs-core/packages/core/src/vcs_core/_world_storage_manager.py is a hotspot file in it that manages world storage. shepherd/packages/dialect/src/shepherd_dialect/providers.py is another hotspot file in the shepherd module, and the commons-vcs module is a separate package with its own pyproject.toml. On a jailed device, the grants of a run are compiled to its writable roots and enforced at the native syscall jail on macOS Seatbelt, while Linux Landlock enforcement is container-gated. The output of each run is kept per binding and settled once with select, apply, release, or discard.
Largest modules
- shepherd: 1,113 files and 214,281 lines of code
- vcs-core: 450 files and 137,285 lines of code
- docs: 132 files and 5,073 lines of code
- shepherd2: 45 files and 10,444 lines of code
- commons-vcs: 31 files and 3,028 lines of code
- examples: 30 files and 3,816 lines of code
- integration-tests: 12 files and 2,598 lines of code
- root: 8 files and 950 lines of code
Languages
By file count: Python 1,594 files, Shell 11 files, Makefile 10 files, Dockerfile 2 files, JavaScript 2 files, C 1 file.
More on shepherd: summary and FAQ, codebase overview, code health.
Related guide: Best dependency graph tools for monorepos