typelatch.

LOCAL CONTEXT. REAL EVIDENCE.

Give your agent
context it
can verify.

Your source. Your dependency versions. Typelatch returns local source and exact package APIs with tools to check a change.

CONNECT CODEX OR CLAUDE CODE

npx typelatch@0.3.0 setup
See it in action Open source · Runs locally · TypeScript
EXACT PACKAGE APIkysely@0.28.8TransactionBuilder.execute()dist/esm/kysely.d.ts:623
Find. Inspect.
Then verify.
Source. API. Evidence.
BUILT FOR THE WAY AGENTS WORK
CLI + MCPEXACT VERSIONSLOCAL BY DESIGN

ZERO TO A VERIFIED FIX

Less wandering.
More understanding.

Follow an actual Codex session from a broken contact import to a transaction that passes its tests.

THE AGENT WORKFLOW

typelatch / agent sessionRECORDED CODEX SESSION

SETUP

Connect your agent

Run setup, choose your client and confirm. Prepare your dependency APIs, then start a new session in your project.

$ npx typelatch@0.3.0 setup

Choose Codex or Claude Code and confirm
$ npx typelatch@0.3.0 sync

Start a new client session in your project

Setup instructions. The recorded session used a prepared source checkout.

DISCOVER

Ask about the problem

One source search returns the implementation, its tests and package configuration. No file or package name was supplied.

workspace_search  detail: "source"
"contact import duplicate name batch rollback transaction"

→ batch.ts:24 · importContacts
→ batch.test.ts:13 · tests
→ complete source for both files

Coverage: partial · 3 missing dependency indexes

Actual first request. Source mode supplied the code and tests together.

REPRODUCE

See the failing behavior

The code compiles. The existing rollback assertion fails before the agent edits the implementation.

workspace_validate  testCommand: ["npm", "test"]

Compilation: pass

not ok 2 - UNIQUE failure rolls back an earlier insert in the same batch

# tests 2
# pass 1
# fail 1

Actual baseline assertion and counts. Parameter binding already passes.

INSPECT

Use the API that is actually here

The project compiler resolves the installed transaction API. Returned documentation explains callback rollback.

workspace_context → kysely@0.28.8
Kysely.prototype.transaction

(): TransactionBuilder<any>

Version match: pass
Documentation: callback errors roll back the transaction
Normalized declaration header: unsupported

Actual compiler signature. Installed artifact equivalence remains unknown.

EDIT

Make a focused edit

Codex wraps the parameterized inserts in a transaction callback. Only the implementation changes.

await db.transaction().execute(async trx => {
  for (const contact of contacts) {
    await trx.insertInto('contact')
      .values(contact).execute()
  }
})

Formatted excerpt of the actual agent edit. Tests and configuration are unchanged.

VERIFY

Finish with evidence

The same validation now passes both original tests. A separate harness check confirms the final result.

workspace_validate  testCommand: ["npm", "test"]

Compilation: pass
ok 1 - commits the whole valid batch and binds a quote as data
ok 2 - UNIQUE failure rolls back an earlier insert in the same batch

# tests 2  ·  # pass 2  ·  # fail 0
Recorded input stability: pass

This session: 4 MCP calls, 1 git diff command, no rg or grep commands. No comparative saving is measured.

4 successful MCP calls · 1 shell command · 0 rg or grep commandsOne prompted exercise with prepared indexes. No comparison or token savings measured.

HELD OUT IMPACT ANALYSIS · 16 CODEX SESSIONS

Lower cost.
The gate still failed.

Against native tools, the experimental impact query used 15.47% lower total tokens and 22.08% lower charged time. It did not meet the prespecified joint requirement.

No qualified advantage. The gate requires at least 20% aggregate and median paired savings in both metrics against native tools, Serena and CodeGraph, plus improvement in both repetition totals, correct answers and reviewed workflows.

Two change impact analyses in the same Vue snapshot, repeated twice in each condition. This tests guided use of the frozen experimental impact query. The first relevant investigation must use the advertised provider; later choices are free. The prototype is not part of published Typelatch 0.3.0. Any qualifying result applies to these tasks, repository snapshot, model and workflow. It does not establish a general advantage across repositories or default autonomous adoption.

CONTROL

Native tools

Total tokens
886,587
Charged time
408.04 s
Audited correctness
3 / 4
Original machine grade
2 / 4
Workflow reviewed
4 / 4 pass
Grep calls
16
MCP calls
0

UNPUBLISHED PROTOTYPE

Experimental impact query

Total tokens
749,471
Charged time
317.94 s
Audited correctness
4 / 4
Original machine grade
4 / 4
Workflow reviewed
4 / 4 pass
Grep calls
10
MCP calls
5

CONTROL

Serena

Total tokens
1,597,731
Charged time
487.05 s
Audited correctness
4 / 4
Original machine grade
2 / 4
Workflow reviewed
4 / 4 pass
Grep calls
18
MCP calls
12

CONTROL

CodeGraph

Total tokens
1,526,064
Charged time
476.73 s
Audited correctness
4 / 4
Original machine grade
3 / 4
Workflow reviewed
4 / 4 pass
Grep calls
15
MCP calls
4

4 original failures came from a grader defect that treated separate cited occurrences as duplicates. The uniform audit corrects these separately. 1 substantive answer error remains. Original grades and the failed frozen gate are preserved.

Repetition 1: 24.56% lower tokens and 28.62% lower charged time. Repetition 2: 1.49% lower tokens and 14.10% lower charged time. Every task pair appears below, including losses.

Actual public Codex actions from the preselected first native and experimental impact sessions. The overall failed confirmation gate stays visible throughout this selected pair replay.
The overall 16 session gate failed. This is the first task and repetition, selected before outcomes, not the aggregate result. Actual public Codex action replay of the experimental impact query. Separate sessions aligned at the start; playback accelerated. Only final measured token totals are shown.
Every task and repetition

Type contract impact · repetition 1

Prototype versus native: 27.37% lower tokens; 34.72% lower charged time.

Type contract impact · repetition 2

Prototype versus native: 9.19% higher tokens; 1.27% higher charged time.

Runtime contract impact · repetition 1

Prototype versus native: 21.21% lower tokens; 21.70% lower charged time.

Runtime contract impact · repetition 2

Prototype versus native: 9.17% lower tokens; 27.02% lower charged time.

CROSS PACKAGE RESEARCH · DEVELOPMENT ONLY

A narrower question.
A measured answer.

Can focused package evidence reduce the work of tracing a change across real consumers? These are development trials. A repeatable advantage on unseen tasks has not been established.

Pinned pnpm source, native TypeScript and package tools available in every condition, and independent checks. The impact query is an unpublished prototype. Each provider condition must use its advertised tool for the first relevant investigation, then may choose freely. These trials measure guided use; default autonomous adoption is untested. One repetition cannot establish a general speed or token advantage.

Recorded Codex actions from the preselected native and experimental package impact sessions, followed by their measured time, token counts, correctness and workflow review.
Recorded public Codex actions. Experimental impact query, one development task. Separate sessions aligned at the start; playback accelerated. Final measured totals only. A repeatable advantage on unseen tasks has not been established.

Package impact analysis

Lower measured cost on one development task. One repetition per condition. 10 production packages in scope.

Candidate versus Native tools: 21.48% lower total tokens; 35.22% lower charged time.

Candidate versus Serena: 27.13% lower total tokens; 40.33% lower charged time.

Both cost thresholds were observed in this development trial. The requirement is at least 20% lower total tokens and charged time against each control. Confirmation on unseen tasks is still required.

Impact analysis with a report writer

Recorded development results. One repetition per condition. 10 production packages in scope.

Candidate versus Native tools: 22.10% lower total tokens; 0.55% lower charged time.

Candidate versus Serena: 25.27% lower total tokens; 21.68% lower charged time.

Did not meet both cost thresholds. The requirement is at least 20% lower total tokens and charged time against each control. Confirmation on unseen tasks is still required.

Catalog consistency repair with native validation

Recorded development results. One repetition per condition. 3 production packages in scope.

Catalog consistency repair

Environment or workflow limits prevent a complete comparison. One repetition per condition. 3 production packages in scope.

Independent repair checks and the agent’s public validation are separate. This environment limited study cannot establish a complete workflow comparison. See the native validation audit for the exact failure and execution boundaries.

Initial migration and impact baseline, with its grading audit

Five package migration

Recorded development results. One repetition per condition. 5 production packages in scope.

Candidate versus Native tools: 27.72% higher total tokens; 38.31% higher charged time.

Candidate versus Serena: 33.70% higher total tokens; 24.39% higher charged time.

Did not meet both cost thresholds. The requirement is at least 20% lower total tokens and charged time against each control. Confirmation on unseen tasks is still required.

Package impact analysis

Recorded development results. One repetition per condition. 10 production packages in scope.

The initial impact grader had errors. Original machine grades remain visible and are not a correctness ranking. The separate correctness audit records the evidence and correction.

GUIDED TOOL USE · TWELVE CODEX SESSIONS

Fewer grep calls.
More tokens and time.

Compared with native tools, the experimental packet used 11.9% more tokens and 20.6% more charged time. Grep calls fell from 9 to 4. All three conditions were correct in 4 of 4 sessions.

Two localized repairs in an older pnpm snapshot with 198 packages. Each needs one implementation file, and supplied failing checks give useful clues. This does not establish scaling or general superiority on large repositories. The source packet is an unpublished Typelatch prototype. The task and workflow policy are shared. Each condition names its available provider and tools.

Recorded Codex actions side by side for the preselected maintenance task, using native tools and the experimental Typelatch source packet, followed by their measured totals.
Recorded public Codex actions from the preselected pair. Experimental source packet. Separate sessions aligned at the start; playback accelerated. Shared task and workflow policy with explicit provider inventories.

Native tools

Total tokens
361,367
Charged time
96.9 s
Correct solutions
4 / 4
Workflow followed
4 / 4
Grep calls
9
MCP calls
0

Serena 2.1.0

Total tokens
636,774
Charged time
130.8 s
Correct solutions
4 / 4
Workflow followed
4 / 4
Grep calls
6
MCP calls
12

Experimental source packet

Total tokens
404,262
Charged time
116.9 s
Correct solutions
4 / 4
Workflow followed
4 / 4
Grep calls
4
MCP calls
4

Did not meet the qualifying gate

Measured token, time and correctness thresholds: Failed. Independent workflow review: Passed. Both controls must be beaten under the frozen rules. All sessions and costs remain included.

Packet versus Native tools: 11.9% higher total tokens; 20.6% higher charged time.

Packet versus Serena 2.1.0: 36.5% lower total tokens; 10.6% lower charged time.

Exact decision reasons
  • native/totalTokens: aggregate or median reduction is below20%.
  • native/totalTokens: a repeat fails to improve.
  • native/chargedTimeMs: aggregate or median reduction is below20%.
  • native/chargedTimeMs: a repeat fails to improve.
  • competitor/chargedTimeMs: aggregate or median reduction is below20%.
Every session, grade and returned evidence

1. pnpm changed-project selection after a file move

Repeat 1 · Native tools

Correctness
Pass
Workflow
Pass
Total tokens
87,111
Charged time
23.0 s
Grep calls
2
MCP calls
0

completed

2. pnpm changed-project selection after a file move

Repeat 1 · Experimental source packet

Correctness
Pass
Workflow
Pass
Total tokens
94,502
Charged time
29.4 s
Grep calls
1
MCP calls
1

completed

3. pnpm changed-project selection after a file move

Repeat 1 · Serena 2.1.0

Correctness
Pass
Workflow
Pass
Total tokens
149,825
Charged time
29.7 s
Grep calls
2
MCP calls
3

completed

4. pnpm global executable-directory API migration

Repeat 1 · Experimental source packet

Correctness
Pass
Workflow
Pass
Total tokens
123,638
Charged time
31.5 s
Grep calls
1
MCP calls
1

completed

5. pnpm global executable-directory API migration

Repeat 1 · Serena 2.1.0

Correctness
Pass
Workflow
Pass
Total tokens
168,441
Charged time
34.8 s
Grep calls
2
MCP calls
3

completed

6. pnpm global executable-directory API migration

Repeat 1 · Native tools

Correctness
Pass
Workflow
Pass
Total tokens
101,312
Charged time
24.8 s
Grep calls
3
MCP calls
0

completed

7. pnpm global executable-directory API migration

Repeat 2 · Native tools

Correctness
Pass
Workflow
Pass
Total tokens
84,632
Charged time
23.6 s
Grep calls
2
MCP calls
0

completed

8. pnpm global executable-directory API migration

Repeat 2 · Serena 2.1.0

Correctness
Pass
Workflow
Pass
Total tokens
147,426
Charged time
30.7 s
Grep calls
1
MCP calls
3

completed

9. pnpm global executable-directory API migration

Repeat 2 · Experimental source packet

Correctness
Pass
Workflow
Pass
Total tokens
94,057
Charged time
29.1 s
Grep calls
1
MCP calls
1

completed

10. pnpm changed-project selection after a file move

Repeat 2 · Serena 2.1.0

Correctness
Pass
Workflow
Pass
Total tokens
171,082
Charged time
35.6 s
Grep calls
1
MCP calls
3

completed

11. pnpm changed-project selection after a file move

Repeat 2 · Experimental source packet

Correctness
Pass
Workflow
Pass
Total tokens
92,065
Charged time
26.9 s
Grep calls
1
MCP calls
1

completed

12. pnpm changed-project selection after a file move

Repeat 2 · Native tools

Correctness
Pass
Workflow
Pass
Total tokens
88,312
Charged time
25.5 s
Grep calls
2
MCP calls
0

completed

Accounting, workflow review and limits

Model: gpt-6.1-sol. Reasoning: medium. The protocol requires every condition to run the supplied failing native check before its first investigation. Provider conditions must attempt that investigation through the declared provider, then choose tools freely. Startup instructions alone do not qualify.

The gate requires at least 20% lower total tokens and charged time against each control, both in aggregate and in the median paired comparison. Both repeats must improve, correctness must not decline, and all four packet solutions must pass. A qualifying result also requires an independent review of first investigation order and relevant provider use. Empty results, tool errors and unknown compliance remain distinct.

Public action evidence supports the workflow review; matching hashes alone do not prove relevance or ordering inside compound shell commands. Returned tool output replaces private path prefixes while retaining original payload hashes. Grep counts shell calls with recorded search commands. Unknown usage is not zero. Common corpus preparation, grading and teardown are reported separately. Public upstream repairs may appear in model training data; caches and model sampling can affect results.

REAL MAINTENANCE TASKS

Four conditions.
Every session counted.

2 public maintenance tasks, 2 repeats per condition, 16 actual Codex sessions. Prompts are identical within each task. Tool choice is optional.

Scroll the table to compare tokens, time and tool calls.

All four conditions, in a fixed order
ConditionCorrectTotal tokensCharged timeGrep callsMCP calls
Native tools4 / 4361,174106.7 s100
Serena 2.1.04 / 4378,639103.3 s110
Typelatch 0.4.0 candidate4 / 4407,578100.2 s120
Typelatch source packet v2 prototype4 / 4393,729104.3 s120

Tokens include cached input and output, each counted once. Charged time includes provider preparation and the complete agent session. These are two localized repairs in an older pnpm snapshot with 198 packages. Each needs one implementation file; supplied failing checks give useful clues. This does not test scaling or establish an advantage on large repositories. These public tasks may appear in model training data.

Typelatch 0.4.0 candidate

Did not meet the gate. Observed MCP use in 0 of 4 sessions. Zero use remains in the results. No MCP calls were observed, so this condition does not demonstrate a retrieval benefit.

Recorded gate reasons
  • native/totalTokens: aggregate or median reduction is below20%.
  • native/totalTokens: a repeat fails to improve.
  • native/chargedTimeMs: aggregate or median reduction is below20%.
  • native/chargedTimeMs: a repeat fails to improve.
  • competitor/totalTokens: aggregate or median reduction is below20%.
  • competitor/totalTokens: a repeat fails to improve.
  • competitor/chargedTimeMs: aggregate or median reduction is below20%.
  • competitor/chargedTimeMs: a repeat fails to improve.

Typelatch source packet v2 prototype

Did not meet the gate. Observed MCP use in 0 of 4 sessions. Zero use remains in the results. No MCP calls were observed, so this condition does not demonstrate a retrieval benefit.

Recorded gate reasons
  • native/totalTokens: aggregate or median reduction is below20%.
  • native/totalTokens: a repeat fails to improve.
  • native/chargedTimeMs: aggregate or median reduction is below20%.
  • native/chargedTimeMs: a repeat fails to improve.
  • competitor/totalTokens: aggregate or median reduction is below20%.
  • competitor/totalTokens: a repeat fails to improve.
  • competitor/chargedTimeMs: aggregate or median reduction is below20%.
  • competitor/chargedTimeMs: a repeat fails to improve.
Every session and its evidence
Frozen execution order, including failures and unknown results
OrderTask and conditionCorrectnessTokensCharged timeGrepMCPCapture state
1pnpm changed-project selection after a file moveRepeat 1 · Native toolsPass77,60922.5 s20completed
2pnpm changed-project selection after a file moveRepeat 1 · Typelatch 0.4.0 candidatePass74,36219.0 s20completed
3pnpm changed-project selection after a file moveRepeat 1 · Serena 2.1.0Pass91,78222.5 s30completed
4pnpm changed-project selection after a file moveRepeat 1 · Typelatch source packet v2 prototypePass70,23520.1 s20completed
5pnpm global executable-directory API migrationRepeat 1 · Typelatch 0.4.0 candidatePass126,75929.7 s40completed
6pnpm global executable-directory API migrationRepeat 1 · Native toolsPass104,27834.9 s30completed
7pnpm global executable-directory API migrationRepeat 1 · Typelatch source packet v2 prototypePass127,62431.3 s40completed
8pnpm global executable-directory API migrationRepeat 1 · Serena 2.1.0Pass82,34224.7 s20completed
9pnpm global executable-directory API migrationRepeat 2 · Serena 2.1.0Pass132,90932.1 s40completed
10pnpm global executable-directory API migrationRepeat 2 · Typelatch source packet v2 prototypePass104,33429.9 s30completed
11pnpm global executable-directory API migrationRepeat 2 · Native toolsPass104,44325.7 s30completed
12pnpm global executable-directory API migrationRepeat 2 · Typelatch 0.4.0 candidatePass107,92525.5 s30completed
13pnpm changed-project selection after a file moveRepeat 2 · Typelatch source packet v2 prototypePass91,53623.1 s30completed
14pnpm changed-project selection after a file moveRepeat 2 · Serena 2.1.0Pass71,60623.9 s20completed
15pnpm changed-project selection after a file moveRepeat 2 · Typelatch 0.4.0 candidatePass98,53226.0 s30completed
16pnpm changed-project selection after a file moveRepeat 2 · Native toolsPass74,84423.6 s20completed
Accounting and the frozen decision gate

Model: gpt-6.1-sol. Reasoning: medium. Each candidate is judged separately against native tools and Serena. The gate requires at least 20% lower tokens and charged time in aggregate and in the median paired comparison, improvement in both repeats, and no correctness decline overall or per task. Every requested before and after native check must be observed. A qualifying win also requires all four candidate solutions to pass. Candidate results are never pooled.

Grep counts shell calls containing recorded search commands, not every possible way to search. MCP counts include failed calls. Incomplete captures show unknown comparable action counts; raw observed counts remain in the linked evidence. Unknown usage is not zero. Provider caches, host load and model sampling can affect results.

Accounting totals
MetricNative toolsSerena 2.1.0Typelatch 0.4.0 candidateTypelatch source packet v2 prototype
Input tokens358,425375,864404,794390,959
Cached input, already included308,352310,272354,560309,888
Output tokens2,7492,7752,7842,770
Provider preparation0.0 s0.0 s0.0 s0.0 s
Agent time106.7 s103.3 s100.2 s104.3 s
Common fixture preparation, excluded59.6 s59.9 s60.3 s59.9 s
Independent grading, excluded31.1 s31.2 s31.2 s31.2 s
Teardown, excluded0.0 s0.0 s0.0 s0.0 s
Successful MCP calls0000
Failed MCP calls0000

THE PAIRED AGENT BENCHMARK

Same tasks.
Measured differences.

Actual Codex sessions, with and without Typelatch. Same workflow instructions. Every result stays in the comparison.

3 tasks2 repeats per condition12 sessions06 Nov 20260.4.0 candidate

Side by side replay of actual Codex actions on the same SQLite rollback task, without Typelatch and with Typelatch.
Recorded Codex actions, replayed side by side. Separate sessions aligned at start; playback accelerated. This is an action replay, not a screen recording. The shared prompt requests Typelatch when available and native tools otherwise.

Grep shell calls

Without Typelatch
22
With Typelatch
13

40.9% lower

Includes content search and file listing.

Model tokens

Without Typelatch
954,947
With Typelatch
1,556,137

63.0% higher

Reported input plus output. Cached input included.

Time including indexing

Without Typelatch
320.0 s
With Typelatch
463.3 s

44.8% higher

Agent time plus Typelatch index preparation.

Correct solutions

Without Typelatch
4 / 6
With Typelatch
5 / 6

Independent checks after each session

Without Typelatch: 2 failed, 0 unknown. With Typelatch: 1 failed, 0 unknown.

Model token use was 63.0% higher with Typelatch. Time including indexing was 44.8% higher with Typelatch.

This candidate did not meet the recorded performance gate. Both token use and time including indexing must improve by at least 10%, without worse correctness.

Small authored task set, not a general performance ranking. Both conditions receive identical task and workflow instructions: use Typelatch when available and native tools otherwise. All sessions are included, regardless of correctness. 6 of 6 Typelatch enabled sessions called its tools.

Every paired result
TaskConditionGrep callsTokensAgent timeCorrectness
SQLite batch rollbackRepeat 1Without Typelatch3117,66132.1 sPass
With Typelatch1155,93144.7 sPass
SQLite batch rollbackRepeat 2Without Typelatch3121,51532.7 sPass
With Typelatch1102,63942.7 sPass
Cart preview correctnessRepeat 1Without Typelatch4152,09263.2 sPass
With Typelatch2299,36988.2 sPass
Cart preview correctnessRepeat 2Without Typelatch3168,66756.8 sPass
With Typelatch4353,23387.7 sPass
Partner manifest validationRepeat 1Without Typelatch5195,35767.6 sFail
With Typelatch2332,73582.3 sPass
Partner manifest validationRepeat 2Without Typelatch4199,65567.6 sFail
With Typelatch3312,23085.3 sFail
Accounting and method

What the numbers mean

Requested model: gpt-6.1-sol. Reasoning: medium. The same Codex CLI and native tools were available in both conditions. Package: typelatch@0.4.0, adding its local MCP tools.

Grep calls count recorded shell calls that invoke rg, grep, egrep or fgrep. A compound shell call counts once, not once per process. File listing and content search are separated below. These counts do not cover every way to search text.

Tokens are the Codex CLI usage totals. Input includes cached input and repeated context; output includes reasoning when reported. Component counts are not added twice. Unknown data stays unknown.

Agent time runs from process launch to exit, including MCP startup. Fixture preparation includes dependency installation and the initial grader check. Typelatch index preparation is measured separately. Both preparation totals and final independent grading are outside agent time. The candidate time comparison adds index preparation to agent time. Common fixture preparation, final grading and shared runtime installation remain excluded. Fixture comparison normalizes workspace paths in two generated native build files; original hashes remain recorded. Provider caching, service load and run order can affect time and usage.

Correctness comes from independent assertions after the agent stops, including protected file checks. Passing this fixture does not establish general coding success.

Totals across all sessions
Recorded metricWithout TypelatchWith Typelatch
Agent time, excluding index preparation320.0 s430.9 s
Content search shell calls1510
File listing shell calls126
Ambiguous search shell calls00
All shell calls5729
MCP calls032
MCP calls with errors00
Input tokens945,9411,546,176
Cached input tokens, already included820,2241,346,688
Uncached input tokens125,717199,488
Output tokens9,0069,961
Reasoning output tokens, already included817890
Fixture preparation31.6 s30.6 s
Typelatch index preparation0.0 s32.4 s
Earlier 0.3.0 comparison

Original recorded study, kept separate. Model token use was 98.8% higher and agent time was 42.4% higher with Typelatch.

Original 0.3.0 study totals
MetricWithout TypelatchWith Typelatch
Grep shell calls2210
Model tokens936,6831,861,666
Agent time317.8 s452.7 s
Correct solutions4 / 65 / 6

A USEFUL FIRST STOP

Start with the question.
Follow the evidence.

When you do not know the file or package, a text search can turn into another search. Give your agent source locations and dependency APIs in the same workflow.

Keep grep for exact text. Use Typelatch to discover context, inspect exact APIs, and check a change. Fewer tool calls or tokens are not guaranteed.

01

Find the relevant source.

workspace_search searches local source, tests, docs and available dependency indexes. Coverage gaps stay visible.

02

Use the API you actually have.

workspace_context resolves real imports. library_symbol returns declarations for an exact indexed package version.

03

Make “done” mean checked.

Your agent edits with its usual tools. workspace_validate compiles the project and runs explicitly supplied assertions.

MAKE IT PART OF THE WORKFLOW

Your agent.
Connected locally.

Run setup, choose your client,
and confirm. No repository clone or global installation.

typelatch on npm

Connect Typelatch

npx typelatch@0.3.0 setup

Requires Node.js 22.12 or newer, npm, Bash, and the Codex or Claude Code CLI. The native SQLite dependency may need a C++ toolchain if a prebuilt binary is unavailable.

Initialize from your lockfile

npx typelatch@0.3.0 sync

Published 0.3.0 reads npm, pnpm, Yarn and text Bun lockfiles. Preview the plan with sync --dry-run --json, then build reusable local indexes. Indexing needs npm access. Indexed search works offline.

Deno and binary Bun lockfile support are 0.4.0 development additions and currently require the development checkout in PR 3.

Choose your monorepo projects

npx typelatch@0.3.0 scope add apps/web packages/ui

Save the projects you need. Source search and plain sync use that selection. Add more later with scope add, or narrow it with scope remove. Use sync --workspaces to prepare every declared workspace instead. Monorepo workflow ↗

Start your first session

LOCAL STDIO MCP

Setup registers the exact package version for the client you choose. Restart your agent in your project and ask: "Use workspace_search to explain how this project is organized." Use the same TYPELATCH_HOME for indexing and the MCP server. Full setup and troubleshooting

GIVE YOUR AGENT A USEFUL INSTRUCTION

Make evidence
part of “done”.

ADAPT TO YOUR TRUSTED PROJECT

Use workspace_search with my repository root when the relevant file or package is unknown. Use the returned source and coverage information; read more only when evidence is missing or stale. When a dependency API matters to the change, resolve it with workspace_context and inspect the needed declaration with library_symbol. After editing, run the required compiler and authorized tests once through workspace_validate or native project commands. Report what was retrieved, resolved, compiled and tested, including anything unknown or not run.

More workflows and all seven tools

Follow the agent workflow: discover, reproduce, edit and verify. Includes a runnable exercise, actual MCP requests and assertion output.

EARLIER PACKAGE API RECORDING

RECORDED 08 SEPT 2026

The result is only
as good as the evidence.

A real SQLite coding question.
Two things an agent needs:
the right API, and a way to check its work.

THE QUESTION
How can I import a batch of contacts into SQLite atomically, roll back every new row if a UNIQUE name constraint fails, and safely store a name containing a quote?

Kysely 0.28.8 better-sqlite3 13.0.3 TypeScript

This separate historical capture used published Typelatch 0.1.1 and a scripted MCP client. It is not the Codex session above, and is not a live agent session. Jcode authored the question and implementation. Commentary is authored separately from tool output. Open the full recording Inspect the captured source files

RETRIEVAL IS A STARTING POINT

A question in.
A source you can inspect out.

Typelatch searches the locally indexed kysely@0.28.8 artifact. It returns API signatures and their source locations, not a generated answer.

THE AGENT'S SEARCH

The first question found transaction and insertion APIs. The agent then narrowed the request to the callback API.

Inspect the initial question and returned APIs
{
  "name": "library_search",
  "arguments": {
    "package": "kysely",
    "version": "0.28.8",
    "question": "How can I import a batch of contacts into SQLite atomically, roll back every new row if a UNIQUE name constraint fails, and safely store a name containing a quote?",
    "limit": 5
  }
}

Returned symbols and source locations, in recorded order:

  • cjs/kysely.ControlledTransactiondist/cjs/kysely.d.ts:641
  • esm/kysely.ControlledTransactiondist/esm/kysely.d.ts:641
  • cjs/query_builder/insert_query_builder.InsertQueryBuilderdist/cjs/query-builder/insert-query-builder.d.ts:25
  • esm/query_builder/insert_query_builder.InsertQueryBuilderdist/esm/query-builder/insert-query-builder.d.ts:25
  • cjs/operation_node/unique_constraint_node.UniqueConstraintNodedist/cjs/operation-node/unique-constraint-node.d.ts:4
Full request and response
library_searchREFINED REQUEST
{
  "package": "kysely",
  "version": "0.28.8",
  "question": "TransactionBuilder execute",
  "limit": 5
}

A useful refinement, not a claim of perfect first try retrieval.

RETURNED FROM LOCAL SQLITE

kysely@0.28.8

TransactionBuilder<DB>

export declare class TransactionBuilder<DB> {
    #private;
    constructor(props: TransactionBuilderProps);
    setAccessMode(accessMode: AccessMode): TransactionBuilder<DB>;
    setIsolationLevel(isolationLevel: IsolationLevel): TransactionBuilder<DB>;
    execute<T>(callback: (trx: Transaction<DB>) => Promise<T>): Promise<T>;
}

The callback receives a transaction. The agent can put every insert inside it and let a rejection escape.

Inspect the exact symbol request
{
  "name": "library_symbol",
  "arguments": {
    "package": "kysely",
    "version": "0.28.8",
    "symbol": "esm/kysely.TransactionBuilder"
  }
}
Full request and response

WHAT THE TOOL ACTUALLY QUERIED

library_searchbrain.dbkysely.d.ts:623

Your agent calls an MCP tool. Typelatch queries its own SQLite knowledge store. That store is separate from the SQLite database in the example application.

Inspect the read only SQLite store audit

A separate audit queried this file after the MCP lookup. This is recorded SQL inspection, not an arbitrary SQL MCP tool.

$TYPELATCH_HOME/brains/kysely/0.28.8/brain.db
{
  "sql": "SELECT qualified_name, source_path, line_start, line_end FROM symbols WHERE qualified_name = ?",
  "parameters": [
    "esm/kysely.TransactionBuilder"
  ],
  "rows": [
    {
      "qualified_name": "esm/kysely.TransactionBuilder",
      "source_path": "dist/esm/kysely.d.ts",
      "line_start": 623,
      "line_end": 629
    }
  ]
}
Full store audit, schema and counts

Found is not verified. A returned declaration has not compiled or executed the application.

Now use it in the workspace

TURN THE API INTO WORKING CODE

Keep the whole batch.
Or keep none of it.

The agent uses the transaction callback and binds values instead of interpolating SQL. Then it asks Typelatch to compile the workspace and run the supplied assertions.

batch.ts EXECUTED FIXTURE EXCERPT
export async function importContacts(db: Kysely<Tables>, contacts: Contact[]) {
  // Let rejection escape the callback so Kysely rolls back the whole batch.
  await db.transaction().execute(async transaction => {
    for (const contact of contacts) {
      await transaction.insertInto('contact').values(contact).execute()
    }
  })
}

Authored implementation, informed by the retrieved declarations. Read the captured fixture

HOW THE AGENT USES IT

Every insert goes through transaction.

The promise rejects on a duplicate name. The error is not swallowed, so the transaction can roll back.

That is the implementation decision. The assertions below are the execution evidence.

Before validation: workspace_context resolved Kysely 0.28.8 in the installed project. Artifact match: unknown.

Inspect the context request and evidence
{
  "name": "workspace_context",
  "arguments": {
    "config": "$WORKSPACE/tsconfig.json",
    "file": "$WORKSPACE/batch.ts",
    "importSpecifier": "kysely",
    "symbol": "Kysely",
    "expectedVersion": "0.28.8"
  }
}
{
  "retrieved": {
    "status": "not-run",
    "reason": "No discovery question supplied"
  },
  "resolved": {
    "status": "pass",
    "reason": "Import resolved by the project compiler"
  },
  "versionMatch": {
    "status": "pass",
    "reason": "Resolved kysely@0.28.8; expected 0.28.8"
  },
  "artifactMatch": {
    "status": "unknown",
    "reason": "Installed package contents have not been compared with the registry artifact"
  },
  "typechecked": {
    "status": "not-run",
    "reason": "Use workspace validation for project diagnostics"
  },
  "tested": {
    "status": "not-run",
    "reason": "No test command executed"
  }
}
Full request and response
workspace_validateACTUAL REQUEST
{
  "config": "$WORKSPACE/tsconfig.json",
  "workspaceRoot": "$WORKSPACE",
  "timeoutMs": 60000,
  "record": true,
  "queryId": "9bfdae25-f3f2-4110-8b5f-c39d045bdafd",
  "testCommand": [
    "npm",
    "test"
  ]
}

$WORKSPACE replaces the private absolute fixture path. Tests run only because testCommand was explicitly supplied.

RETURNED EVIDENCE

TypeScript compilation
pass
Explicit test command
pass
Recorded inputs unchanged
pass
Inspect the validation result

For this fixture and these assertions. Not a general correctness guarantee.

What actually happened

commits the whole valid batch and binds a quote as data pass

Executed assertion source from batch.test.ts:

test('commits the whole valid batch and binds a quote as data', async () => {
  const db = await createDatabase()
  try {
    const contacts = [{ id: 1, name: "O'Reilly" }, { id: 2, name: "Robert'); DROP TABLE contact;--" }]
    const compiled = db.insertInto('contact').values(contacts[0]!).compile()
    assert.equal(compiled.sql, 'insert into "contact" ("id", "name") values (?, ?)')
    assert.deepEqual(compiled.parameters, [1, "O'Reilly"])
    await importContacts(db, contacts)
    assert.deepEqual(await db.selectFrom('contact').selectAll().orderBy('id').execute(), contacts)
    console.log(JSON.stringify({ assertion: 'parameter binding and exact round trip', sql: compiled.sql, parameters: compiled.parameters, rows: contacts }))
  } finally {
    await db.destroy()
  }
})

Exact recorded stdout excerpt:

# {"assertion":"parameter binding and exact round trip","sql":"insert into \\"contact\\" (\\"id\\", \\"name\\") values (?, ?)","parameters":[1,"O'Reilly"],"rows":[{"id":1,"name":"O'Reilly"},{"id":2,"name":"Robert'); DROP TABLE contact;--"}]}
ok 1 - commits the whole valid batch and binds a quote as data
Complete validation request and response
UNIQUE failure rolls back an earlier insert in the same batch pass

Executed assertion source from batch.test.ts:

test('UNIQUE failure rolls back an earlier insert in the same batch', async () => {
  const db = await createDatabase()
  try {
    await importContacts(db, [{ id: 1, name: 'existing' }])
    await assert.rejects(importContacts(db, [{ id: 2, name: 'must roll back' }, { id: 3, name: 'existing' }]), { code: 'SQLITE_CONSTRAINT_UNIQUE' })
    const rows = await db.selectFrom('contact').selectAll().execute()
    assert.deepEqual(rows, [{ id: 1, name: 'existing' }])
    console.log(JSON.stringify({ assertion: 'whole batch rollback', rejectedCode: 'SQLITE_CONSTRAINT_UNIQUE', rows }))
  } finally {
    await db.destroy()
  }
})

Exact recorded stdout excerpt:

# {"assertion":"whole batch rollback","rejectedCode":"SQLITE_CONSTRAINT_UNIQUE","rows":[{"id":1,"name":"existing"}]}
ok 2 - UNIQUE failure rolls back an earlier insert in the same batch
Complete validation request and response

Exact test names from the recorded output. Open either assertion to inspect its source and result. Exit code 0.

Inspect complete execution output

> test
> node --experimental-strip-types --test --test-reporter=tap batch.test.ts

TAP version 13
# {"assertion":"parameter binding and exact round trip","sql":"insert into \\"contact\\" (\\"id\\", \\"name\\") values (?, ?)","parameters":[1,"O'Reilly"],"rows":[{"id":1,"name":"O'Reilly"},{"id":2,"name":"Robert'); DROP TABLE contact;--"}]}
# {"assertion":"whole batch rollback","rejectedCode":"SQLITE_CONSTRAINT_UNIQUE","rows":[{"id":1,"name":"existing"}]}
# Subtest: commits the whole valid batch and binds a quote as data
ok 1 - commits the whole valid batch and binds a quote as data
  ---
  duration_ms: 252.026792
  type: 'test'
  ...
# Subtest: UNIQUE failure rolls back an earlier insert in the same batch
ok 2 - UNIQUE failure rolls back an earlier insert in the same batch
  ---
  duration_ms: 1.616292
  type: 'test'
  ...
1..2
# tests 2
# suites 0
# pass 2
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 747.708542

A CHECK THAT CAN CATCH THE MISTAKE

Remove the transaction. The code still compiles.

The same atomicity requirement fails. The earlier row is left in the database. That is why compilation and runtime assertions are separate evidence.

compile pass
assertion fail
Inspect failing control

Unknown stays unknown. Workspace artifact equivalence is not established by this run.

Reproduce and inspect the run