Write with intent. Koan makes it real.

Koan is an opinionated .NET meta-framework for agentic, data-driven applications.

A package reference expresses intent. AddKoan() composes the referenced capabilities. Entities give application code a consistent vocabulary for persistence, APIs, background work, and intelligence.

Your application describes its business. Koan owns composition, provider selection, infrastructure lifecycle, and the explanation of what was selected.

Declare what your application knows. Declare how the world reaches it.

public sealed class Todo : Entity<Todo>
{
    public string Title { get; set; } = "";
    public bool Done { get; set; }
}

[Route("api/todos")]
public sealed class TodosController : EntityController<Todo>;

With Koan’s web foundation and SQLite connector, this becomes a persisted, queryable HTTP API at /api/todos.

Make one.

You need the .NET 10 SDK.

dotnet new install Sylin.Koan.Templates
dotnet new koan-web -o TodoApi
cd TodoApi
dotnet run -- --urls http://localhost:5000

In another shell, create a Todo and read it back:

Invoke-RestMethod -Method Post -Uri http://localhost:5000/api/todos `
  -ContentType application/json -Body '{"title":"Ship something useful"}'

Invoke-RestMethod http://localhost:5000/api/todos

Stop the application, start it again, and repeat the GET. Your Todo is still there.

The template references Koan’s application bundle and SQLite connector. Its host is ordinary ASP.NET Core with one composition call:

using Koan.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddKoan();

var app = builder.Build();
await app.RunAsync();

Application code works directly with the Entity:

var todo = await new Todo { Title = "Ship it" }.Save();

var open = await Todo.Query(item => !item.Done);

Use ordinary ASP.NET Core controllers and services for application-specific behavior.

Already have an application? Bring Koan into an existing ASP.NET Core application.

Let the idea grow.

Today it is a local SQLite API. Tomorrow it might need semantic search, tenant isolation, background processing, files, or an agent interface.

Add what the application needs. The code keeps saying Todo.

For example, after composing Entity embedding integration, an embedding runtime, and a vector store, semantic search uses the Entity’s vocabulary:

var matches = await Todo.Ai.Search(
    "something quick to finish before lunch",
    search => search.Top(5));

The semantic-search capability carries the complete setup, indexing declaration, model constraints, and working recipe.

Provider choices remain meaningful. Query support, durability, transactions, and operating requirements follow the selected capability and implementation.

Agent, meet Todo.

Add Koan’s MCP package:

dotnet add package Sylin.Koan.Mcp

Opt the existing Entity into an agent-visible surface:

+using Koan.Mcp;
+
+[McpEntity(Name = "Todo", Description = "Work the team intends to finish")]
 public sealed class Todo : Entity<Todo>

Koan projects applicable Entity operations into MCP tools and resources. Generated operations use the application’s configured Entity access rules and persistence policies.

Choose the client transport and access policy through the MCP recipe. Local STDIO and remote Streamable HTTP are supported; the HTTP transport requires explicit enablement.

The declaration selects the model to expose. Authorization determines what a caller may do.

Agents can also help you build it.

Koan supplies workflows for building, extending, repairing, explaining, and upgrading applications.

Start with a business outcome:

Add semantic search over task titles. Keep the existing HTTP routes.

Or request an explanation:

Why was this data provider selected?

The workflows direct agents to inspect the application, retrieve the relevant capability guidance, use exact packages and APIs, and verify the resulting behavior.

The same documentation serves developers and agents:

Business outcome
  → capability and constraints
  → exact packages and deployment choices
  → working recipe
  → observable proof

The capability tree routes from broad requirements to actionable guidance. Recipes provide installation, configuration, code, and verification. Installed packages carry their own version-matched documentation, and the coding skill includes dated capability snapshots for restricted or offline environments.

Read-only explanation has its own workflow, allowing an agent to inspect evidence and explain behavior before changes are made.

Explore Koan’s agent workflows.

Shared expertise can become an application foundation.

Koan’s bundle and module model provides building blocks for teams maintaining an internal platform.

Platform engineers can package approved capabilities and compatible versions. Domain engineers can contribute shared contracts, lifecycle policies, and business operations. Feature developers can build upon those decisions.

An organization’s purchasing foundation, for example, could bring together its persistence choices, tenancy conventions, diagnostics, and purchasing policies.

Those decisions become versioned, reviewable, and testable.

For teams with varied experience, this gives new contributors established patterns, experienced developers reusable foundations, architects executable conventions, and coding agents a consistent application vocabulary.

Bundles select capabilities. Modules and application boundaries enforce rules. The organization owns its shared contracts, extension points, and compatibility promises.

Understand what the application composed.

When behavior comes from referenced capabilities, its origin should be inspectable.

For the application above:

Invoke-RestMethod http://localhost:5000/.well-known/Koan/facts

Build-time composition and runtime selections answer different questions. Together with behavior checks, they help developers and agents understand what the application actually does.

Choose a foundation appropriate to your application.

Koan fits business APIs, internal tools, knowledge applications, integration services, operational portals, and product backends. Its composition model also supports organizations maintaining shared foundations across several teams.

Capabilities and connectors have individual maturity assessments. Use the evaluated product surface when choosing a production baseline.

Continue with:

• Build your first application
• Explore capabilities
• Find a working recipe
• Compose a whole solution
• Run complete applications
• Understand the architecture
• Find exact packages
• Navigate documentation as an agent

Koan is licensed under Apache 2.0.

Contributing · Support · Security · Code of Conduct