Claude Code: Managing Multi-Repo Workspaces
To solve this, I built a tool called facet. The core idea is to create disposable, terminal-based workspaces similar to VS Code workspaces, but designed specifically for LLM agents.
The Workspace Architecture
A facet workspace is a directory containing checkouts of one or more repositories defined by a manifest. The workflow follows a strict lifecycle:
1. Initialization: You spawn a workspace from a GitHub issue.
2. Context Injection: The tool identifies the required repos, clones them, and writes a CLAUDE.md file based on the issue body. This ensures the agent has immediate context without manual prompting.
3. Tracking: The issue is automatically moved to "In progress" on the project board.
4. Cleanup: Once the PR is merged, the entire workspace is deleted.
Technical Implementation & Lessons
I initially tried to integrate zellij for session management, but it was a disaster. I ended up with nameless Claude sessions and no way to reattach after crashes, resulting in lost work and 1,500 lines of deleted code. I learned that the integration needs to be leaner and more explicit.
One specific challenge was determining which repositories were "in scope" for a given issue. I found that GitHub labels are too ambiguous for this. Instead, facet infers the repo set from form fields and cross-references, but it always presents this guess for manual confirmation. Never trust the AI's inference silently; always require a human check.
The tool is a small Go CLI, and interestingly, much of the hardening was done by Claude Code agents themselves. I fed them the issue backlog, they wrote the fixes, and I merged them. This created a tight feedback loop where the agent helped build the very environment it needed to be productive.
For those looking for a deep dive into the implementation, the source is available here:
https://github.com/RiccardoCereghino/facet