infrawise

Purpose

Infrawise provides deterministic infrastructure awareness for AI coding assistants. AI assistants can read source code, but cannot deterministically understand infrastructure: they do not know which GSIs exist, how tables are partitioned, which functions have triggered scans, or where indexes are missing, so they can only guess. Infrawise statically analyzes codebases, cloud infrastructure, and database schemas, and exposes the context to tools such as Claude Code through MCP, replacing guesswork with infrastructure-aware context.

It is itself not an AI agent framework, an infrastructure configuration tool, an observability platform, or a cloud management dashboard, but a deterministic infrastructure intelligence layer for AI-assisted development.

Main Capabilities

Infrawise includes two layers of analysis:

Infrastructure analysis (all languages): Based on AWS APIs, database schema introspection, and IaC files, independent of application code.

Code correlation analysis (TypeScript / JavaScript / Python): Uses ts-morph AST analysis to detect which functions call which tables and how they call them. Python repositories use the built-in stdlib-ast scanner (requires python3 in PATH, otherwise skipped with a warning), supporting boto3 clients and dynamodb.Table() resources, cursor.execute SQL, pymongo collections, and kafka-python/confluent-kafka producers and consumers. Language detection is automatic, and TypeScript and Python scans run only when matching files are present.

The scanner supports: AWS SDK v3/v2 for DynamoDB, pg/Prisma/Knex for PostgreSQL, mysql2/Knex for MySQL, driver/Mongoose for MongoDB, AWS SDK v3 for SQS/SNS/SSM/Secrets/Lambda, and kafkajs for Kafka topics (producers/consumers).

Workflow: scan repositories and infrastructure metadata → graph engine maps services, schemas, indexes, and query patterns → rule-based analyzers detect infrastructure and query anti-patterns → expose context through MCP → AI coding assistants query that context when generating code.

UsageMethod

Requires Node.js 22 or later.

On first run, infrawise start will: probe the environment and generate infrawise.yaml (only the first time; if there are multiple AWS profiles, it will ask which one to use); scan AWS services, databases, and codebases; write .mcp.json so the editor automatically connects on subsequent startups; open Claude Code with all 22 MCP tools ready.

After that, each analysis is cached for 24 hours. When the cache expires, the infrawise serve --stdio automatically started by the editor will refresh at the beginning of the session. File changes are detected within the session and the code graph is automatically updated.

Working with AI coding assistants:

• Claude Code (recommended): writes .mcp.json in the project root (merging with existing MCP servers) and opens Claude Code. It can also be installed as a Claude Code plugin, registering the same MCP server, and still requires infrawise.yaml in the project.
• Cursor: writes .cursor/mcp.json and opens Cursor, with the 22 tools available in the MCP panel.
• VS Code: writes .vscode/mcp.json and opens VS Code, with the tools available to Copilot agent mode through the MCP server panel.
• Any editor (no flag): writes .mcp.json and exits, pointing the editor to infrawise serve --stdio --config /path/to/infrawise.yaml as an MCP server command.
• HTTP transport (alternative): if your editor or workflow needs an HTTP MCP endpoint instead of stdio, it can be added to the editor's MCP configuration.

Every tool is marked read-only (readOnlyHint: true, openWorldHint: false), so MCP clients that honor annotations can call them directly without confirmation prompts.

Every response carries a fixed-structure dataHealth block: when the infrastructure was read and how long ago, the status of each source behind that answer, whether cdk.out has been synth'd since, and the refresh command. Every key is always present; there is no need to infer from missing fields.

Infrawise only reports, it does not adjudicate. When a question is time-sensitive, you can pass maxAgeSeconds, and the answer will tell you whether the data meets that requirement (advisory—the data is still returned and flagged). A running server rechecks the cache on every tool call, and an open session can pick up new infrawise analyze results on the next question without restarting.

Command options:

• infrawise analyze: analysis options.
• infrawise check(CI/CD): runs a fresh analysis and sets a non-zero exit code when there are blocking findings, so you can gate pipelines without an AI editor.
• infrawise serve: service options.

infrawise.yaml is generated by infrawise start(or the infrawise start --interactive bootstrap wizard) and lives at the repository root. Every service must be explicitly enabled: true—infrawise never connects to anything not listed in the configuration. Connection strings support ${ENV_VAR} substitution, so passwords do not need to be committed.

Infrawise is read-only. See the documentation for the minimum IAM policy for DynamoDB. SSO profiles require logging in before running infrawise. PostgreSQL setup (optional): create a read-only user; for Amazon RDS, allow inbound port 5432 from your local IP in the security group.

When to use it

• Let AI coding assistants know the real table structure, partition keys, sort keys, and GSIs when generating code, avoiding suggestions for indexes that already exist or .scan() on a 50-million-row table.
• Detect IaC drift, missing indexes, security gaps, and performance anti-patterns.
• In CI/CD, via infrawise check Gated pipeline.
• Two demos can simulate the real AWS API locally in Docker, at zero cost and without a real AWS account: demo/floci/ uses Floci (MIT licensed, covering all services supported by infrawise, including CloudFront, API Gateway v2, RDS, Cognito, Kinesis, ElastiCache, and MSK, with no authentication token or registration required); demo/localstack/ uses LocalStack Community Edition, covering core services. Both listen on port 4566 and must be run one at a time.

Limitations

• Code-level correlation supports TypeScript, JavaScript, and Python (Python requires python3 in PATH).
• Dynamically constructed queries may not always be statically parsed.
• Runtime tracing is not yet implemented.
• Large monorepos may need future incremental analysis optimizations.
• Projects in other languages can still get full value from the infrastructure-level analyzers, but code correlation (function-to-table mapping, N+1 patterns) currently only supports TypeScript, JavaScript, and Python.

Security and Design

• Deterministic analysis: no LLMs are used to analyze infrastructure; all extraction and analysis are deterministic (AST parsing, schema introspection, rule-based analyzers, graph correlation). LLMs only consume the generated context via MCP.
• Read-only: never writes to AWS or databases, never executes DDL.
• Local-first: everything runs on the local machine and is not sent to external servers.
• No telemetry: zero data collection.
• Credentials: uses the existing AWS credential chain; infrawise never stores them.

Note: some supply-chain security scanners may flag this package as "deceptive naming" due to the "infra" prefix; this is a false positive triggered by automated tools. The project is completely safe and independent, and is not affiliated with any commercial trademark.