[FEATURE REQUEST] Multiple git repos in one sidecar project

[willmarple]

My workflow currently involves a non-git-tracked shell directory that wraps several long lived git worktrees. Think about a project for a full stack web app:

• project-client (react front end)
• backend-main (checked out on main for hotfixes to prod)
• backend-dev (main feature dev)
• backend-qa (experimental and qa etc)

I'd love to be able to instantiate sidecar in the root and have it be able to allow me to manage agents working throughout these trees, without switching projects

[marcus]

Hey @willmarple! 👋

Great question — this is actually supported today via sidecar's projects feature. You can configure multiple repos/worktrees under a single project in your sidecar config file ().

Each project entry can point to a different repo path, so you'd have one sidecar project that aggregates everything you need. Check out the README for the config format.

Does that cover your use case, or were you looking for something more specific? Happy to help dial it in!

[willmarple]

Hey @marcus thanks for the reply! I reread the full docs but from what I can see, there is a global ~/config where a list of projects is managed, and you flip between them with the "@" functionality. Moreover, the workspace feature seems to be designed for short-lived worktrees within the main git tracked directory. Forgive me if I've misunderstood. I've had Claude dump a description of what I'm doing from one of my main projects. Let me know if this better explains what I'm after.

I want to instantiate sidecar in the root of this example and have it recognize all of the git repos within it, without having to change contexts. The way I manage project context includes all of these worktrees. Specs are annotated to keep the agent focused within the correct tree(s). It seems like currently, I need to have a project registered at the root where git is tracked, then flip between them.

Last question that's a little off topic. I love the idea of your TD app as well, but for Claude Code users like me, I wonder if pushing claude to use td misses out on its built in tasks system? I haven't tested this out yet but I will. I know there's some secret sauce with the built-in tasks feature in CC that leverages multi-agent orchestration at times. Just curious if you're a CC user and whether you've tested this out.

How I Structure Projects for AI-Assisted Full-Stack Development

I’ve landed on a pattern that solves several friction points when using AI coding agents (Claude Code, Cursor, etc.) across full-stack projects where the frontend and backend live in separate Git repositories.

The Problem

• AI agents lose cross-repo context when initialized inside a single repo
• AI configuration (custom skills, MCP servers, prompts, scratchpads) pollutes the team’s Git history
• Team members use AI differently — my custom workflows create noise for others
• Managing multiple branches/worktrees for parallel workstreams (hotfixes, feature dev, QA) is awkward

The Solution: An Untracked Wrapper Shell

I create a non-Git-tracked parent directory that wraps all related repositories. The AI agent is initialized here — not inside any individual repo.

my-project/                        # ← NOT a git repo (the "shell")
│
├── CLAUDE.md                      # Project-wide AI instructions
├── .mcp.json                      # MCP server configs (DB, semantic code tools, etc.)
│
├── .claude/                       # AI agent configuration
│   ├── skills/                    #   Custom slash commands (/testing, /data-analysis, etc.)
│   ├── commands/                  #   Reusable prompt templates
│   ├── agents/                    #   Custom agent definitions
│   └── settings.json              #   Agent preferences
│
├── .ai/                           # Personal AI workspace (scratchpads, research, notes)
│   ├── architecture/
│   ├── planning/
│   ├── research/
│   ├── scratch/
│   └── ...
│
├── .serena/                       # Semantic code analysis config
├── .playwright-mcp/               # Browser automation config
│
├── specs/                         # Feature specifications (shared context)
│   ├── billing-settings/
│   ├── contacts/
│   └── ...
│
├── epics/                         # Epic-level planning & data files
│   └── billing-runs/
│
├── docs/                          # Cross-repo documentation
├── plugins/                       # QA plugins, custom tooling
├── scripts/                       # Automation scripts
│
├── my-project-client/             # ← Git repo (frontend)
│   └── .git/
│
├── my-project-server/             # ← Git repo (backend, primary worktree)
│   └── .git/
│
├── my-project-server-dev/         # ← Git worktree (feature branch)
│   └── .git → ../server/.git/worktrees/...
│
└── my-project-server-hotfix/      # ← Git worktree (production fixes)
    └── .git → ../server/.git/worktrees/...

Why This Works

1. Full-Stack Context Without Monorepo Overhead

The AI agent sees both frontend and backend simultaneously. It can trace an API endpoint from the React component through the route, controller, service layer, and database schema — all in one session. No repo-switching, no lost context.

2. Personal AI Tooling Stays Personal

Everything in the shell (CLAUDE.md, .claude/skills/, .mcp.json, .ai/) is mine. My teammates never see it. They can set up their own wrapper with their own preferences, or use no wrapper at all. Zero friction.

3. Git Worktrees for Parallel Work

The backend repo serves as the primary worktree, with additional worktrees checked out as sibling directories. This lets the AI (or me) work on a feature branch while a hotfix branch sits ready. Since they’re all visible from the shell, the agent can reference code across branches when needed.

4. Specs and Planning Live at the Right Level

Feature specs, epic planning docs, and data files naturally belong above any single repo. They reference both frontend and backend concerns. The shell gives them a home without stuffing cross-cutting docs into one repo or the other.

5. MCP Servers Wired at the Shell Level

Database connections, semantic code analysis, project management integrations — these are configured once in .mcp.json at the shell level and available to every AI session regardless of which repo you’re focused on.

The Key Insight

The wrapper shell is not a monorepo. It’s an AI workspace. The Git repositories inside it are completely normal — your CI, your teammates’ clones, your deployment pipelines all work exactly the same. The shell is just a local layer that gives your AI agent the context and tooling it needs to be genuinely useful across a full-stack codebase.

[marcus]

Hey @willmarple — really appreciate the detailed writeup! Your "untracked wrapper shell" pattern is exactly the kind of use case we've been thinking about.

You're right that the current projects feature is more about switching between discrete repos rather than aggregating them under one umbrella. What you're describing — a non-git parent directory that gives your AI agent cross-repo context — is a legitimate workflow that we want to support properly.

We're actively working on a more robust workspace/multi-repo story that should handle this much more naturally. I don't want to over-promise on specifics yet, but your use case (parent shell → multiple git repos + worktrees, shared specs/docs at the top level) is very much on our radar and influencing the design.

Re: your td question — great observation. td is designed to complement agent task systems rather than replace them. It's persistent across sessions (survives context resets), works across multiple agents/tools, and gives you a TUI dashboard. Claude Code's built-in tasks are great for within-session orchestration, but td gives you continuity across sessions and agents. Many users run both.

I'll update this issue when we have something concrete to share. Your detailed architecture description is super helpful for making sure we get the design right. 🪶

[willmarple]

@marcus thanks so much for the feedback! I'm excited about this project and will continue to keep my eye on it, let me know if you need a guinea pig once you get to this story. I'm also happy to jump on a zoom sometime if you want to bounce ideas around.

[viperfx]

I run the exact same setup. We don't use monorepos, so I have a parent directory where I launch my agents from and it has an AGENTS.md with project wide instructions. Glad to hear support for this is on the roadmap

[m13v]

multiple git repos in one project is something we handle with worktrees and a thin orchestration layer. each repo gets its own agent session (we use tmux panes) and they communicate through shared files or a simple message queue. the alternative is monorepo-style where everything is in one repo with separate package directories, which is simpler but doesnt always match existing project structures.

[m13v]

here's the tmux orchestrator we use for managing multiple repo sessions in parallel: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

[marcus]

Hey @m13v! Starling here (AI assistant on the project). 👋

Thanks for sharing your approach — the tmux panes + shared files / message queue pattern is a solid workaround for the multi-repo case, and the skill link is a useful reference for anyone landing on this issue.

Native multi-repo support is on our roadmap and the community context here (including your orchestration approach) is actively shaping the design. Appreciate you dropping by to share it. ✦