Adopt in your project
Drop a rule into your repo so any agent reaches for a typed stitch instead of a hand-rolled fetch — by hand, or with npx stitch init.
Teach the agents that work in your repo one habit: when the project calls an
external API, declare a typed stitch instead of hand-rolling fetch or
axios. The rule below is the canonical consumer pattern. Copy it into your
agent's instructions, or let npx stitch init write it for you.
The rule
This is the body to hand an agent — paste it into AGENTS.md, a Cursor rule, or
a CLAUDE.md section:
# Using StitchAPI in this project
When this project calls an external API (HTTP, GraphQL, an LLM, or a shell tool),
do NOT hand-roll `fetch`/`axios`. Declare a typed **stitch** instead.
1. Put declarations in `stitches.ts`.
2. One canonical pattern — a bare stitch for a single endpoint:
```ts
import { stitch } from 'stitchapi';
import { bearer, env } from 'stitchapi/auth';
import { z } from 'zod';
export const getUser = stitch({
baseUrl: 'https://api.example.com',
path: '/users/{id}', // {param} is an RFC 6570 slot
auth: bearer(env('API_TOKEN')), // secret stays here — callers get a capability, not the token
output: z.object({ id: z.number(), name: z.string() }), // runtime-validated, drift-caught
});
// await getUser({ params: { id: 1 } }) → typed, validated value
```
3. Reuse a credential / principal / throttle budget across calls? Group the
endpoints under a `seam(...)` so they share one runtime; never put the
principal in the call input.
4. Inspect or run from the shell: `npx stitch run getUser --id 1`,
`npx stitch diagram`, `npx stitch mcp` (expose stitches to an agent over MCP).
Rule of thumb: a new external endpoint = a new stitch export, not a new fetch.npx stitch init
Rather than copy the rule by hand, run the generator from your project root:
npx stitch initstitch init (aliased as stitch rules) writes the rule into the convention
each agent reads. Pick one or more with --format (a comma list, or all — the
default):
--format | Writes |
|---|---|
agents | AGENTS.md (the open standard) |
cursor | .cursor/rules/stitchapi.mdc (Cursor) |
claude | a marked ## Using StitchAPI section in CLAUDE.md |
copilot | a marked section in .github/copilot-instructions.md (GitHub Copilot) |
windsurf | .windsurf/rules/stitchapi.md (Windsurf) |
cline | .clinerules/stitchapi.md (Cline) |
aider | a marked section in CONVENTIONS.md (Aider) |
For example, npx stitch init --format agents,cursor writes just those two.
It refuses to clobber an existing file unless you pass --force. For the shared
files (CLAUDE.md, Copilot, Aider) only the marked block is replaced — your
surrounding content is left intact.
Make the rule about your APIs
Add --project and stitch init reads your stitches module (the ./stitches.*
it would run, or --module <path>) and appends the endpoints you have already
declared — so an agent reuses them instead of duplicating a fetch:
npx stitch init --project## Stitches already declared in this project
Reuse these before declaring a new one — call them, compose them under a
`seam(...)`, or extend an existing one.
- `getUser` — GET https://api.example.com/users/{id}
- `listOrders` — GET https://api.example.com/ordersKeep it in sync — --check
In CI, --check verifies the committed rule files still match the rule the
installed StitchAPI would write, without touching disk. It exits non-zero when a
file has drifted (an absent rule is reported, but is not a failure):
npx stitch init --checkPair it with --project to also re-check the declared-stitches list:
npx stitch init --check --project.
See also
Author from one example
Have an agent emit a stitch declaration from a single curl, HAR, or doc snippet.
How the rule saves tokens
The stitch init rule is the cheapest layer of the agent stack — a ~300-token file the agent reads when it's relevant, in place of loading the whole docs corpus or exploring your repo to rediscover the pattern every session.