add-endpoint
Skill9 starsChanged 18 days agoApache-2.0View on GitHub
Step-by-step guide for adding new server functionality to ShipIt: HTTP endpoints (service -> route -> client hook -> test), WebSocket messages (type -> handler -> dispatcher -> client), deploy targets, tool activity labels, and the WebSocket vs HTTP decision framework. Load when adding a new API endpoint, WS message type, deploy target, or activity label.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- nanotaboada/python-samples-fastapi-restfultheir own version, first seen Nov 1, 2026
- KevinArce/create-bun-apitheir own version, first seen Oct 25, 2026
- Ssoulisack/claude-skillstheir own version, first seen Oct 15, 2026
- lepresk/groundworktheir own version, first seen Oct 15, 2026
- Azure/azure-sdk-toolstheir own version, first seen Oct 13, 2026
- Azure-Samples/art-voice-agent-acceleratortheir own version, first seen Oct 8, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- nanotaboada/python-samples-fastapi-restful★ 141same name
- Azure/azure-sdk-tools★ 134same name
- atherio-danp/cde-dotnetcc★ 109same name
- Azure-Samples/art-voice-agent-accelerator★ 74same name
- paulieb89/property-shared★ 16same name
- KevinArce/create-bun-api★ 11same name
- aiqadam/qadam-flow★ 5same name
- jpoindexter/theft-kit★ 1same name
- lepresk/groundwork★ 0same name
- Ssoulisack/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- android-buildSkill
- client-architectureSkill
- deployment-architectureSkill
- design-languageSkill
- docs-navigatorSkill
- dogfooding-shipitSkill
- frontend-design:frontend-designSkill
- git-architectureSkill
- prompt-architectureSkill
- server-architectureSkill
- session-containersSkill
- session-lifecycleSkill
- session-processesSkill
- testing-and-qualitySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 2 are distinctive, and 15 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Use WebSocket: only when one of these applies:
- Very specific: line 26
If an operation triggers server-side effects that push WS events (e.g., fork_session triggers a session_list broadcast), that's fine — the …
- Very specific: line 27
If you're unsure, start with HTTP.
- Very specific: line 29
Current WS message types: read the WsClientMessage union in src/server/shared/types/ws-client-messages.ts (~23 client → server at time of …
- Very specific: line 37
Add the service function in the appropriate src/server/orchestrator/services/*.ts file — pure function that accepts explicit parameters …
- Very specific: line 38
Add the Fastify route in the matching src/server/orchestrator/api-routes-*.ts file — call the service function, handle errors, return JSON
- Very specific: line 40
Add integration tests using app.inject() in src/server/orchestrator/integration_tests/
- Very specific: line 44
Add the interface to src/server/shared/types/ws-client-messages.ts (and/or ws-server-messages.ts for server-to-client)
- Very specific: line 45
Add the handler in the appropriate src/server/orchestrator/ws-handlers/*-handlers.ts file
- Very specific: line 46
Add a case to the switch (msg.type) dispatcher in src/server/orchestrator/route-registry.ts
- Very specific: line 47
Add the client-side handler as a file in src/client/hooks/message-handlers/ and register it in that directory's index.ts
- Very specific: line 48
Add integration tests in src/server/orchestrator/integration_tests/
- Very specific: line 51
Use Extract<WsClientMessage, { type: "..." }> to get the narrowed message type — don't import individual message interfaces.
- Very specific: line 55
Import getErrorMessage from ./validation.js for consistent error formatting (within orchestrator).
- Very specific: line 63
Add a typed field on PersistedMessage + column + toRow/fromRow + a database.ts migration.
- Distinctive: line 65
Add a history round-trip test and a no-duplicate-on-replay test.
- Very specific: line 83
Add a case to activityFromTool() in src/client/components/StreamingIndicator.tsx.
“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Adding New Endpoints & Features
When to use WebSocket vs HTTP
ShipIt uses HTTP for most operations and reserves WebSocket for a narrow set of cases. When adding a new feature, use this decision framework:
Use HTTP (default) when:
- The operation is a simple read (GET) or mutation (POST/PATCH/DELETE) with a single request-response cycle
- The client needs the result directly (e.g., to update UI state from the response)
- The operation is stateless — any client tab could make the same request
- Examples: fetching file content, renaming a session, creating a PR, saving settings
Use WebSocket only when one of these applies:
- Streaming output — the server produces incremental data over time (Claude CLI events, deploy progress, terminal output). HTTP would require polling or SSE; WS gives us a natural push channel already connected.
- Per-connection state — the operation modifies state tied to this specific browser tab, not the user globally. Session activation (
activate_session) attaches a runner and file watcher to the connection. Agent selection (set_agent) sets the agent for this tab only. These don't make sense as HTTP because they bind to the socket's lifecycle. - Bidirectional real-time interaction — the client and server exchange messages in rapid succession as part of one logical flow: sending a prompt and receiving streamed tokens, answering permission questions mid-turn, interactive terminal I/O.
- Server-initiated push — the server needs to notify the client without a preceding request: file change events, preview status updates, session status broadcasts, queue notifications.
Gray area — lean HTTP:
- If an operation triggers server-side effects that push WS events (e.g.,
fork_sessiontriggers asession_listbroadcast), that's fine — the trigger is HTTP, the notification is WS. Don't put the trigger on WS just because it has side effects. - If you're unsure, start with HTTP. It's simpler to test (
app.inject()), easier to debug (curl), and doesn't couple the operation to connection lifecycle. You can always add a WS broadcast for notifications on top.
Current WS message types: read the WsClientMessage union in src/server/shared/types/ws-client-messages.ts (~23 client → server at time of writing). Don't trust a copied list — it rots. The dispatch switch that narrows them lives in route-registry.ts, not index.ts.
See docs/001-websocket-protocol/plan.md for the full endpoint and message reference.
Adding an HTTP endpoint (most cases)
Prefer HTTP for new endpoints unless the operation requires per-connection state or real-time streaming (see decision framework above).
- Add the service function in the appropriate
src/server/orchestrator/services/*.tsfile — pure function that accepts explicit parameters (session ID, managers) and returns data or throwsServiceError - Add the Fastify route in the matching
src/server/orchestrator/api-routes-*.tsfile — call the service function, handle errors, return JSON - On the client, call the endpoint via
useApihook (apiGet()/apiPost()/ etc.) fromsrc/client/hooks/useApi.ts - Add integration tests using
app.inject()insrc/server/orchestrator/integration_tests/
Adding a WebSocket message (streaming, per-connection state only)
- Add the interface to
src/server/shared/types/ws-client-messages.ts(and/orws-server-messages.tsfor server-to-client) - Add the handler in the appropriate
src/server/orchestrator/ws-handlers/*-handlers.tsfile - Add a
caseto theswitch (msg.type)dispatcher insrc/server/orchestrator/route-registry.ts - Add the client-side handler as a file in
src/client/hooks/message-handlers/and register it in that directory'sindex.ts - Add integration tests in
src/server/orchestrator/integration_tests/
Key conventions:
- Use
Extract<WsClientMessage, { type: "..." }>to get the narrowed message type — don't import individual message interfaces. - Handler functions are
asynconly if theyawaitsomething; otherwise usevoidreturn. - Read per-connection state via
ctxgetters (ctx.getActiveAppSessionId(), etc.), not closure variables. There are noctx.setXrunner setters — they were deleted for becoming silent no-ops after disconnect. To mutate runner state, resolve a runner viaresolveRunner(ctx)and assign directly (runner.running = false). SeeCLAUDE.md→ WebSocket lifecycle MUST NOT affect server behavior. - Access app-level managers directly from
ctx(ctx.sessionManager,ctx.chatHistoryManager, etc.). There is noctx.deploymentStore—DeploymentStoreno longer exists. - Import
getErrorMessagefrom./validation.jsfor consistent error formatting (within orchestrator).
Server → client messages that render in the chat MUST be persisted
If your new server-to-client message renders inline in the chat transcript (a bubble or a card in MessageList.tsx), emitting it is not enough. runner.emitMessage() is transport only: it broadcasts to viewers and buffers into the per-turn turn-event log (replayed on a WS reconnect), but it does not write to persisted chat history. A session switch and a full page reload rebuild the transcript from ChatHistoryManager (GET /history), so an emit-only card renders live, survives a reconnect, then vanishes on switch/reload. This has bitten us repeatedly (voice notes docs/163, bug-report cards docs/164) — see the "Chat transcript content MUST be persisted, not just emitted" pattern in CLAUDE.md for the full checklist.
For a card that arrives off the agent-event stream (HTTP relay or post-turn WS):
- Emit it with
emitChatCard(chat-card-persistence.ts) — never bareemitMessage— so it's emitted AND recorded in-band (anchored byafterGroupIndex) in one call andbuildTurnMessageslands it at its true transcript position. - Add a typed field on
PersistedMessage+ column +toRow/fromRow+ adatabase.tsmigration; patch lifecycle transitions in place (e.g.updateBugReportCard). - Rehydrate on the client in
loadSessionHistory; make the live append + store upsert idempotent by id so reconnect-buffer and reload-history replays don't double-render or clobber a terminal state. - Add a history round-trip test and a no-duplicate-on-replay test.
Transient signals (spinners, preview_status, queue counts) are correctly emit-only — only persist what belongs in the scrollback.
On step 3's "idempotent by id", if the message is both broadcast live AND rehydrated from history. The live copy appends; the history load replaces the whole transcript. They race on every attach, reload and switch, and whichever lands second decides whether the user sees the message zero times or twice. The two failures look nothing alike, so one is typically still open after you fix the other. Three things make any arrival order converge:
- A real id, not the text. Two "continue" sends are genuinely distinct messages, so a text comparison either collapses them or duplicates them.
- Persist the id on the row, so the rehydrated copy still matches (
messages.client_request_idis the worked example — the sender's per-sendrequestId, echoed back onsystem_user_message). An id that exists only in browser memory is gone the moment history replaces the transcript. - Queue the live message behind
historyLoadedinuseMessageHandler, alongsideagent_event/turn_snapshot/sub_agent_spawn. Otherwise a history response sampled a moment before the row was written wipes what the live message just added.
Guards: useMessageHandler.test.ts covers both hydration orders; multi-tab.test.ts covers the cross-viewer broadcast.
Deploy targets — there is no longer anything to add
ShipIt does not own a deploy pipeline. There is no deploy-targets/ directory, no DeployTarget interface, and no deploymentManager. Deploys are triggered by the hosting platform's own Git integration on push, and ShipIt reads their status from the GitHub Deployments API to render it in the PR lifecycle card. See the deployment-architecture skill.
Adding a new tool activity label
Add a case to activityFromTool() in src/client/components/StreamingIndicator.tsx. The function receives the tool name and its input object, and returns a StreamingActivity with a human-readable label.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

