Skip to article
Public docs

Shiplet documentation

Share what your agents made, and how they made it: artifacts and agent sessions, with exactly the access you choose.

Browse documentation
Start

Why Shiplet

Why the session behind agent work should be as shareable as the work, with access you choose.

Say it's Thursday afternoon and a PM is clicking through a build that fixes invite recovery. The expired-link screen still says “Something went wrong,” so she leaves a comment on it: “Still broken, or am I looking at an old version?” Nobody on the thread can tell her. The engineer's agent has reworked that flow four times since Monday, and the session behind those changes closed with a terminal window on Tuesday, along with the test run that failed before the last fix.

In Shiplet the build has one review link that stays the same while the work underneath changes, and her comment keeps the revision it was left on, so the engineer can see which version she was looking at. The Tuesday session is there too, as a trace beside the build. The engineer chooses who reads it and at what level, which here means a summary for the PM and the whole session for whoever picks up the ticket next. Claude Code and Codex can share a session without leaving the conversation, and any other agent can write the open format, so a team that uses both, or adds a new agent next year, keeps every session in one place.

What the session knows

Open that trace and Tuesday is all there, from the engineer's first prompt to the screenshot the agent took of the expired-link screen, with every tool call and its result in between. The failed test run sits a few steps above the edit that fixed it, so when the PM asks in the thread whether anyone ran the tests after the copy change, the engineer answers from the trace.

On Friday a teammate takes the ticket. They paste the viewer's Copy prompt for your agent into their own agent, which loads the trace over MCP, or they run shiplet trace pull --as context in a terminal. Their agent starts a fresh session with a briefing at the teammate's level: what was asked, what changed, which checks passed or failed, and how Tuesday ended. Any agent that speaks MCP or can run the CLI can load a trace this way, so a session recorded in Codex can brief Claude Code, and the other way round.

Who reads what

Before closing that terminal on Tuesday, the engineer typed “Share this session to Shiplet.” Claude Code and Codex both know which session they are in, so the agent ran the CLI itself. Secrets are masked on the engineer's computer before anything leaves it, which turns a GitHub token in a tool result into [secret:github-token], and Shiplet scans again when the trace arrives. Until the engineer shares it, the new trace is private to the engineer and the Shiplet's owner.

Every audience gets one of three levels:

  • Full: everything except secrets, for the person who will pick the work up.
  • Conversation: the messages and tool steps, without tool output or reasoning.
  • Summary: what was done, which files were touched, which checks ran, and how it ended, with no text from the session.

An audience can be a person, an email address, a team, the organization, anyone with the link, or an API key. When someone falls into more than one, the most specific one wins, so if the organization gets Conversation and Dana gets Full, Dana sees everything. A custom rule narrows one audience further. The contractors team can get Conversation with the client's name masked and the reasoning hidden, and Preview as this audience shows exactly what they will see before you share. Organization administrators can read every shared trace in full, and a private trace stays private from them too.

The build has its own access, set apart from the trace. It can be private, visible to the organization, unlisted, or public, and you can grant it to a team or to one person by exact email address. Invite links bring people into the organization or one of its teams. Viewing and editing are granted separately, so the PM can review the build without being able to change it.

The open format

Claude Code and Codex each keep sessions in a format and folder of their own, and by next year there will be a third. Shiplet reads the first two directly, subagents included, and turns each session into one open format, shiplet.trace/v1, on your computer, so the raw logs stay there. The harness names claude-code and codex are reserved for those importers, which means a trace labeled Claude Code came from Claude Code's own log. Any agent that writes the format can share its sessions the same way.

A trace file is JSON Lines, with a header and then one event per line in the order the session happened. Every event carries a seq number, and a gap is an error, so a lost line never goes quiet. When an agent leaves something out on purpose, it writes an omitted event with a reason, and the reader sees that something was there.

Where the comment was left

The PM's comment from Thursday knows where she was when she left it: the expired-link screen, the element she clicked, her viewport, and the revision the link was showing at that moment. A trace can be pinned to the revision it produced as well, which puts the Tuesday session next to the version it made.

The default Shiplet review flow on a static artifact, with the compact Annotate control and one contextual comment pin
The default review surface stays out of the way until somebody adds an annotation or opens a thread.

On Friday the teammate's agent reads her ticket over MCP along with the Tuesday briefing and fixes the screen. It attaches its own session to the revision it made, and when the PM opens that revision, the story of the fix is beside it.

When I say you'll never lose an agent session or your review context, I mean for as long as you keep the Shiplet. A trace you delete is gone, and archiving a Shiplet deletes its traces after 7 days and the Shiplet itself after 30.

A review layer shaped like the ticket

The toolbar around the build is a widget, and the engineer can swap it for one made for this job. A widget can turn the acceptance criteria on a ticket into the controls that prove them. On the invite recovery build, each criterion opens the exact state it names. The PM opens the expired-link state or replays an invitation that was already used, then passes or blocks that criterion and attaches evidence to it, without rebuilding the ticket from memory.

An engineer-authored invite recovery build wrapped in a custom release-proof widget that turns acceptance criteria into test controls
An engineer-authored build carries its own release proof. Reviewers can open the expired-link state and replay a consumed invitation. The mobile criterion opens the flow at 390 pixels before a reviewer attaches evidence.

Every Shiplet gets a root

Say the engineer asked an agent to build that widget. The agent reaches Shiplet through its MCP, which has two tools, search and execute. It finds the review-layer operations with search without loading the whole platform into context, and execute runs its program in a disposable Dynamic Worker. That Worker has no direct D1, R2, or Durable Object bindings and can call only what the trusted host exposes, with the engineer's own access. Publishing, reading feedback, sharing a trace, and loading one with getTraceContext all go through that same narrow door.

The program produces a preview that a person with edit access tries against the build and approves, and that approval goes to the Shiplet's root. Each Shiplet gets one ShipletRoot, built on Cloudflare Durable Objects. The Platform Worker resolves it with getByName(shiplet.id), so every request for that Shiplet reaches the same object, with storage of its own. In its own SQLite the root keeps the state that has to agree inside one Shiplet: the active review layer, previews waiting for approval, where the layer came from, and its audit events.

An illustrated ShipletRoot station giving one Shiplet its own review interface
One ShipletRoot per Shiplet, reached by name, with its own SQLite.

Applying the approved widget is a guarded update inside the root. If another change to the review layer landed between the preview and the approval, the update fails closed, and a stale agent turn can't overwrite it. Traffic for one review stays with its root, so one unusually busy Shiplet has the ceiling of one root, a limit I accept for the product we have.

The rest of the stack is boring on purpose. The Platform Worker checks identity and access before it routes a request. R2 keeps artifact bytes and trace segments, and D1 keeps the directory of Shiplets and their feedback. D1 also records who can read which trace, and each audience's version of a trace is rendered once, when its sharing changes, then stored.

Shiplet architecture showing the trusted browser host and Platform Worker reaching one ShipletRoot, plus Code Mode running in a disposable Dynamic Worker
Reviewers and Code Mode programs reach the same ShipletRoot. Code Mode runs in the Dynamic Worker, and the approved widget runs in the browser sandbox.

An evidence board for a study

Say a researcher shares a study of the same invite flow, with the prototype and the findings in one Shiplet. Pass and block buttons would be the wrong controls for that work, so the researcher's widget is an evidence board that keeps each product claim beside the observations behind it, contradictions included. Product and design reviewers mark whether an observation supports or contradicts a claim, and when a claim rests on an assumption nobody has tested, they flag it.

A researcher-authored invite recovery study wrapped in an evidence board that connects product claims to observations and open questions
The researcher-authored evidence board keeps each claim attached to the observations that shaped it. Reviewers can challenge the synthesis and attach another observation inside the same Shiplet.

Both widgets are browser code, each in its own sandboxed frame. A widget never receives the reviewer's session or direct access to storage. To create feedback, it asks the trusted host through a small, typed operation, and the artifact underneath stays as it was.

Software should be allowed to wander

I think of Shiplet as the workspace a team shares with its agents, and I keep coming back to the idea that a workspace should belong to the people using it. The open trace format comes from that instinct, and it applies to Shiplet itself. An organization should be able to choose where Shiplet lives, on Shiplet Cloud or in its own Cloudflare account, and moving between those homes should feel ordinary.

Once it is there, local coding agents should be able to reshape it until it fits the organization, and the path back to upstream improvements should stay open while they do. I care about that shape before I care about the neat open-source category for it.

Software that carries live state and its own local changes has a kind of history that Git, built to move source between developers, leaves out. Something is hiding in that gap, and I don't have a name for it yet.

Try it

Publish your first artifact and leave a comment on the work itself. Then ask your agent to share the session that made it, and read how traces work to choose who sees what.