Shed Manages Git for Terminal Agents

shed is Andrew Hannigan’s open-source Go project for managing git repositories and workspaces for terminal coding agents. It deals with a very practical problem: agents need fresh code to read, safe places to write, and a way to avoid trampling on each other when several sessions touch the same repo. Shed is a git repo management system that keeps read-only reference checkouts separate from disposable write workspaces. The useful idea for Cursor, Anysphere’s AI code editor, is simple: make the filesystem boundary obvious before you make the agent more autonomous.

As of September 2026, the repository is small: MIT licensed, mainly Go, and listed with 4 GitHub stars in the source signal. That size is part of the story. This is not a polished platform announcement; it is a sharp little Show HN project aimed at a workflow many agent-heavy developers are already feeling.

Keep the clean copy away from the writing agent

Shed’s main trick is a catalog under ~/.shed/repos. Those repos are read-only at the OS level and kept current before agent work begins. When an agent needs to make changes, Shed gives it a cheap disposable workspace instead of letting it write into the catalog.

That matters because terminal agents are tireless, but not sentimental. If an agent corrupts a checkout, leaves a half-applied patch, switches branches mid-task, or starts from yesterday’s main branch, the next task inherits the mess. Shed tries to make the good path boring: read from a fresh reference copy, write somewhere disposable, push to the real upstream when ready.

The trap is thinking this replaces git discipline. It does not. Shed gives the agent a cleaner room to work in; it does not prove the patch is correct, choose the right branch policy, or decide whether the PR is safe.

A concrete flow looks like this:

shed init
shed workspace new
# agent edits in the new workspace
shed prune

The README describes shed workspace new as local and fast because objects hardlink from a shared per-upstream mirror. The resulting workspace is still an ordinary git repo with origin pointing at the real upstream, so the agent can push like it cloned the repo directly.

Notice what developers cared about

The interesting part of the Hacker News signal was not “yet another git wrapper.” Developers have had git worktree, ghq, shell scripts, and hand-rolled clone directories for years. Shed got attention because terminal agents turn minor repo hygiene problems into recurring operational pain.

A human can remember, “Oh, this checkout is dirty from the billing refactor.” An agent may not. A human can decide not to run two risky edits in the same tree. Agents often get launched in parallel because waiting feels wasteful.

Shed’s opinion is that agents should manage this themselves after one setup step. shed init wires the integration once, then the agent can create and clean up its own workspaces. That is a nice inversion: instead of the human preparing a sandbox for every task, the sandbox becomes part of the agent’s normal working vocabulary.

The fair objection is that this adds another layer around git. If your current workflow is one repo, one agent, one branch, and you rarely run parallel sessions, the layer may not pay for itself. If you routinely ask agents to investigate, patch, and open PRs across the same codebase, the layer starts to look less like ceremony and more like seatbelts.

Map the idea to Cursor workflows

Cursor users do not need to copy Shed’s exact model to learn from it. The bigger lesson is to separate three things that often get blurred together: repository context, write permission, and review responsibility.

Cursor rules can describe the boundary. Cursor subagents and skills can describe the job. The workspace should still decide where writes are allowed.

For example, a Cursor setup might use a small rule that makes the Shed boundary explicit whenever an agent is working in a disposable repo. This is the kind of artifact that belongs near your code, not hidden in someone’s prompt history.

---
description: Keep terminal-agent work isolated when using Shed
globs:
  - "**/*"
alwaysApply: false
---

When a task needs edits, create or use a disposable Shed workspace before changing files.

Treat ~/.shed/repos as read-only reference material. Do not write there.

Before opening a PR, report:
- current branch
- upstream remote
- files changed
- tests or checks run
- any generated files changed by the agent

That rule does not make the agent brilliant. It makes the contract reviewable. If an agent edits inside ~/.shed/repos, the failure is obvious. If it opens a PR without naming the branch, remote, and checks, the handoff is incomplete.

This also fits the broader Cursor subagents and skills pattern: a subagent can own a narrow job, while a rule or repo instruction owns the boundary. If you are building this style of workflow, the related Cursor subagents and skills topic is the better home for durable patterns than a one-off prompt pasted into chat.

There is a similar theme in cloud-agent workflows. Repo provisioning is becoming part of agent design, not a background detail; that is why stories like Cursor Starts Cloud Agents Without Repos are adjacent to Shed even though the implementation surface is different.

Try Shed safely on one repo

The safest way to evaluate Shed is not to move your whole development life into it. Try it on one active repo where parallel agent sessions already annoy you.

Use this checklist as a small experiment:

• Pick a repo with normal git hosting and a test command you trust.
• Install Shed from the project instructions, then run shed init.
• Add or track one repo in Shed, following the README and shed --help output.
• Confirm the catalog lives under ~/.shed/repos and is not where edits happen.
• Start one agent task that only reads the repo and summarizes the current architecture.
• Start a second task that creates a workspace with shed workspace new and makes a tiny change.
• Before pushing, ask the agent for branch, remote, changed files, and checks run.
• Delete old scratch workspaces with shed prune after you have kept or pushed anything useful.

The pass condition is boring: the reference repo stays clean, the writable workspace is ordinary git, and the agent can explain what it changed without you replaying the whole terminal session.

The fail condition is also useful. If the agent cannot reliably tell you where it is working, or if your project tooling assumes one fixed path on disk, Shed will expose that quickly.

Fit and not-fit

This is where Shed’s smallness cuts both ways. A single Go binary with no daemon and no telemetry is easy to reason about. A young open-source project also means you should read the code, test the edge cases you care about, and avoid treating the README as a service-level promise.

Common questions

• Does Shed replace git worktrees?

  No. Shed uses the same broad idea of cheap separate working areas, but it packages a fuller agent-facing workflow around a read-only repo catalog, syncing, disposable workspaces, and pruning. If git worktree already solves your problem cleanly, Shed may be unnecessary.

• Can I use Shed with Cursor?

  Yes, the project README names Cursor CLI as one of the terminal agent environments it is meant to work across. The important caveat is that Cursor’s IDE review still happens on ordinary files and git changes, so you should keep branch, remote, diff, and test output visible.

• Why not let the agent clone the repo every time?

  You can, but repeated cloning is slower and does not solve stale or messy reference copies by itself. Shed’s model keeps an always-current catalog under ~/.shed/repos and creates local workspaces from shared objects, so the agent starts from a cleaner base without re-downloading everything.

• When is Shed overkill?

  Shed is overkill when the cost of another repo-management layer is higher than the collision risk. A solo project with one agent session and a simple branch flow probably does not need it; a repo with parallel agent edits and frequent PR handoffs is a better test case.

• What should a Cursor rule say if I try it?

  The rule should say where the agent may write, where it must not write, and what it must report before review. Keep it short: name ~/.shed/repos as read-only, require disposable workspaces for edits, and require branch, remote, changed files, and checks run before PR work.

Best ways to use this research

• Best for: evaluating whether your terminal-agent workflow needs a repo boundary, not deciding whether every developer should change their local git setup.
• Best first artifact: a small .cursor/rules file that tells agents not to write inside ~/.shed/repos and requires a review handoff before pushing.
• Best comparison angle: compare Shed against vanilla git worktree on freshness, cleanup, parallel sessions, and how much the agent can do without a human preparing the workspace.
• Best limitation to remember: Shed is a young open-source project. Test it on one repo, read the source, and keep normal git review habits intact.

Further reading

• Cursor — Agent
• Cursor — Rules
• shed — source

Try the boundary, not the brand

The practical takeaway is not that every agent needs Shed. It is that write boundaries should be concrete enough for an agent to follow and a human to review.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.