# VolcanicAgenticCore

A headless, extensible agent harness for .NET, modelled on [earendil-works/pi](https://github.com/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 ships as the first one.

It also ships a C# port of [chem/pi-claude-code-provider](https://github.com/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 |
| Google Calendar (tool + connect commands) | `extensions/Volcanic.AgenticCore.Extensions.GoogleCalendar` | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`; one account per chat |
| Scheduler (scheduled prompts, watcher scripts) | `extensions/Volcanic.AgenticCore.Extensions.Scheduler` | Cronos; per-chat jobs in `<agent dir>/scheduler/jobs.json`; see [docs/telegram-bot.md](docs/telegram-bot.md#scheduling) |
| Telegram bot | `hosts/Volcanic.AgenticCore.Telegram` | Chat with the agent from Telegram; long polling, Claude Code, allow-list |
| Reference headless host | `samples/Volcanic.AgenticCore.Sample.Headless` | Prompt in, JSON events out |
| Tests | `tests/` | xunit; no test calls a paid API |

## Quick start

```bash
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-opus-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"

# the Telegram bot (see docs/telegram-bot.md)
TELEGRAM_BOT_TOKEN=123:abc TELEGRAM_ALLOWED_USER_IDS=111111111 dotnet run --project hosts/Volcanic.AgenticCore.Telegram
```

To run the bot in a container (Coolify or any Docker host): `cp .env.example .env`, fill in the two required values,
`docker compose up -d --build`. See [docs/docker.md](docs/docker.md).

Hosting it yourself:

```csharp
var services = new ServiceCollection();
services.AddAgenticCore(o =>
{
    o.DefaultModel = "anthropic/claude-opus-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](docs/architecture.md): projects, vertical slices, the agent loop and the event model.
- [Writing extensions](docs/extensions.md): tools, commands, lifecycle hooks, providers, message injection, discovery.
- [Providers and models](docs/providers.md): model keys, authentication, the built-in provider extensions.
- [Telegram bot](docs/telegram-bot.md): setup, commands, security, connection recovery.
- [Docker and Coolify](docs/docker.md): the container image, configuration, volumes, first login.
- [Google Calendar](docs/google-calendar.md): Google Cloud setup, connecting a chat, token storage, time zones.
- [Building a UI (Telegram guide)](docs/ui-integration.md): how to put a chat front end on the core.
- [Claude Code provider](docs/claude-code-provider.md): requirements, how the bridge works, limits, the doctor
  command, automatic re-login when the subscription session expires.
- 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` (or, if absent, `CLAUDE.md`) project context.

Beyond pi: the working directory may also hold `PERSONA.md` (the agent's personality) and `MEMORY.md` (memories
the agent maintains itself with `edit`/`write`); both are appended to the system prompt when present. File names
match case-insensitively.

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