An engineering note from the team building Shepherd. Updated September 8, 2026.

You remember the conversation: an agent was fixing a validation bug. But which checkout was it using? Was that the task still running in the second terminal, or a conversation from yesterday? Which changes should you inspect before continuing?

A transcript can tell you what was said. Returning to a coding task requires more: its project, working location, agent session, and the live environment around it. We built Shepherd’s workspace around keeping those relationships understandable.

A task has several kinds of identity

The same agent can work on different projects. The same repository can have several working copies. A terminal pane can remain open while the conversation inside it changes. A task title is helpful to a person, but it is not enough to establish that two views refer to the same work.

We therefore distinguish the places where work happens from the agent conversations associated with them. A workspace organizes the project. A terminal provides a running environment. A provider session identifies a conversation when that identity is available.

These concepts are related, but they do not have interchangeable lifetimes. Keeping them separate gives the product a way to preserve the useful relationships without pretending that a pane and a conversation are always the same thing.

Put the relationship close to the running work

If the interface alone decides which conversation belongs to a pane, that relationship depends on the interface being present to notice it. Another window, or a later reconnect, may be working from a different picture.

In Shepherd, confirmed associations are maintained by the service that manages the workspace’s state. The interface reads and presents them. That keeps the relationship tied to observed work rather than to whichever window happened to be open when a list was refreshed.

The important design choice is ownership: the component with continuing knowledge of the running environment maintains the association, while the view concentrates on helping you navigate it.

Leave room for an identity that is not known yet

Starting an agent and learning the identity of its conversation do not necessarily happen at the same moment. Reusing a familiar title or selecting the newest-looking history entry can produce a convincing but incorrect match.

We build around confirmed associations and allow the information to be incomplete while the session is becoming identifiable. A temporary absence of evidence should not become a fabricated permanent relationship.

This is a broader principle in workspace design: a product should distinguish what it knows from what it can merely make look plausible. A slightly less complete view is preferable to a resume action that confidently leads to unrelated work.

Scope history to the task you are returning to

A global list of conversations is useful for exploration, but it can be a poor starting point for resuming a particular project. Names repeat, related work spans branches, and unrelated recent activity can crowd out the conversation you wanted.

Shepherd’s history handling accounts for workspace and repository context, including the working copy being used. The scope helps decide which conversations belong in the view before the list is trimmed for display.

Active work also needs different treatment from old history. Keeping a history list manageable should not cause the association for a still-running task to disappear simply because newer entries exist. The workspace needs to remain useful to someone returning to work that began earlier.

Resuming and reconnecting solve different problems

Reconnecting returns you to a live environment that still exists. Resuming a conversation uses the agent provider’s saved context and may involve a different process. Both are useful, and neither should be mistaken for the other.

We keep that distinction in the design of session continuity. A history entry is not proof that its original terminal is alive, and a running terminal is not proof that every conversation it has hosted should share one identity.

That clarity also matters when changing tools. Opening the same project in another workspace does not automatically transfer its running processes or its provider-session associations.

Make the return feel ordinary

The desired experience is modest: see the right task, find its current state, and continue with enough context to make a good decision. Achieving that requires the workspace to remember relationships that a collection of windows can easily lose.

Our work on persistent terminal sessions keeps the running environment available. Our agent monitoring design helps you decide where to look. Context connects those two: it makes the place you return to the place you intended.

Your next workspace

Put it to work.

Try Shepherd on an Apple silicon Mac. The iOS app is currently listed as coming soon.

Get Shepherd for Mac