A modular, extensible AI agent execution platform built in C#/.NET. BotNexus enables running multiple AI agents concurrently, each powered by configurable LLM providers, receiving messages from multiple channels, and executing tools dynamically.
| Guide | Audience |
|---|---|
| Getting Started → | First-time users — clone to running in minutes |
| Developer Guide → | Developers and agents — build, test, run locally |
| API Reference → | REST and SignalR endpoint documentation |
| Architecture → | System design, components, and extension points |
| Observability → | Distributed tracing, logging, and local Jaeger setup |
| Sub-Agent Spawning → | Background sub-agent delegation, tools, and configuration |
- Multi-Agent — Run multiple agents with independent configs (model, provider, system prompt, tools)
- Multi-Channel — Discord, Slack, Telegram, SignalR, REST API, and Azure Service Bus
- Multi-Provider — GitHub Copilot (26 models: Claude, GPT, GPT-5, Gemini, Grok via model-aware routing), OpenAI, Anthropic, Azure OpenAI
- Model-Aware Routing — Each model defines its API format (Anthropic Messages, OpenAI Completions, OpenAI Responses); requests route to the correct handler automatically
- Extensible — Dynamic assembly loading with folder-based extension system
- Skills System — Modular knowledge packages for agents (git workflows, coding standards, best practices)
- MCP Support — Model Context Protocol servers (stdio and SSE transports)
- MCP Invoke — Expose BotNexus agents as MCP servers to other tools
- Session Persistence — Conversation history persisted to disk (JSONL format)
- Conversations — Named, persistent conversation contexts across sessions with cross-agent access
- Observable — Correlation IDs, health checks, real-time activity stream via WebUI
- CLI Tool —
botnexuscommand-line tool for config, agents, providers, doctor, and Gateway lifecycle - Diagnostics — 13 health checkups across 6 categories with auto-fix support (
botnexus doctor) - Hot Reload — Edit
config.jsonand changes apply live (agents, providers, cron) — no restart needed - REST API — Agent CRUD, session management, skills, system status endpoints
- WebUI — Real-time chat with model selector, tool visibility toggle, and command palette (
/help,/reset,/status,/models) - Mobile WebUI — Responsive Blazor WASM mobile client for on-the-go agent access
- Tool Control — Disable tools per agent via
DisallowedToolsconfig - Skill Control — Disable skills per agent via
DisabledSkillsconfig (supports wildcards) - Loop Detection — Configurable safeguards against infinite tool call loops (
MaxRepeatedToolCalls) - Model Logging — Actual model used logged per provider call for debugging and observability
- Config Audit — Config changes backed up to
.bak, OAuth token operations logged - Agent Templates — Auto-bootstrapped workspace with SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md
- Heartbeat System — Dedicated
HeartbeatAction+HeartbeatTriggerwith cron scheduling for background agent tasks - Memory System — Structured agent memory with search, retrieval, and lifecycle management
- Audio Transcription — Audio input transcription extension
- Web Tools — Built-in web search and fetch tools
- Process & Exec Tools — Shell command execution with approval gating
The BotNexus Gateway is the central hub for multi-agent orchestration. It provides:
- REST API — Agents, sessions, chat, configuration endpoints
- SignalR — Real-time streaming with agents
- Multi-agent routing — Route messages to different agents by ID
- Session persistence — Durable conversation history (JSONL)
- Hot reload — Edit
config.jsonand changes apply live (no restart) - Health checks — Built-in
/healthendpoint for monitoring - Blazor WebUI — Interactive chat and configuration interface
# Build the solution
dotnet build BotNexus.slnx
# Run the Gateway (port 5005 by default)
# Option 1: PowerShell dev script (build + test + run)
.\scripts\dev-loop.ps1
# Option 2: Start gateway only
.\scripts\start-gateway.ps1
# Option 3: Direct dotnet command
dotnet run --project src/gateway/BotNexus.Gateway.ApiOpen http://localhost:5005 for the real-time chat dashboard. See the Developer Guide for the full workflow.
Edit ~/.botnexus/config.json to configure:
{
"gateway": {
"listenUrl": "http://localhost:5005",
"defaultAgentId": "assistant",
"sessionsDirectory": "workspace/sessions"
},
"agents": {
"assistant": {
"provider": "copilot",
"model": "gpt-4.1",
"systemPromptFile": "prompts/assistant.txt",
"isolationStrategy": "in-process",
"enabled": true
}
},
"providers": {
"copilot": {
"apiKey": "auth:copilot",
"baseUrl": "https://api.githubcopilot.com",
"defaultModel": "gpt-4.1"
}
}
}| Endpoint | Method | Purpose |
|---|---|---|
/health |
GET | Health check status |
/api/agents |
GET | List all agents |
/api/agents |
POST | Register a new agent |
/api/agents/{id} |
GET | Get agent details |
/api/agents/{id}/sessions/{sid}/status |
GET | Check agent instance status |
/api/chat |
POST | Send a message to an agent |
/api/chat/steer |
POST | Inject steering message into active run |
/api/chat/follow-up |
POST | Queue follow-up for next run |
/api/sessions |
GET | List sessions |
/api/sessions/{id} |
GET | Get session history |
/api/sessions/{id} |
DELETE | Delete a session |
/api/conversations |
GET/POST | List or create named conversation contexts |
/hub/gateway |
SignalR Hub | Real-time streaming with agents |
Connect to http://localhost:5005/hub/gateway with a SignalR client.
Hub methods:
SubscribeAll()SendMessage(agentId, channelType, content)Steer(agentId, sessionId, content)Abort(agentId, sessionId)ResetSession(agentId, sessionId)
Server events:
ConnectedMessageStart,ThinkingDelta,ContentDelta,ToolStart,ToolEnd,MessageEnd,Error
┌─────────────────────────────────────────────────────────┐
│ Gateway.Api (ASP.NET) │
│ [REST Controllers] [SignalR Hub] [WebUI Files] │
└────────────┬──────────────────────────────┬─────────────┘
│ │
Message Bus Session Persistence
│ │
┌────────────▼──────────────────────────────▼─────────────┐
│ BotNexus.Gateway │
│ [Agent Router] [Hot Reload] [Channel Manager] │
└────────────┬────────────────────────────────────────────┘
│
Extension Points
│
┌────────┼────────┐
│ │ │
[IIsolationStrategy] [IChannelAdapter] [ISessionStore]
(in-process/sandbox) (Discord/Slack) (File/Memory/Redis)
👉 Read src/gateway/README.md for detailed architecture, configuration, and development guide.
BotNexus includes a command-line tool for managing configuration, agents, providers, diagnostics, and the Gateway lifecycle:
# Install as a .NET tool
dotnet tool install --global --add-source ./src/BotNexus.Cli/bin/Release/net10.0 botnexus
# Or run directly from source
dotnet run --project src/BotNexus.Cli -- doctorKey commands: botnexus init, botnexus validate, botnexus agent list/add/remove, botnexus config get/set, botnexus doctor, botnexus status, botnexus start, botnexus stop. Run botnexus --help for the full list.
On first run, BotNexus creates ~/.botnexus/ with a default config.json. Edit this file to configure providers, channels, and agents:
~/.botnexus/
├── config.json # Your configuration (primary)
├── extensions/ # Channel, provider, and tool plugins
├── tokens/ # OAuth token storage
├── workspace/sessions/ # Conversation history
└── logs/
{
"gateway": {
"listenUrl": "http://localhost:5005",
"defaultAgentId": "assistant"
},
"agents": {
"assistant": {
"provider": "copilot",
"model": "gpt-4.1",
"isolationStrategy": "in-process",
"enabled": true
}
},
"providers": {
"copilot": {
"apiKey": "auth:copilot",
"baseUrl": "https://api.githubcopilot.com",
"defaultModel": "gpt-4.1"
}
}
}| Component | Description |
|---|---|
| Gateway | Main orchestrator — message bus, agent routing, channel management, hot reload |
| Gateway.Api | ASP.NET host — REST controllers, SignalR hub, Blazor WebUI |
| Gateway.Dispatching | Message dispatch pipeline between channels and agent runners |
| Gateway.Prompts | Prompt pipeline — template rendering, context injection, mustache support |
| Gateway.Conversations | Named persistent conversation contexts with cross-agent access |
| Gateway.Sessions | JSONL-based conversation persistence |
| Agent | Per-agent processing loop with context building and tool execution |
| Core | 14 interface contracts, configuration, extension loading |
| Cli | botnexus command-line tool — config, agents, providers, doctor, Gateway lifecycle |
| Cron | Scheduled task engine — cron expressions, HeartbeatAction, HeartbeatTrigger |
| Memory | Structured agent memory with search, retrieval, and lifecycle management |
| Tools | Built-in tool implementations shared across agents |
| Diagnostics | 13 health checkups with auto-fix, used by CLI doctor and /api/doctor endpoint |
| Channels | Discord, Slack, Telegram, SignalR, Service Bus implementations |
| Providers | Copilot (OAuth, model-aware routing), OpenAI, Anthropic LLM backends |
| WebUI | Real-time activity monitoring dashboard (desktop + mobile Blazor WASM) |
BotNexus uses a Pi-style, model-aware provider architecture:
- ModelDefinition — Each model explicitly declares its API format (Anthropic Messages, OpenAI Completions, OpenAI Responses)
- IApiFormatHandler — Separate handler per API format (3 handlers in Copilot provider for 26 models)
- Automatic Routing — Request model determines handler; no provider name needed
- Copilot Models — 26 pre-registered models: Claude (6), GPT-4/4o/o1/o3 (8), GPT-5 (7), Gemini (4), Grok (1)
Example:
{
"Agents": {
"analyst": {
"Model": "gpt-4o", // Routes to openai-completions handler
"Provider": "copilot"
},
"researcher": {
"Model": "gpt-5.4", // Routes to openai-responses handler
"Provider": "copilot"
},
"coder": {
"Model": "claude-opus-4.6", // Routes to anthropic-messages handler
"Provider": "copilot"
}
}
}See Architecture Guide and Configuration Guide for details.
- Getting Started ← Start here
- Developer Guide — Build, test, and run locally
- API Reference — REST and SignalR endpoints
- Architecture Overview — System design and components
- Configuration Guide — Complete configuration reference
- Extension Development — Build custom providers, channels, and tools
- Workspace & Memory — Agent workspace and memory system
- Cron & Scheduling — Scheduled tasks and heartbeats
- Skills Guide — Modular knowledge packages for agents
Top-level folders in this repository:
| Folder | Purpose |
|---|---|
.copilot/ |
Copilot configuration and custom instructions. |
.github/ |
GitHub Actions CI/CD workflows, Copilot agent definitions, and issue templates. |
.squad/ |
Team charters, decisions, and shared working context for role-based agents. |
artifacts/ |
Generated outputs and captured run artifacts. |
docs/ |
User, API, architecture, and planning documentation. |
examples/ |
Runnable examples and proofs-of-concept. Includes examples/teams-proxy (Azure Bot + Service Bus Teams bridge) and examples/BotNexus.CodingAgent. |
projects/ |
Project incubator area for active experiments before they are promoted to src/ or examples/. |
scripts/ |
Development and operational automation scripts. |
src/ |
Production source code (domain, agent, gateway, extensions). |
tests/ |
Unit, integration, component, and end-to-end test suites. |
tools/ |
Tooling utilities and support assets used by development workflows. |
worktrees/ |
Git worktree root — active feature/fix branches. Never commit directly here. |
src/
├── domain/
│ └── BotNexus.Domain # Domain primitives (value objects, smart enums)
├── agent/
│ ├── BotNexus.Agent.Core # Agent loop, tool execution, streaming
│ ├── BotNexus.Agent.Providers.Core # Provider abstractions, LLM client, model registry
│ ├── BotNexus.Agent.Providers.Copilot # GitHub Copilot provider (OAuth, model-aware routing)
│ ├── BotNexus.Agent.Providers.OpenAI # OpenAI provider
│ ├── BotNexus.Agent.Providers.Anthropic # Anthropic provider
│ └── BotNexus.Agent.Providers.OpenAICompat # OpenAI-compatible provider (custom endpoints)
├── gateway/
│ ├── BotNexus.Gateway # Main host, agent router, hot reload
│ ├── BotNexus.Gateway.Api # REST API, middleware, SignalR hub, Blazor host
│ ├── BotNexus.Gateway.Abstractions # Gateway contracts and interfaces
│ ├── BotNexus.Gateway.Contracts # Shared DTOs
│ ├── BotNexus.Gateway.Channels # Channel adapter base classes
│ ├── BotNexus.Gateway.Conversations # Named persistent conversation contexts
│ ├── BotNexus.Gateway.Dispatching # Message dispatch pipeline
│ ├── BotNexus.Gateway.Prompts # Prompt pipeline (template rendering, mustache)
│ ├── BotNexus.Gateway.Sessions # Session persistence (JSONL)
│ ├── BotNexus.Cron # Cron scheduling engine (HeartbeatAction, HeartbeatTrigger)
│ ├── BotNexus.Memory # Agent memory: search, retrieval, lifecycle
│ ├── BotNexus.Tools # Built-in tool implementations
│ └── BotNexus.Cli # CLI tool (botnexus command)
├── extensions/
│ ├── BotNexus.Extensions.Channels.SignalR # SignalR channel (WebUI real-time)
│ ├── BotNexus.Extensions.Channels.SignalR.BlazorClient # Blazor WebUI (desktop)
│ ├── BotNexus.Extensions.Channels.SignalR.BlazorClient.Core # Shared Blazor service layer
│ ├── BotNexus.Extensions.Channels.SignalR.BlazorClient.Mobile # Blazor WASM mobile client
│ ├── BotNexus.Extensions.Channels.Telegram # Telegram Bot channel
│ ├── BotNexus.Extensions.Channels.ServiceBus # Azure Service Bus channel
│ ├── BotNexus.Extensions.Channels.Tui # Terminal UI channel
│ ├── BotNexus.Extensions.Mcp # MCP server support (stdio + SSE)
│ ├── BotNexus.Extensions.McpInvoke # Expose agents as MCP servers
│ ├── BotNexus.Extensions.Skills # Modular knowledge packages
│ ├── BotNexus.Extensions.ExecTool # Shell exec tool with approval gating
│ ├── BotNexus.Extensions.ProcessTool # Background process management tool
│ ├── BotNexus.Extensions.WebTools # Web search and fetch tools
│ └── BotNexus.Extensions.AudioTranscription # Audio input transcription
examples/ # Runnable examples and proof-of-concept projects
tests/ # Unit, integration, and E2E tests
BotNexus uses a layered configuration model:
- Code defaults — Built-in constants
- appsettings.json — Project defaults
- ~/.botnexus/config.json — User configuration (primary)
- Environment variables — Override any setting via
BotNexus__Path__To__Property
Set BOTNEXUS_HOME environment variable to override the ~/.botnexus/ location.
See LICENSE for details.