A headless, extensible agent harness for .NET, modelled on earendil-works/pi. It keeps the parts of pi that make it extensible and provider-agnostic and leaves out the terminal UI, so you can put any front end on top (a Telegram bot is the intended first one).

It also ships a C# port of chem/pi-claude-code-provider: an extension that drives the locally installed claude CLI on a Claude subscription, so the core can use Claude Code as a model provider without an API key.

What you get

Piece	Where	Notes
Contracts for extensions, providers, tools, sessions, UI	`src/Volcanic.AgenticCore.Abstractions`	The only assembly an extension needs to reference
Runtime (vertical slices)	`src/Volcanic.AgenticCore`	Agent loop, sessions, models, tools, extensions, commands, compaction, system prompt, hosting
Anthropic Messages API provider	`extensions/Volcanic.AgenticCore.Extensions.Anthropic`	`ANTHROPIC_API_KEY`
OpenAI-compatible provider	`extensions/Volcanic.AgenticCore.Extensions.OpenAI`	OpenAI, OpenRouter, Groq, Ollama, llama.cpp, vLLM
Claude Code (subscription) provider	`extensions/Volcanic.AgenticCore.Extensions.ClaudeCode` (+ `.Bridge`)	Spawns `claude -p`, MCP "proposal" bridge
Reference headless host	`samples/Volcanic.AgenticCore.Sample.Headless`	Prompt in, JSON events out
Tests	`tests/`	xunit; no test calls a paid API

Quick start

dotnet build
dotnet test

# run the reference host with the scripted faux provider (no keys needed)
dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --faux "Say hello"

# with a real provider
ANTHROPIC_API_KEY=sk-ant-... dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --model anthropic/claude-sonnet-4-5 "List the files here"

# with a Claude subscription through the claude CLI
dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --model claude-code/sonnet "List the files here"

Hosting it yourself:

var services = new ServiceCollection();
services.AddAgenticCore(o =>
{
    o.DefaultModel = "anthropic/claude-sonnet-4-5";
    o.AddExtension<AnthropicProviderExtension>();
    o.AddExtension<OpenAIProviderExtension>();
    o.AddExtension<ClaudeCodeProviderExtension>();
});
var factory = services.BuildServiceProvider().GetRequiredService<IAgentSessionFactory>();

await using var session = await factory.CreateAsync(new AgentSessionOptions { Cwd = "/path/to/project" });
session.Subscribe(e =>
{
    if (e is AgentSessionEvent.MessageUpdate { AssistantMessageEvent: AssistantMessageEvent.TextDelta d }) Console.Write(d.Delta);
});
await session.PromptAsync("Explain this repository");

Documentation

Architecture: projects, vertical slices, the agent loop and the event model.
Writing extensions: tools, commands, lifecycle hooks, providers, message injection, discovery.
Providers and models: model keys, authentication, the built-in provider extensions.
Building a UI (Telegram guide): how to put a chat front end on the core.
Claude Code provider: requirements, how the bridge works, limits, the doctor command.
Design spec and plan: docs/superpowers/specs/, docs/superpowers/plans/.

Layout of the agent directory

Everything the runtime writes lives under ~/.volcanic/agent (override with VOLCANIC_AGENT_DIR or AgenticCoreOptions.AgentDir):

~/.volcanic/agent/
  sessions/<scope>/<session-id>.jsonl   one JSONL file per session
  extensions/*.dll                      extension assemblies discovered at start
  auth.json                             { "anthropic": { "apiKey": "sk-..." } }
  settings.json                         { "extensions": ["path/to/Ext.dll"] }

A project can add .volcanic/extensions/*.dll and .volcanic/settings.json in its working directory.

Status

Ported from pi: agent loop with parallel tool execution, steering and follow-up queues, abort, auto-retry, overflow recovery and threshold compaction; JSONL session trees with resume and branching; the extension event model; slash commands; provider registration; API key resolution; built-in read, write, edit, bash, ls, grep, find tools; system prompt assembly with AGENTS.md/CLAUDE.md project context.

Not ported (by design): the terminal UI, themes, keybindings, renderers, skills and prompt templates, OAuth logins, image generation models, session tree navigation commands.

License: MIT. Fixtures under tests/.../ClaudeCode/Fixtures are from pi-claude-code-provider (MIT).