AIContextBuilder

AIContextBuilder (aicb)

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

Give coding agents a Roslyn-accurate map of your C#/.NET solution. aicb is a code intelligence server for C# and .NET: it answers questions about callers, implementations, dependency injection, tests, side effects and change impact, then packs the relevant code into compact Markdown for an LLM. It runs locally as an MCP server and CLI; a Windows desktop app adds visual context selection, analysis and editing.

The software is closed source. This public repository contains its documentation, license and releases. It is free for individuals, education and organizations below the license thresholds.

This page is a short tour, not the reference. It names 35 of the 54 tools an agent sees by default; the three manuals run to 35 chapters, about 39 times the length of this page.

See it answer a code question

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]

How analysis and memory work

.sln / .slnx / .slnf + C# + XAML/AXAML                 ↓        MSBuild + Roslyn semantic models                 ↓  AICB facts and consolidated semantic indexes                 ↓ individual answers or budgeted AI-Builder-MD

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.

What the model can and cannot prove

• AICB analyzes statically visible C# (including the C# the Razor generator compiles from .cshtml views) and selected Razor, XAML and AXAML relationships. Code reached only through reflection, runtime assembly scanning, dynamic configuration or an external consumer can remain invisible.
• DI analysis recognizes statically readable Microsoft-DI-shaped registrations and MEF export attributes; runtime-produced registrations are disclosed as dynamic or unknown rather than invented.
• A XAML binding is checked only where its data type is known for certain; where it is not, the binding is left unjudged rather than reported as broken.
• A reported side effect means the method reaches such an operation in its code, itself or through the methods it calls. It tells you that a method can write a file, not which file or when.
• Responses disclose stale sessions, unresolved projects and capped result sets. Read staleness, incompleteProjects, totalFound and truncated before treating an empty or short answer as proof.

How an agent should judge an answer

An AICB response is evidence together with its limits. Before acting on an empty, short or apparently definitive result, inspect the accompanying signals:

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).

AICB also distinguishes unknown from verified absent. Tools such as assert_absence return confirmed, refuted or indeterminate rather than turning missing evidence into a false negative.

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. Setting analyzePreferredTfmOnly in <Solution>.aicb.json reduces analysis and export work to the newest target-framework instance. The symbol inventory remains available, but fan-in edges that exist only in another target can disappear, 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.510.1    solution: App.sln    output: artifacts/context.md    fail-on: "critical>0 OR debt>120min"

The example pins both halves: @v0.5.510.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. These numbers describe the available product surface; they are not a published benchmark of agent outcome quality.

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

For a freshly registered solution, all three auto-init flags start enabled. The next time the desktop Context Builder loads it, AICB attempts each still-unconfigured axis. If a sidecar already covers an axis, the GUI offers to restore it without a model call. Otherwise, with a usable default model profile, one LLM request proposes layer rules and exclusions from declared and referenced namespace lists; test detection is derived locally from the analyzed projects and test attributes. The confirmation dialog decides whether the proposal is applied - the LLM request has already happened at that point. A missing model profile, no detected tests, or declining the proposal can leave an axis unconfigured. Existing choices 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]

Product direction, not a release commitment

The direction for the desktop app is a human-facing orchestration workspace: a developer selects and constrains context, inspects intermediate results, approves decisions and controls what an AI model runs next. Manual is the released run type today. Iteration is intended to process selected nodes one by one, and Preselection to let a model narrow the relevant context before the main run; both are represented in the application but are not released yet. Pipeline currently exists only as a placeholder in the data model and executes nothing.

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

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/, without overwriting existing files. 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. Opt out with:

aicb init --hooks none

--hooks none skips only the guard; the server is still registered. 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.

Tool sets and Agent Skills

This README names 35 of the 54 default tools; the references below describe all of them. Start 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 three 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.

Four 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.

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

Scale, releases and compatibility

AICB has no published hard project-count limit. Initial cost and peak memory are solution-specific and grow with loaded projects, documents, target-framework instances and graph density. The first analysis can take seconds to minutes; subsequent questions reuse the warm graph, and eligible saved-source edits use the incremental refresh path. For a very large repository, use a .slnf to reduce what MSBuild loads and optionally set analyzePreferredTfmOnly to avoid analyzing every target-framework instance. summaryOnly, query scopes and token budgets reduce response volume; they do not necessarily reduce the underlying solution analysis. The desktop load-perf.log and MCP usage_report provide local phase and latency measurements. A standardized cold/warm time and RAM benchmark on three public .NET solutions (≈ 25k, ≈ 55k and ≈ 1.8M lines of C#) is published in the architecture and evidence guide; these controls are still not a universal performance claim, but there is now a measured boundary.

Public releases currently have no declared LTS window, response-time SLA or promise that every MCP response and persisted schema remains unchanged across versions. Operational safeguards are explicit instead: the changelog records releases; server_info reports version, build and configuration drift; persisted analyses carry payload-schema and analyzer identities and fall back to a live analysis when they are incompatible; and the desktop refuses to write a database created by a newer schema. Database migrations can be one-way, so a reliable rollback means backing up before an update and using the older build with a separate or restored pre-migration database. Commercial agreements can define stronger support, response-time and version-maintenance commitments where required; 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 have no outbound network capability and do not modify the source code they analyze.
• 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 - 35 chapters, each manual 70,000 to 88,000 words, together about 39 times the length of this README.

• 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.