AIContextBuilder

AIContextBuilder (aicb)

[NuGet Version] [NuGet Downloads] [MCP Registry] [License] [M8ven Verified]

Semantic code intelligence for AI coding agents on C#/.NET. Before AI changes your code, understand the impact.

aicb gives coding agents a Roslyn-accurate map of your C#/.NET solution. It answers the questions an agent has to get right before it edits code - who calls this, what a change reaches, which tests cover it, what dependency injection resolves, which code has side effects - and packs the code a task needs into compact, token-budgeted Markdown. It runs locally as an MCP server and CLI for Claude Code, Codex, OpenCode, Cursor and any other MCP client that starts a stdio server; a Windows desktop app adds visual context selection, analysis and editing.

Free for individuals, education and organizations below the license thresholds, with commercial licenses for larger teams. This repository hosts the releases, the documentation and the license.

Know the impact before the edit

Ask your coding agent:

What could be affected if I change ColorMixerService? Use AICB.

Or call the same tool from a terminal:

aicb call impact_of_change --sln C:/repo/App.sln --arg symbol=ColorMixerService

Abridged output from the bundled ColorMixer.SelectionLab sample:

{  "symbol": "ColorMixerService",  "resolvedKind": "type",  "directCount": 1,  "transitiveCount": 2,  "risk": "low",  "productionImpactCount": 2,  "directImpact": {    "items": [      {        "name": "DemoCompositionRoot",        "file": "ColorMixer.SelectionLab.ConsoleApp/DemoCompositionRoot.cs",        "line": 9      }    ]  }}

The desktop app's MCP Usage page records calls locally and separates guided refusals from suspected defects:

[AICB MCP Usage statistics showing calls, sessions, latency and the most-used tools]

That answer comes from the Roslyn symbol graph, not a substring search. AICB distinguishes overloads, follows interface and override relationships, understands partial types and records DI construction paths.

Build context that fits the task

AICB does more than answer individual symbol questions. It can assemble a focused, task-specific context package for an agent instead of sending an unfiltered source dump:

The focused context tools accept a token budget, so a package fits the room your agent has. The symbols you name stay in; when the budget is tight, the package becomes less detailed around them instead of being cut off in the middle of a block, and a leading note says which types, tests or siblings were left out. AICB can therefore tell you that a bundle was reduced or capped; it cannot certify that what remains is enough to solve the task correctly. Whole-document rendering can use the same budget through a pipeline profile, with an allowance for overshoot and an optional report of what was trimmed.

The result is AI-Builder-MD: structured Markdown for an LLM, containing the selected code together with symbol relationships, architecture graphs, semantic metadata and provenance. It can use the established tag notation or YAML. See the context-document guide and the task-packing tools.

Add explicit meaning with AI Tags and semantic annotations

AICB works without annotations. Where source structure and conventions are not enough, optional <ai> tags in XML documentation let a developer state the intended role of a type or method explicitly:

/// <ai///   role="service"///   layer="Application"///   responsibility="Coordinates order validation and submission."///   stability="Stable"/// />public sealed class OrderService

Annotations can describe semantics such as role, domain, architectural layer, priority, stability, responsibility and side effects. Explicit values take precedence over heuristic inference; sentinel values such as none can deliberately suppress inference for one field. AICB preserves provenance so an agent can distinguish source-derived facts, author-provided meaning and inferred hints. The AI annotation reference documents the supported forms and fields.

[AIContextBuilder desktop app with a loaded solution]

What happens after your first question

1. The first question about a solution takes the longest. You name a .sln, .slnx or .slnf; AICB loads it the way your build would and reads its C# code and its XAML/AXAML markup.
2. The questions after it are quick. Callers, implementations, tests, injection and impact come from what the first analysis learned, as a single answer or as a context document sized to your budget.
3. Your saved edits are picked up. With the shipped settings the next question brings the analysis up to date with the saved files; an explicit refresh does the same in every setting.

AICB analyzes the solution once and then answers each question from what it learned: who calls what, which types use or implement which, what the markup refers to and which code reaches outside the program. Follow-up questions therefore come back quickly, and the context tools pick and render the part of the code a task needs. This does not mean that every possible answer or runtime relationship is known in advance.

Every agent session that starts aicb mcp gets its own analysis, and the desktop app, the CLI and the server answer alike and can share configuration and saved snapshots. After you edit source files, the next refresh picks up what changed, usually without loading the solution again (force: true loads it completely). A client that gives up waiting for a long first analysis can simply ask again: the analysis finishes anyway, and a retry with the same arguments gets it from the cache.

Live sessions, snapshots and persistent codebase memory

These states serve different purposes and should not be treated as interchangeable:

remember_codebase, recall_codebase and refresh_remembered are opt-in tools: no MCP profile exposes them, so start the server with AICB_MCP_TOOLS naming them (or AICB_MCP_TOOLS=all). recall_codebase reports whether the persisted model still matches the source, payload schema and analyzer identity. It deliberately returns the recalled model even when it is stale, with metadata that tells the agent when a live re-analysis is necessary. See sessions, recall and staleness.

Answers that carry their own evidence

An AICB answer says not only what it found but how far it can be trusted. Unknown and verified absent are different answers: tools such as assert_absence return confirmed, refuted or indeterminate. Responses carry these signals whenever they apply; an agent reads them before it acts on an empty, short or apparently definitive result:

The analysis covers statically visible C# - including the C# the Razor generator compiles from .cshtml views and the code source generators add (an answer says when generated code is missing) - together with Razor, XAML and AXAML relationships. Where a relationship exists only at runtime (reflection, assembly scanning, dynamic configuration, an external consumer, a registration produced at runtime), AICB marks it as dynamic or unknown instead of inventing it, and a XAML binding whose data type is not known for certain stays unjudged rather than reported as broken.

The MCP profile controls automatic refresh. Off only discloses drift, Reactive refreshes before a reading tool answers and is the normal shipped setting, while Proactive starts analysis after saved edits settle. Automatic refresh never sees unsaved editor buffers. Staleness is also different from reference incompleteness: the first needs a refresh; the second normally needs a restore followed by a refresh (after a build, a forced one).

The question-first architecture, limits and evidence guide explains what lives in memory, how refresh and context selection work, which claims are measured, and where the published scale benchmark stands.

Where it helps

The default profile exposes every tool in this table except semantic_diff, diff_review, find_by_concurrency_risk, find_by_resource_leak, find_structural_twins, check_pattern_drift and check_doc_drift, which need the Full Select profile, and compare_public_api, which is opt-in (see Tool sets and Agent Skills).

These tools form a broader capability map rather than a flat search catalog:

The desktop app turns code-quality, security, design and architecture findings into an actionable review queue:

[AICB Insights page with prioritized code-quality, security, design and architecture findings]

AICB is most useful for non-trivial C#/.NET solutions and semantic questions that plain text search cannot answer reliably. It analyzes C#; selected XAML/AXAML relationships supplement that graph. Other programming languages are out of scope.

Multi-targeted projects are loaded once per target framework by default, while query surfaces generally deduplicate them to one logical project: each type is one entry, and the references every target makes count for it. Setting analyzePreferredTfmOnly in <Solution>.aicb.json reduces analysis and export work to the newest target-framework instance. The symbols that instance declares remain available, but a type or a fan-in edge that exists only in another target disappears, so this is a documented precision-versus-cost choice rather than a transparent optimization.

A safe agent workflow

An agent can use AICB without memorizing the tool catalog:

1. Call server_info to verify the connection and detect binary or configuration drift. Use list_skills for the complete capability map or docs() for the built-in operating manual.
2. Start an edit task with prepare_task to collect the named symbols, relevant context, covering tests and likely sibling implementations within one budget.
3. Before changing a symbol that other code names, call impact_of_change; use find_tests_for when the task bundle does not give enough test evidence.
4. Read uncertainty and completeness signals before treating an empty result as proof. Qualify ambiguous symbol names; restore and force-refresh incomplete projects.
5. Make and save the change. Then call refresh_session before get_diagnostics. Under the normal Reactive profile this is usually redundant, but it remains correct in every mode and makes the intended boundary explicit.
6. Use review_context, evaluate_change_set or verify_claim when the task makes a review or policy claim; do not infer absence merely from a short search result.
7. Finish with the repository's real build and test commands. get_diagnostics reports Roslyn compiler diagnostics, not third-party analyzer or runtime results.

For several independent read-only questions, batch reuses one session and returns one bounded response. Use measure first when the likely response size matters.

Reproducible analysis, CI and review

In GitHub Actions the gate is one step. The action at the root of this repository sets up the .NET 10 SDK, installs the published tool, restores the solution and runs aicb analyze; a failed gate fails the step with exit code 6, and the document is still written:

- uses: gregordadera/[email protected]  with:    version: 0.5.520.1    solution: App.sln    output: artifacts/context.md    fail-on: "critical>0 OR debt>120min"

The example pins both halves: @v0.5.520.1 fixes the action, version fixes the package it installs. Without version the action installs the newest published package, and @main follows every change to the action, so neither belongs in a build you depend on. A release tag can in principle be moved; the full commit SHA of that tag is the immutable form. Further inputs are dotnet-version, restore and args for other aicb analyze options; the outputs are output and exit-code. See action.yml.

Configuration precedence is axis- and surface-specific. For example, headless layer mapping can fall back to the sidecar, while headless test detection currently resolves from the database or built-in rules rather than the sidecar's test axis. The exact matrix is in the configuration guide. A running MCP session keeps the configuration it was analyzed with; after editing the sidecar, start a new analysis instead of assuming refresh_session re-reads it. Suppressions hide accepted findings from suppression-aware reading surfaces, but solution_metrics and the CLI quality gate continue to count them. A shared suppression is therefore an explicit review decision, not a way to lower the gate.

From semantic engine to human-in-the-loop workspace

The MCP server is currently AICB's most complete and operationally mature integration surface. Its 82 registered tools cover semantic navigation, change impact, dependency injection, test discovery, architecture, quality, context packing, review and session management. Profiles expose a curated 54-tool default or the 72-tool Full Select set, while sessions, staleness signals and bounded responses make the surface practical for coding agents.

The active MCP profile also selects task-oriented facets: each facet connects agent guidance, a context-template slot and the corresponding tool subset. list_skills is the runtime source of truth for which tools are exposed, which are callable, and which additional registered tools sit outside the active pool.

The Windows app complements that agent-facing surface with a visual workspace for people: solution navigation, manual context selection, detail and token controls, AI-Builder-MD preview and export, snapshots, Insights, reusable configuration and manual LLM runs.

Quality and solution-specific analysis profiles

A Quality Profile controls which insight producers run and the thresholds they use, such as method length, cyclomatic complexity and class size. It does not by itself define finding severity or the CLI quality gate.

[AICB Quality Profiles editor with producer switches and thresholds]

Each solution also has three independent analysis axes:

The desktop app presents these three pickers side by side for the selected solution. The Settings pages are the library editors; the Workspace pickers choose which library entry applies to this particular solution. A per-solution choice wins over the global default.

[AICB Workspace showing Layer Profile, Exclude Namespaces and Test Profile side by side]

Initialize the three axes

You do not have to set the three axes up by hand. When the desktop Context Builder loads a solution, AICB offers a setup for every axis that is still open and whose automatic setup you have not switched off:

• If a <SolutionName>.aicb.json beside the solution already covers the axis, it offers to take the setting from there, without asking a model.
• Otherwise, if a default model profile is set up, it asks the model once for a layer map and an exclusion list and shows you the proposal. The request has been sent by the time you see the dialog; you decide whether the proposal is applied. Test code is recognized on your machine, without a model.
• An axis can stay open: without a model profile, without detected tests, or when you decline. Choices you already made are never overwritten.

Successful GUI auto-initialization stores the chosen profiles in the local database. It does not create <SolutionName>.aicb.json automatically. Use Workspace → Profiles → Export Config to write that portable sidecar, then commit it. A later GUI can restore the supported axes from it without an LLM call; headless consumers apply the per-axis rules described in the configuration matrix. Initialize Now performs only an immediate sidecar restore - it does not call a model or analyze the solution.

An agent can guide the same setup explicitly:

1. solution_config_status reports which axes are initialized and whether their active values come from the local database, the sidecar or neither.
2. init_solution_config returns proposal material: declared namespaces for the layer map, referenced namespaces for exclusions, and detected test projects and attributes for the test profile.
3. After reviewing or adapting that proposal, apply_solution_config creates and activates the custom entries, marks the axes initialized and writes both the local configuration database and <SolutionName>.aicb.json beside the solution.
4. Commit the sidecar so the portable solution configuration travels with the repository. Each consumer applies the supported axes described above; do not assume every surface resolves every field identically. Later, check_solution_config_drift reports namespaces or test projects no longer covered by that configuration.

aicb init is a different operation: it connects a repository to the MCP server and installs the agent skill and optional symbol guard. It does not initialize these three solution axes or create <SolutionName>.aicb.json.

See profiles and solution configuration for precedence, the sidecar schema and the full initialization behavior.

Context templates and run templates

The two template types have different responsibilities:

Detail Presets, Markdown Profiles, Expansion Strategies, Compression Rules, Pipeline Profiles and Quality Profiles are reusable building blocks referenced by a context template; a run template selects that context template.

[AICB Context Templates editor with prompt, detail-level and export configuration]

Where the desktop app is heading

The desktop app is growing into a human-in-the-loop orchestration workspace: a developer selects and constrains context, inspects intermediate results, approves decisions and controls what an AI model runs next. Today it runs Manual runs; further run types that process selected nodes one by one or let a model narrow the context first are planned.

Install

Install one form per machine:

The .NET tool needs the .NET 10 SDK. Without .NET 10 it runs on the next newer .NET on the machine and needs that version's SDK. A machine that has only .NET 8 or .NET 9 cannot start it.

dotnet tool install -g aicb-roslyn-mcpaicb --version

Then register the server with your MCP client. For clients that read .mcp.json:

{  "mcpServers": {    "aicb": {      "command": "aicb",      "args": ["mcp"]    }  }}

aicb init writes this file for you; see Connect a coding agent.

Up to 0.5.465.1 the package was called AIContextBuilder. An update does not cross that rename: remove the old package first, then install the new one as above.

dotnet tool uninstall -g AIContextBuilder

Update it later with dotnet tool update -g aicb-roslyn-mcp. For a container, the repository's Dockerfile installs the same .NET tool and serves MCP over stdio. The container runs as a non-root user, and analysis writes obj/ into the mounted solution, so run it as the owner of the mount and restore the solution inside the container first:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/src" \  -v aicb-nuget:/home/aicb/.nuget/packages --entrypoint dotnet aicb restore /src/App.slndocker run --rm -i --user "$(id -u):$(id -g)" -v "$PWD:/src" \  -v aicb-nuget:/home/aicb/.nuget/packages aicb

The Dockerfile header explains why the restore has to run in the container.

If the tool reports that MSBuild could not be registered, the .NET it runs on found no SDK it can use: an SDK newer than that .NET does not count (for example a .NET 10 runtime next to only the .NET 11 SDK). Install the .NET 10 SDK; beside a .NET 10 runtime the .NET 8 and .NET 9 SDKs work as well. Or set the environment variable DOTNET_ROLL_FORWARD=LatestMajor so that the tool runs on the newest .NET - a preview .NET additionally needs DOTNET_ROLL_FORWARD_TO_PRERELEASE=1.

The Windows downloads are self-contained, but analyzing a solution still needs MSBuild from a .NET SDK or Visual Studio. The installer and the programs are code-signed (publisher: Gregor Dadera); Windows SmartScreen can still warn about a new release until it has enough download history. Every release provides SHA-256 checksums.

Connect a coding agent

Run this from the project you want the agent to work on:

aicb init

It writes .mcp.json, the MCP configuration Claude Code reads, and the aicb-csharp-context agent skill under .claude/skills/. Files you wrote yourself are not overwritten; a skill file aicb wrote earlier is brought in step with the tools the server serves (aicb skills sync does it on request). If the project uses Codex or OpenCode (a .codex/ or .opencode/ folder), it also registers the server in that client's own configuration and writes the skill to .agents/skills/, where both read skills. If it detects Claude Code, Codex or OpenCode project configuration, it also installs a symbol guard that blocks C# symbol searches by grep and redirects the agent to the semantic tool. This intentionally changes agent behavior. For Claude Code it also adds a session-start hook that keeps the aicb skill files in step with the served tools (aicb skills sync). Opt out of both with:

aicb init --hooks none

--hooks none skips only the guard and the session-start hook; the server and the skill are still set up. To wire a client whose folder does not exist yet, name it: aicb init --hooks codex or aicb init --hooks opencode.

Client-specific status:

Manual .mcp.json configuration for clients that read it:

{  "mcpServers": {    "aicb": {      "command": "aicb",      "args": ["mcp"]    }  }}

Verify the connection by asking the client to call server_info. Every analysis tool accepts an absolute .sln, .slnx or .slnf path as its session, so no separate analyze step is required. See the five-minute guide for setup, first questions and troubleshooting.

Tools

The questions an agent asks most, and the tool that answers each one:

All tools with their parameters: docs/TOOLS.md.

Tool sets and Agent Skills

Start the Local profile with aicb mcp --mcp-profile mcp-profile/local and the Full Select profile with aicb mcp --mcp-profile mcp-profile/full. Set AICB_MCP_TOOLS=all to add the opt-in tools as well. The generated tool reference documents the default set; the MCP server manual documents all 82 tools and their parameters, and alongside them sessions and staleness, profiles, pools and facets, and what aicb init writes - twelve chapters in Markdown, readable in the browser and by an agent, and also published as a PDF.

The published counts are starting points, not fixed editions. In the desktop MCP Profiles editor you can create or duplicate a profile, enable only the task facets you want, and select individual core and facet tools. Every core tool can be removed except the locked diagnostic server_info, so even a very small task-specific tools/list is possible. The server's fixed lead-in is standing agent guidance, not another selectable tool group. For headless setup, AICB_MCP_TOOLS=methods:<tool>,<tool>,... exposes exactly the named functions; class lists, lean and all are also supported. Profile and environment changes take effect at the next server start. list_skills shows the resulting in-pool and out-of-pool tools. See profiles, pools and facets.

Five Agent Skills ship in skills/:

• aicb-csharp-context routes semantic C# questions to the right tool.
• aicb-code-review checks a completed change for correctness.
• aicb-code-simplifier looks for unnecessary complexity.
• aicb-usage-check reports what this server was actually reached for.
• aicb-smoke-test runs read-only checks on your own solution, sorts the findings into HIGH, MID and LOW, and drafts reproducible issues for the maintainer. It files nothing until you confirm.

The last four are opt-in: aicb init --skills=all.

Scale, releases and compatibility

AICB is built for large solutions. On RavenDB, about 1.76 million lines of C#, the first analysis takes about 75 seconds and a repeated question about 2 seconds, at a peak of about 4.1 GB of RAM; on Serilog, about 25,000 lines, the first analysis takes about 15 seconds and a repeated question about 0.14 seconds (medians on one machine, measured 2026-11-06). The full table, with revisions, machine and method, is in the architecture and evidence guide. Follow-up questions reuse the warm analysis; saved C# edits are usually picked up incrementally, while changes to project or solution files take a full reload.

For a very large repository, a .slnf reduces what MSBuild loads and analyzePreferredTfmOnly avoids analyzing every target framework. summaryOnly, query scopes and token budgets keep responses small. The desktop load-perf.log and MCP usage_report measure your own solution locally.

The changelog records every release. server_info reports version, build and configuration drift; persisted analyses carry their schema and analyzer identity and fall back to a live analysis when they are incompatible; and the desktop app never writes to a database created by a newer version. Database migrations are one-way, so back up the database before an update if you may want to roll back. Commercial agreements can add support, response-time and version-maintenance commitments; see Support.

CLI at a glance

aicb init      Connect a project to the MCP server and install the agent skill.aicb analyze   Analyze a solution and emit context Markdown.aicb export    Re-render Markdown from an existing session database.aicb import    Import a constellation JSON.aicb list      List built-in and custom profiles and presets.aicb mcp       Start the stdio MCP server.aicb call      Invoke one MCP tool without an MCP client.

Run aicb <command> --help for options.

Local by default

• The CLI and MCP server make no outbound network connection of their own and do not modify the source code they analyze. The MSBuild logic and source generators of the analyzed solution run in the same process, so they can reach the network if that solution's own build does (see the last point).
• There is no outbound telemetry, analytics, update check, account or license server. The MCP server records its tool calls locally for usage_report and the desktop app's MCP Usage page; that log never leaves the machine.
• The desktop app can contact only an LLM endpoint you configure: for a manual run, a model-profile connection test, or first-load proposals for Layer Profile and Exclude Namespaces when those auto-init flags are armed. The endpoint may be a local model. The Details tab is also a real editor and saves a file only when you explicitly use Save.
• Opening a solution runs its MSBuild logic to resolve references, and building its compilation runs the source generators its projects reference, as in an IDE or dotnet build. Analyze only solutions you trust. AICB does not run third-party Roslyn analyzers, with one opt-in exception: get_diagnostics with runSuppressors: true runs the projects' diagnostic suppressors, as a real build does.

A small number of explicitly named tools can write configuration or an export; their tool descriptions state this. The complete threat model and private reporting route are in SECURITY.md.

License at a glance

Use is free for:

• private, hobby and educational use by natural persons,
• accredited educational institutions for teaching, learning and non-commercial research,
• organizations that reach none of these thresholds: 100 employees, EUR 10 million annual turnover, 21 developers.

The thresholds apply to your organization, not to your clients. After first reaching any one threshold, you have 90 days to agree a commercial license; use remains free during that period. The 90 days are contractual text only: AICB starts no license timer, sends no threshold or deadline data, blocks no feature and does not technically stop working when the period ends. Commercial licenses start at EUR 25 per licensed developer per month; the exact price and scope depend on the number of users, the requested support level and any agreed priority for improvement requests. A commercial agreement can include support, defined response or maintenance commitments, prioritized consideration or implementation of improvements - for example, making a generally useful analyzer handle patterns found in the customer's code more accurately. Such work improves the general AICB product; it does not create a customer-specific fork or specialize AICB to one codebase. Customer code is never collected or used for improvement automatically; examining it requires material or access deliberately provided by the customer and a separate agreement on scope and confidentiality. Exact deliverables, priorities and guarantees exist only when written into the individual agreement. Connecting AICB to MCP clients, agent harnesses, scripts, build systems and CI through its documented interfaces is permitted. Redistributing, modifying, repackaging, reselling or offering the AICB binaries as a hosted service is not. Contact [email protected]. See the plain-language guide, LICENSE.txt and the full bilingual EULA.md.

Support and continued development

AICB is under active development: the changelog records every release, and published releases appear on the Releases page.

Support follows the license:

The targets in this table are typical values an individual agreement can include; they bind only when written into the agreement, and payment alone creates no unstated SLA. Prices are in License at a glance. Contact [email protected].

Questions and feature requests are welcome in GitHub Discussions. Report bugs through GitHub Issues and include aicb --version and, for MCP problems, the output of server_info. Report security issues privately as described in SECURITY.md.

Documentation

Everything above is the short version. The three manuals below hold the full reference in 35 chapters.

• Getting started - install, connect and ask the first question
• Tool reference - generated reference for the default MCP profile
• Architecture, limits and evidence - in-memory model, refresh, context selection, static-analysis boundaries and benchmark status
• MCP server manual - the full reference in twelve Markdown chapters: connecting a client, aicb init, sessions and staleness, profiles and facets, every tool, troubleshooting
• General reference manual - the full reference in twelve Markdown chapters, with the printable PDF in the same folder
• Desktop app reference manual - the full reference in eleven Markdown chapters, with the printable PDF in the same folder
• Changelog and latest release

"AIContextBuilder" and "AIContextBuilder for .NET" are product names used by Gregor Dadera; no registration is claimed.