One folder to
rule them all.

Git submodules pin repos to specific commits, create merge conflicts, confuse new team members, and break CI pipelines. Git subtrees are no better — they flatten history and make extraction impossible. Neither was built for a world where one developer touches five repos in a single morning.

Monorepo tools (Nx, Turborepo, Lerna) assume everything lives in one git history with one CI pipeline. But real companies have private client repos, third-party codebases, and varying access levels. Not everything belongs in the same git log.

In the vibe-coding / AI code generation era, agents need context. If your API is in one repo, your frontend in another, and your shared types in a third, every AI tool you use sees a fragment. They can't reason about cross-cutting changes, can't refactor across boundaries, can't run a pipeline that touches multiple systems.

Every directory inside is a standalone git repository with its own remote, branches, CI, and access controls. GUT doesn't merge them, pin them, or flatten them. It just knows they exist and where they live.

The folder structure is a semantic map of your organization — not a package manager's opinion. Web apps, APIs, CLIs, client projects, internal initiatives, infrastructure — each in its own category, each instantly discoverable.

This is the Unix philosophy applied to code organization: simple directories, obvious names, and tools that compose.

In the AI-first era, .md files aren't documentation — they're the instructions that produce your software. A PRD written in markdown becomes epics, stories, and deployed code. An architecture doc becomes the constraints an agent follows. A rule file prevents the same production bug from ever happening again.

Your agent personas, workflow definitions, decision logs, and operational runbooks are all markdown — all living in the same filesystem as the code they govern. Markdown is the source code of your company.

# These .md files aren't docs — they're executable
docs/PRD-new-feature.md        →  AI agent reads it, produces code
docs/architecture/system.md    →  Agent follows constraints
agents/pirlo.md                →  Defines a dev agent's behavior
rules/api-debugging.md         →  Prevents known mistakes
workflows/deploy-pipeline.md   →  Orchestrates multi-agent work
memory/project-context.md      →  Persists knowledge across sessions

The super-repo isn't just code repos. It's the entire operational intelligence of your organization — decisions, patterns, agent workforce, and the code they produce — in one place, versioned by git, searchable by any tool.

When your entire codebase and your entire knowledge base live in one directory, AI agents see everything. They can trace an API change through the backend, into the shared types, and up to the frontend. They can read the PRD that motivated it, the architecture doc that constrained it, and the rule that prevents the mistake you made last time.

This is the real unlock: single brain, single project, single management. The super-repo isn't just a folder — it's the shared context that makes AI-driven development actually work.

Compared to the usual approaches:

# Git submodules — pinned commits, merge conflicts, broken CI
# Git subtrees  — flattened history, no clean extraction
# Monorepo tools — one git log, one CI, access = all-or-nothing
# Polyrepo       — scattered context, no unified view

# GUT super-repo — independent repos, unified workspace, selective access
# Each repo has its own git. GUT coordinates across them.
# Clone what you need, ignore what you don't.
# One folder to rule them all.

Navigate to your workspace root (the directory containing your repos) and run:

gut init

GUT scans packages/, apps/, libs/, services/, and tools/ for directories with .git. Each git repository found is registered as an entity.

gut quick-setup --profile monorepo --clone-missing

Profiles: monorepo, microservices, fullstack, library. The --clone-missing flag fetches repos not yet on disk.

gut entity list -v
# NAME           TYPE       PATH                          REPO
# api            module     packages/serverless/api        git@gitlab.com:.../api.git
# sign           delivery   packages/web-apps/sign         git@gitlab.com:.../sign.git
# api-contracts  module     packages/shared/api-contracts  git@gitlab.com:.../api-contracts.git
# ...

An entity is any git repository GUT knows about. Each has a name, type, path, and optional remote URL. Types include module, delivery, service, client, and more.

gut entity add my-service service     # register manually
gut entity clone my-service              # clone from registered remote
gut entity clone-all --parallel          # clone everything at once

Focus tells GUT which entities to operate on. All batch commands (checkout, commit, push, sync) only affect focused entities. You can focus on one or many.

gut focus api sign api-contracts  # focus on 3 entities
gut focus api --mode delivery      # with work mode context
gut unfocus                             # clear focus
gut back                                # go back to previous focus
gut recent                              # show focus history

Every standard git operation runs across all focused entities. One command, multiple repos.

gut checkout -b feature/new-api   # create branch in all focused
gut status                              # git status across all focused
gut add -A                              # stage all changes
gut commit -m "feat: add endpoint"   # commit in all focused
gut push -u                             # push all focused with upstream
gut sync                                # fetch + pull + push all focused

# Focus on what you're working on today
gut focus api sign --mode delivery

# Sync with remote before starting
gut sync --rebase

# Creates the branch in BOTH api and sign repos
gut checkout -b feature/bulk-send-v2 --from master

# Check what changed across repos
gut status

# Stage and commit
gut add -A
gut commit -m "feat: add bulk send v2 endpoint"

# Push to remote
gut push -u

# Urgent bug in a different repo? Switch focus.
gut focus notifications
gut checkout -b fix/slack-token

# Fix it, commit, push...

# Go back to what you were doing
gut back
# Focus restored to: api, sign (feature/bulk-send-v2)

# Focus on the repos the pipeline will touch
gut focus api sign api-contracts

# Create worktrees for all focused entities
gut worktree create workflow/deploy-batch --install
# Worktree ready:
#   Path:   /tmp/gut-worktrees/workflow-deploy-batch
#   Branch: workflow/deploy-batch
#   Entities: api, sign, api-contracts

The --install flag runs pnpm install in the worktree so dependencies are ready.

The worktree mirrors your workspace structure. Tools that reference packages/serverless/api/ work without changes.

# Use --cwd to point any tool at the worktree
bmad-workflow workflow docs/PRD-example.md \
  --cwd /tmp/gut-worktrees/workflow-deploy-batch

# Check worktree status across entities
gut worktree status workflow/deploy-batch
# Entity        Branch                  Status   Changes
# api           workflow/deploy-batch   dirty    3 changes
# sign          workflow/deploy-batch   clean    clean
# api-contracts workflow/deploy-batch   dirty    1 changes

# List all active worktrees
gut worktree list

# Remove when done
gut worktree remove workflow/deploy-batch

Write a PRD in markdown. An AI agent reads it, generates epics and stories, implements the code, deploys, and runs tests — all inside an isolated worktree. Your main checkout stays untouched.

# Write the PRD
docs/PRD-new-billing-api.md

# Focus on the repos the agent will touch
gut focus api shared-types dashboard

# Create an isolated workspace
gut worktree create workflow/billing-api --install

# Launch the agent pipeline in the worktree
claude -p --cwd /tmp/gut-worktrees/workflow-billing-api \
  "Implement the PRD at docs/PRD-new-billing-api.md"

Need two features built simultaneously? Create two worktrees. Each agent works in its own sandbox — even if they touch the same repos.

# Agent 1: billing feature → api + dashboard
gut focus api dashboard
gut worktree create workflow/billing

# Agent 2: notifications feature → api + mobile-app
gut focus api mobile-app
gut worktree create workflow/notifications

# Both share the api repo — but on different branches
gut worktree list
# workflow/billing        → api (workflow/billing), dashboard (workflow/billing)
# workflow/notifications  → api (workflow/notifications), mobile-app (workflow/notifications)

# Launch both agents simultaneously
pipeline-tool run docs/PRD-billing.md --cwd /tmp/gut-worktrees/workflow-billing &
pipeline-tool run docs/PRD-notifications.md --cwd /tmp/gut-worktrees/workflow-notifications &

When agents finish, inspect what they built, merge the branches, and clean up the worktrees.

# See what each agent produced
gut worktree status workflow/billing
gut worktree status workflow/notifications

# Review the changes in each entity
cd /tmp/gut-worktrees/workflow-billing/packages/api
git log --oneline master..workflow/billing

# Merge when satisfied
git checkout master
git merge workflow/billing

# Clean up
gut worktree remove workflow/billing
gut worktree remove workflow/notifications

A worktree is just a regular directory. Open it in your editor, use the terminal, run git — everything works like a normal checkout.

# Open the worktree in Cursor / VS Code
cursor /tmp/gut-worktrees/workflow-billing
code /tmp/gut-worktrees/workflow-billing

# Or cd into it from the terminal
cd /tmp/gut-worktrees/workflow-billing

# Browse what the agent changed in each entity
cd packages/serverless/api
git diff                                # see all changes
git log --oneline master..HEAD        # see agent's commits

cd ../../web-apps/dashboard
git diff                                # changes in another entity

To commit and push the agent's work across all entities:

# Option A: one entity at a time (full control)
cd /tmp/gut-worktrees/workflow-billing/packages/serverless/api
git add -A
git commit -m "feat: billing API endpoints"
git push -u origin workflow/billing

cd ../../web-apps/dashboard
git add -A
git commit -m "feat: billing dashboard UI"
git push -u origin workflow/billing

# Option B: quick loop over all dirty entities
for dir in packages/serverless/api packages/web-apps/dashboard packages/shared/types; do
  cd /tmp/gut-worktrees/workflow-billing/$dir
  git add -A && git commit -m "feat: billing changes" && git push -u origin workflow/billing
done

Without the super-repo, an AI agent sees one repo at a time. It can't trace an API change into the frontend, can't update shared types, can't run cross-repo tests. It works in a silo.

With GUT:

# The agent sees everything it needs
/tmp/gut-worktrees/workflow-billing/
  packages/serverless/api/        ← backend changes here
  packages/shared/types/          ← update types here
  packages/web-apps/dashboard/    ← frontend changes here
  docs/PRD-billing.md             ← the instructions
  docs/architecture/billing.md    ← the constraints
  rules/api-patterns.md           ← the guardrails

# One workspace. Full context. Complete autonomy.
# And your main checkout? Untouched.

gut deps sign           # what does sign depend on?
gut used-by api         # what depends on api?
gut affected core       # what breaks if core changes?
gut related sign        # entities related to sign
gut graph               # visual relationship graph

gut insights           # workspace-wide analytics
gut patterns           # learned development patterns
gut audit              # access and change audit