When an AI coding agent opens a file in a large monorepo, it suffers from a fundamental visibility problem: blind local navigation.
A high-level instruction file or a package-level contract tells the agent what invariants govern the overall package. But inside a specific 500-line screen, hook, or route handler, the agent cannot see the live code topology without reading through hundreds of lines of imported code:
- What runtime is this? Is this an interactive React client component, a server component rendering in a streaming pipeline, a background worker function, or an HTTP route handler?
- What child components are actually rendered? Which imported identifiers correspond to rendered JSX elements versus type utilities or helper functions?
- What wires connect this file to the rest of the system? What outbound API endpoints are fetched? What background queue events are emitted? What database tables are queried?
- Is multi-tenant isolation enforced? If a query reads from a table, does it explicitly filter by tenant isolation keys, or does it risk leaking data across tenant boundaries?
In October 2026, we expanded Agent-Native Context (ANC) with source-level code topology and wire tracing (anc trace). This article explains how it works, why dynamic on-demand tracing beats static context files, and how it plugs directly into the agent’s editing loop.
The limits of manifest-level context
Our first implementation of Agent-Native Context placed a CONTEXT.agent.yaml contract at the root of each package. That contract answered package-level questions:
- What workspace packages does this module import?
- What invariants must stay true, and what executable test proves each one?
- What actions can an agent perform autonomously versus requiring founder sign-off?
This eliminated package-level drift and detected dependency cycles across workspace manifests.
However, once an agent entered a package to edit a specific file, manifest-level context was too broad. An agent modifying an ERP screen like HomeownerPortalView.tsx could see that the package depended on @proof/ui and @proof/api-client, but it had no immediate awareness that the screen rendered 26 specific child components, invoked two custom hooks, or called specific /api/v1/homeowner/... endpoints.
To compensate, agents either guessed API contracts, duplicated existing child components, or made database queries that overlooked tenant-scoping guards.
Extracting code topology from the Abstract Syntax Tree
Rather than forcing developers or agents to manually maintain documentation for thousands of individual source files, anc trace extracts topology directly from source code ASTs on demand.
1. Runtime execution context detection
The tracer inspects file directives, path conventions, and exported symbols to classify the file into one of seven runtime categories:
export type RuntimeContext =
| "client-component" // "use client" directive
| "server-component" // React Server Component (default in App Router)
| "route-handler" // Next.js route.ts / route.js with HTTP exports
| "server-action" // "use server" directive or server action export
| "background-worker" // Inngest function handler or queue worker
| "test-suite" // *.test.ts, *.spec.tsx
| "library-module"; // Standard TypeScript / JavaScript libraryClassifying the runtime context immediately prevents agents from attempting client-only operations (like useState or window access) in server components, or calling database drivers directly from client components.
2. Rendered JSX component resolution
The tracer scans JSX syntax trees for component invocations (tags starting with a capital letter) while filtering standard HTML5 elements (<div>, <button>, <span>) and SVG primitives (<path>, <circle>).
It cross-references every rendered component name against the file’s import declarations, outputting the exact relative or workspace import path:
renders:
- "ClaimTimeline (from ./timeline/ClaimTimeline)"
- "DryingProgressCard (from ./cards/DryingProgressCard)"
- "HomeownerHeader (from ./HomeownerHeader)"
- "PhotoGrid (from @proof/ui)"An agent no longer needs to grep the codebase to find where child UI state originates.
3. Outbound and inbound connector tracing
The engine extracts network and messaging connectors:
- Outbound API Requests: Detects
fetch(),apiClient, and client wrappers, resolving both static strings and template literals (e.g.,/api/jobs/${id}/photos). - Inbound Route Handlers: In route files, extracts exported HTTP methods (
GET,POST,PUT,DELETE). - Background Events: Detects event emission (
inngest.send) and event listeners (createFunction). - Domain Hooks: Identifies custom state and mutation hooks while omitting standard React primitives.
4. Tenant isolation compliance auditing
In multi-tenant architectures, database queries must strictly isolate data by tenant. Proof OS enforces this via database-level Row Level Security (RLS) and explicit application-level predicates.
When anc trace encounters database table queries (.from("table_name")), it analyzes the chained AST calls within the same query block:
wires:
tables:
- table: jobs
tenant_scoped: true
- table: lead_inbox
tenant_scoped: "WARN: missing explicit tenant_id scoping"If a query lacks .eq("tenant_id", ...) or a tenant-scoping guard, the trace surfaces an immediate mechanical warning before the agent writes code.
5. Transitive depth resolution
Modern frontend architectures separate presentation from data fetching by delegating network calls to local custom hooks (e.g., HomeownerPortalView.tsx importing ./useHomeownerState.ts).
With --depth 1, anc trace follows local relative imports to extract transitive APIs, database tables, and child hooks, giving the agent a complete picture of the file’s data pipeline.
Static files vs. Dynamic on-demand tracing
A natural question when designing context architectures is: Should every source file have a companion static YAML or JSON file in the repository?
In our monorepo of over 3,300 files across apps and packages, generating 3,300 static .trace.yaml files would introduce severe failure modes:
- Instant Staleness: A developer renames an import or updates an API route in a PR. The companion YAML is immediately out of date. Stale context actively misleads language models.
- Repository Bloat: Doubling the monorepo’s file count adds noise to git status, search, and version history.
- Merge Conflict Multipliers: Two branches touching the same directory constantly conflict on generated metadata.
The Solution: Head-Level Invariants + On-Demand AST Tracing
We chose a hybrid architecture:
- Package Head Level: Human authority and high-level invariants live in hand-authored, schema-validated
CONTEXT.agent.yamlfiles at each package root. - File Level: Connector wires, rendered components, and tenant audits are computed dynamically on demand in 2 milliseconds via
anc trace.
Putting topology in front of the agent
To make this context actionable during development, we integrated anc trace into the Claude Code PreToolUse hook (.claude/hooks/anc-context.mjs).
When an agent invokes an edit or write tool on any source file, the hook:
- Resolves the nearest package-level
CONTEXT.agent.yamlto extract localized invariants and authority rules. - Runs
traceFileon the target file with--depth 1. - Returns both structures formatted as compact YAML into
hookSpecificOutput.additionalContext.
The agent receives the exact invariants of the package and the live runtime topology of the specific file before executing the edit:
Agent-Native Context — contract for the module you are about to change:
# ANC contract: erp (apps/erp/CONTEXT.agent.yaml)
Purpose: Core restoration operations platform
Invariants:
- [erp-tenant-01] Every query must include tenant isolation predicates
Authority:
autonomous:
- Add UI components and API handlers with unit tests
founder_approval:
- Modify tenant RLS policies or billing matrix logic
Code Topology & Wire Trace (runtime connectors):
trace:
target: features/homeowner/HomeownerPortalView.tsx
runtime: client-component
module: erp
renders:
- "ClaimTimeline (from ./timeline/ClaimTimeline)"
- "HomeownerHeader (from ./HomeownerHeader)"
wires:
hooks:
- useHomeownerState
transitive_wires:
apis:
- /api/v1/homeowner/claim-status (via ./useHomeownerState)
- /api/v1/homeowner/photos (via ./useHomeownerState)Verification across the monorepo
To prove that the AST tracer handles real production complexity without crashing or hanging, we ran batch scans (anc trace --batch) across our active codebase:
apps/erp/features: 712 files scanned; classified 497 client components, 110 server components, 105 library modules; extracted 214 unique API endpoints.apps/erp/app: 1,101 files scanned; classified 720 route handlers, 241 client components, 90 server components; mapped 800 unique API paths and 146 database tables.packages/: 1,328 files scanned across all workspace libraries; classified 1,163 library modules and 47 Inngest background workers; mapped 122 database tables.apps/mobile-shell: 179 files scanned; classified 82 client components and 54 server components with zero warnings.
Across more than 3,300 files, the tracer executed with zero unhandled exceptions, zero regex lockups, and an average execution speed under 3 milliseconds per file.
Try it
The code topology tracer is part of the open-source Agent-Native Context reference implementation on GitHub at Proof-Company/agent-native-context under the MIT license.
To inspect the topology of any TypeScript or JavaScript file:
git clone https://github.com/Proof-Company/agent-native-context.git tools/anc
node tools/anc/bin/anc.mjs trace path/to/Component.tsx --depth 1Or run a whole-directory batch architectural audit:
node tools/anc/bin/anc.mjs trace --batch path/to/routes/Ready to see AI in action?
Proof AI handles dispatch, documentation, vision, and operations — so you can focus on the work.