Retrieval tied to an event

Agent context is often assembled before the work begins. TypeLens waits for two concrete events.

After a read, the plugin knows the file and visible range. It asks the TypeScript language service which declarations matter there, ranks and deduplicates them, and appends complete declarations. After a write, it knows which file changed, so it can run bounded diagnostics and put that file's errors first.

This is semantic locality, not file proximity. A declaration elsewhere in a monorepo may explain the current code better than the next 200 lines in the same file. TypeScript's Compiler API exposes programs, source files, symbols, types, and diagnostics. A tool can follow the compiler's model of the program instead of relying only on text similarity.

The sequence matters too. Type context appears after the agent has shown interest in a file, so it does not occupy every turn. Diagnostics appear just after the edit that caused them, while cause and effect are still easy to connect. Our guide to agent context budgets covers the wider retrieve, cache, trim, and compact cycle. TypeLens applies one narrow version of that logic to compiler-resolved contracts.

Do not cut the useful part in half

A token cap can create a perverse result: retrieval finds the right definition, then clips it halfway through a union, generic constraint, or overload set. TypeLens says it emits complete declarations, stopping before the budget rather than slicing a declaration mid-signature.

That trade makes sense. One intact interface is usable. One and a half interfaces can suggest a contract that does not exist. Automatic analysis defaults to 800 estimated tokens, a dependency depth of four, a 1.5-second timeout, and a 2 MiB file limit. Explicit checks receive five seconds. These are project defaults, not proof that 800 tokens fits every codebase.

The engineering rule is simple: retrieve in units that match what the developer must act on. In typed code, that is often a declaration rather than an arbitrary span of characters.

Fail-open keeps work moving, with a catch

TypeLens preserves the underlying tool result. A failed analysis does not turn a successful read or write into an error. Its circuit breaker pauses automatic analysis for 30 seconds after five operational failures within 60 seconds, while explicit tools and health reporting stay available.

That is a reasonable availability choice. A helper should not stop a developer from saving a file because its own analysis layer is struggling. The catch is important: no diagnostic does not mean no error. The agent or CI still needs an authoritative compiler and test run before merge.

Treat the injected output as quick feedback, not a release gate. An agent policy can say this plainly: repair reported errors immediately, then run the repository's normal checks before claiming the task is complete.

The evidence stops at acceptance testing

TypeLens 0.1.2 was released on August 28. The maintainer reports 18 test files and 61 passing tests, along with package, secret, and isolated DeepSeek Harness lifecycle checks. The acceptance record targets DSH 0.1.1-rc.2 on macOS arm64, with Linux CI on Node.js 22 and 24.

That is useful release evidence, but not an independent coding-agent benchmark. Nothing published yet shows that TypeLens reduces defects, token use, or task time across representative repositories. The project had no adoption signal when checked, and Windows remains a compatibility target rather than a release gate.

Language support has clear edges. TypeScript, TSX, JavaScript, and JSX are supported. Vue and Svelte script blocks use optional compilers when available and a bounded fallback otherwise; template semantics sit outside the analysis boundary. Large composite repositories also carry familiar tooling costs. TypeScript's project-reference documentation describes trade-offs around declaration outputs and editor performance.

“Local analysis” is not “local inference.” TypeLens says it makes no outbound requests and holds source-bearing analysis state in memory. Once appended, however, the context enters the next model request and follows the configured provider's privacy policy.

The pattern is larger than TypeLens

You can borrow the design without adopting this plugin:

• Let an observed action trigger retrieval instead of preloading speculative context.
• Return whole semantic units, under hard limits for depth, time, size, and tokens.
• Put validation beside the edit that caused it, while keeping authoritative checks separate.
• If enrichment fails, preserve the underlying tool result and make the skipped analysis visible.

The same approach could work with another language server, a compiler service, a schema registry, or an API-description graph. It also suits model-routing products such as api.ish.chat: send the model a small contract selected for the current action, not an indiscriminate repository dump.

TypeLens is far too new to call proven. The next useful evidence would be a repository-level comparison: measure whether post-read declarations prevent type mistakes, how much latency they add, and how often fail-open behavior leaves the agent falsely confident. Until then, the design is worth copying as an experiment, with the normal compiler and test suite still in charge.