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.
The rule that stitch init writes is a
few hundred tokens the agent reads once, at the start of a session. It earns its
place by being the cheapest way to answer a question the agent would otherwise
pay for every time it touches an endpoint: how does this project call an
external API?
The always-on cost is tiny
Measured against the site's own machine-readable docs, the rule weighs almost nothing:
| What the agent could load | Size | ~Tokens |
|---|---|---|
The stitch init rule (AGENTS.md) | 1.2 KB | ~300 |
…with the --project inventory (2 stitches) | 1.5 KB | ~390 |
/llms.txt — the curated docs index | 21 KB | ~5,500 |
/llms-full.txt — the entire docs corpus | 451 KB | ~115,000 |
Token figures are the byte count over four — a rough English/code estimate, not a tokenizer run. The ratios are what matter: the rule is under 0.3% of the full corpus.
The cost model matches each ecosystem. The AGENTS.md and CLAUDE.md rules are
always-on but small; the Cursor (.cursor/rules/stitchapi.mdc) and Windsurf
rules are glob-scoped to stitches.ts, so the model only spends the tokens
when it is already working near your API layer.
What it replaces
The rule is cheap in absolute terms, but the saving is what it lets the agent not do:
- Load the manual.
llms-full.txtis the docs' own "simplest correct default" — the whole corpus (~115k tokens) fits in a modern context window. The rule front-loads the ~300 tokens that resolve the common case (declare a stitch, reuse these) and defers the rest to an on-demandsearch_docslookup the agent makes only when it hits an edge. - Explore the repo. Without
--project, an agent that wants to reusegetUserhas to find it first — openstitches.ts, skim the exports, match one to the endpoint.--projectappends that inventory to the rule for one line per endpoint, so the list is already in context. - Hand-roll, then fix. A raw
fetchwith no validation and an inline token is the path the model takes by default. The round-trip of writing it, having it reviewed or failing at runtime, and rewriting it as a stitch costs more than the rule that prevented it.
It is a fixed cost, too. The rule is read once per session and amortises across every call the agent makes after it; rediscovery is paid again every session the rule is absent.
Layer it: rule plus retrieval
The rule is the always-on layer, not the only one. Pair it with the docs MCP and
you get a two-tier budget: the small rule resolves the frequent decisions for
free, and search_docs pulls exactly the page
the agent needs for the rare ones — never the whole corpus, never stale training
data.
# always-on: the habit, in every agent's rules file
npx stitch init --project
# on-demand: the long tail, one page at a time
# → connect the docs MCP at https://stitchapi.dev/api/mcpThat frugality is the whole point: adding APIs never floods the model's context window, because the rule stays small and the retrieval stays scoped.