Agent-Context

The problem

When an AI agent is asked to edit a codebase, it has two bad choices: ingest the entire repository (which wastes thousands of tokens, causes distraction, and leads to context truncation) or guess (which leads to broken dependencies and silent failures). Codebases are structured graphs, but LLMs view them as flat text.

If an agent modifies src/auth.js, it doesn't just need to know the contents of that file. It needs to know which files rely on it (its dependents) so it doesn't break their API contracts, and which files it imports (its dependencies) so it understands its helper functions. Agent-Context extracts exactly this structural blast radius, condensing it into a tiny context snippet (~200 tokens) that is prepended to the system prompt.

How it works: step by step

• Step 1: Walk the project tree. The system recursively reads the project folder using native Node.js filesystem APIs. It automatically skips massive build outputs, temporary files, and environments like node_modules, .git, dist, and venv to keep execution under 100ms.
• Step 2: Extract imports dynamically. For every supported source file, the parser runs custom regex or AST scanners. It recognizes ESM import syntax, CommonJS require(), Python import/from, and Go imports. It resolves relative file paths into absolute workspace coordinates.
• Step 3: Build the dependency graph. It organizes the scanned files into an in-memory graph structure. Each file is a node, and each import is a directed edge pointing from the importer to the imported file.
• Step 4: Query the blast radius. When the agent targets a specific file, the system queries the graph. It retrieves both outgoing edges (what this file imports) and incoming edges (what files import this file).
• Step 5: Format the LLM context. It outputs a structured text block specifying the exact imports and dependents of the file. Prepending this block to the agent's prompt alerts the agent to the downstream effects of its changes.

Select a file and generate context...

Context Snip: what the agent reads

### GRAPHIFY STRUCTURAL CONTEXT FOR [src/auth.js]
- Dependencies (what this file uses): src/db.js, src/utils/crypto.js
- Dependents (what relies on this file): src/routes/login.js, src/routes/signup.js, src/middleware/guard.js

Rule: If you modify this file, be aware of the blast radius affecting its dependents.
### END GRAPHIFY CONTEXT

Supported Languages

The parser has zero native compiler dependencies and extracts import chains fast:

How to run it

git clone https://github.com/shubham0086/Agent-Context
cd Agent-Context
npm install

# Run graph discovery demo
node demo/graph.js .

# Query the blast radius for Graphify.js
node demo/blast-radius.js src/Graphify.js .

The API

import { GraphifyClient } from 'agent-context';

// 1. Initialize client pointing to project root
const client = new GraphifyClient('./my-project');

// 2. Discover files and parse imports
await client.buildGraph();

// 3. Get in-memory graph details
const summary = client.getGraphSummary();
console.log(`Discovered ${summary.nodeCount} files`);

// 4. Query neighborhood (dependents & dependencies)
const neighbors = client.queryNeighbors('src/auth.js');

// 5. Generate formatted prompt block
const promptSnippet = client.getContextString('src/auth.js');

Security and MCP Sandbox Applications

In production environments, Large Language Models (LLMs) execute filesystem tools via the Model Context Protocol (MCP). However, exposing file paths blindly exposes host filesystems to path traversal exploits (e.g., CVE-2025-53110) or symlink bypasses (e.g., CVE-2025-53109).

Agent-Context mitigates these vulnerabilities by validating paths during graph tree queries. Every target file and discovered dependency path is normalized using native absolute path resolution, then verified against an allowlisted workspace root sandbox. Any file paths trying to escape the root workspace context are blocked before the dependency graph is updated.

Where this fits

Agent-Context solves the context boundary step of the autonomy ladder. It implements Pattern 04 (GraphDB for Agent Context) in Agentic Patterns. The core orchestration layer AgentKernel uses this client before launching coder subagents to target code changes without bloating the system prompt.

Honest framing

This uses token scanning rather than full AST generation or TS compiler services. This makes it extremely fast (runs in milliseconds) and allows it to process multiple languages with zero dependencies. However, it does not trace dynamic runtime imports or complex alias paths (like TSConfig paths) unless they are explicitly mapped in the workspace configuration. For 95% of standard code structure operations, the static token scan is perfectly sufficient.