Thanks for wanting to poke the machine responsibly. BotNexus is an experimental C#/.NET platform for orchestrating LLM agents, tools, channels, and memory. This guide covers everything you need to build from source, make a change, and open a pull request that CI (and your fellow humans) will accept.
For a higher-level tour of the project, start with the README. For deeper topics, see the Documentation section below.
| Requirement | Version | Notes |
|---|---|---|
| .NET SDK | 10.0.204 or later | Pinned in global.json with rollForward: latestMinor. Earlier SDKs (including .NET 9) are not supported. |
| PowerShell | 7+ (pwsh) |
Required for the repo helper and validation scripts under scripts/. |
| Git | Recent | Worktrees are used heavily (see Development Workflow). |
Verify your SDK:
dotnet --version
# Must output 10.0.204 or laterDownload the .NET 10 SDK: https://dotnet.microsoft.com/download/dotnet/10.0
BotNexus runs on Windows and Linux. All code, tests, scripts, and docs must be portable across both — CI runs on both and developer machines vary.
Clone the repo and restore tools and packages:
git clone https://github.com/sytone/botnexus.git
cd botnexus
dotnet tool restore # installs pinned tools from dotnet-tools.json (dotnet-affected, etc.)
dotnet restore # restores NuGet packages (Central Package Management)
dotnet build dirs.projRun the CLI directly from source:
dotnet run --project src/gateway/BotNexus.Cli -- init
dotnet run --project src/gateway/BotNexus.Cli -- provider setup
dotnet run --project src/gateway/BotNexus.Cli -- gateway startOr run the gateway in the foreground:
dotnet run --project src/gateway/BotNexus.Cli -- serveThe WebUI and REST API serve at http://localhost:5005. For a fuller walkthrough
see the Developer Setup guide.
Install the versioned git hooks (the #1602 core.bare guard runs on push; there
is deliberately no pre-commit hook - see Validation):
pwsh scripts/repo/install-hooks.ps1All file modifications and commits happen in a dedicated worktree — never
directly on main. Local main stays clean and aligned to origin/main.
# Create a worktree + branch off up-to-date main
git worktree add ../botnexus-wt/<issue-number>-<slug> -b <type>/<issue-number>-<slug>
cd ../botnexus-wt/<issue-number>-<slug>Branch naming: <type>/<issue-number>-<short-slug> — for example
fix/64-history-first-load or feat/128-gateway-plugins.
Ordinary PRs target main. For a planned change with at least two dependent,
independently reviewable layers, GitHub native stacked PRs are permitted: the
bottom branch targets main and each upper branch targets the branch below it.
Do not stack unrelated work merely because it was developed at the same time.
See PR and Commit Conventions.
Planning lives in GitHub Issues on sytone/botnexus (not in docs/planning/).
Use gh issue list / gh issue view <number> to find work.
All commit messages use Conventional Commits:
<type>(<scope>): <short summary>
- Types:
feat,fix,refactor,docs,test,chore,ci,perf,build - Scope: the area affected — e.g.
cli,gateway,scripts,domain,extensions,tools - Keep the summary lowercase, imperative mood, no trailing period
- Commit in small logical batches — one feature, one fix, one refactor per commit
- Multi-line bodies are encouraged for non-trivial changes: explain what and why, not how
Examples:
feat(cli): add serve command with gateway and probe subcommands
fix(gateway): prevent duplicate session writes on concurrent requests
refactor(scripts): simplify start-gateway.ps1 to delegate to CLI
docs(agents): add conventional commit rules for PRs
chore(deps): bump Microsoft.Extensions.* to 10.0.1
- PR titles must also follow Conventional Commits — GitHub uses the PR title as the squash-merge commit message, so a non-conforming title produces a non-conforming history entry.
- Reference the issue number in the PR body (e.g.
Closes #128), not the title. - When work is complete, close the issue with a comment referencing the PR or commit.
When writing or reviewing documentation, follow the shared Documentation standards. They define the three audiences, plain-language guidance, evidence requirements, and agent review boundaries. Use Documentation grooming for the existing checks and PR and commit conventions for the submission format. Apply the standard incrementally and respect document ownership headers.
BotNexus enforces a few hard conventions. The full detail lives in
AGENTS.md and the per-area AGENTS.md files under src/.
Full code standards - XML comment requirements, naming, dependency boundaries, and testing conventions - are in docs/development/code-standards.md.
- Cross-platform paths. Production code injects
IFileSystem(System.IO.Abstractions) and usesfileSystem.Path.Combine(...)rather than hardcoded separators or/tmp/. UsePath.Combine()in tests and static helpers. Never hardcodeC:\...or/tmp/.... - Value objects use Vogen.
New identifiers are
[ValueObject<T>]partial structs inBotNexus.Domain.Primitiveswith aValidatepartial method. Do not add implicit operators — callers use.Valueand.From(...)explicitly. Seesrc/domain/AGENTS.md. - XML docs on public API. All public methods and properties need a
<summary>explaining why the member exists and the context a caller needs — not a restatement of the signature. - Warnings are errors. Fix all compiler warnings during development;
TreatWarningsAsErrors=trueis enforced centrally. Do not silence warnings with#pragma warning disable,#nullable disable, or null-forgiving!. - No dead code, no
[Obsolete]. This codebase has no external consumers — delete unused code and update call sites in the same commit instead of deprecating.
MSBuild conventions are centralized: TargetFramework, Nullable, and
ImplicitUsings come from Directory.Build.props, and
all package versions live in
Directory.Packages.props (Central Package
Management — no Version on individual PackageReferences).
botnexus/
├── src/
│ ├── agent/ agent core + provider adapters (Copilot, OpenAI, Anthropic, ...)
│ ├── domain/ BotNexus.Domain — domain model and Vogen value objects
│ ├── extensions/ channels (SignalR, Telegram, ServiceBus, TUI), tools, MCP, skills
│ ├── gateway/ gateway, CLI, cron, sessions, prompts, memory, tools, webhooks
│ └── persistence/ BotNexus.Persistence.Sqlite
├── tests/ unit, integration, architecture, scenario, component, e2e tests
├── docs/ published documentation site (MkDocs Material)
├── scripts/ build, test, repo, and local development scripts
├── examples/ experiments and sample integrations
└── tools/ supporting utilities
The root traversal project is dirs.proj. Many directories carry
their own AGENTS.md with area-specific conventions — read the one closest to the
code you are changing.
All tests must pass before a change is complete. Prefer Test-Driven Development: write the failing test first, then implement until it passes.
Run only the tests impacted by your change (plus the Architecture and Scenario safety-net suites):
scripts/repo/test-impacted.ps1This uses dotnet-affected to select affected test projects and always adds the
*.Architecture.Tests and *.Scenarios.Tests projects as a safety net. See
Running Impacted Tests for parameters
(-From, -Configuration, -All, -NoBuild, -DryRun) and the Windows
testhost firewall pre-authorization details.
Architecture fitness functions live in
tests/architecture/BotNexus.Architecture.Tests/ and structurally enforce the
Vogen and scenario-suite conventions. Channel-agnostic acceptance tests live under
tests/scenarios/ — read tests/scenarios/AGENTS.md before adding one. Every
Blazor .razor component requires a corresponding bUnit component test.
The authoritative pre-push gate is:
scripts/repo/Invoke-PreCommitValidation.ps1The canonical command was renamed from scripts/repo/Validate-PreCommit.ps1 to
scripts/repo/Invoke-PreCommitValidation.ps1. This is a breaking path change: the old
file is removed, with no alias or wrapper. Update external scripts and local skill
references before invoking validation. This repository change does not migrate those
external consumers. Parameters, mode selection, approval checks and exit behavior stay
the same. The policy identity changes, so pre-migration receipts must not be reused.
The paired offline fixtures are now Test-PreCommitValidation.ps1 and
Test-AzureBuildTestArtifacts.ps1 under scripts/repo/.
Mode is selected via BOTNEXUS_VALIDATION_MODE (local or remote); the
operational default is remote (#2158). Local validation spawns real gateway
processes that outlive their parent and steal the live gateway's scheduled jobs, so
it is opt-in and must not be run on a host with a live gateway. Select it explicitly
only when remote infrastructure is genuinely unavailable:
$env:BOTNEXUS_VALIDATION_MODE = 'local'
scripts/repo/Invoke-PreCommitValidation.ps1Install the versioned git hooks (the #1602 core.bare guard on push). There is
deliberately no pre-commit hook - commit-time local validation is banned:
pwsh scripts/repo/install-hooks.ps1Do not use --no-verify on commits containing code changes. A hand-run
dotnet build is encouraged before validating - it costs seconds and starts no
test host - but it is not itself the validation gate. Do not run dotnet test
or test-impacted.ps1 on a host with a live gateway: the test host leaks
gateway processes that outlive it (#2158). Test execution is remote.
Documentation-only changes skip the test gate. If your change touches nothing
but *.md, docs/**, or mkdocs.yml, build the docs instead - it takes about
twenty seconds and catches dead links:
npm ci # first time only
npm run docs:buildThis is what deploy-docs.yml runs. ci-build-test.yml already lists docs/**
and **/*.md under paths-ignore, so a docs-only PR never triggers the test
workflow. A change touching docs and code is a code change - validate it fully.
The docs/development/ and docs/internals/ trees carry the in-depth material:
| Topic | Page |
|---|---|
| Agent execution model | docs/development/agent-execution.md |
| Message flow | docs/development/message-flow.md |
| Prompt pipeline | docs/development/prompt-pipeline.md |
| LLM request lifecycle | docs/development/llm-request-lifecycle.md |
| Gateway crash diagnostics | docs/development/gateway-crash-diagnostics.md |
| WebUI connection issues | docs/development/webui-connection.md |
| Session stores | docs/development/session-stores.md |
| Workspace and memory | docs/development/workspace-and-memory.md |
| DDD patterns | docs/development/ddd-patterns.md |
| Agent core (internals) | docs/internals/02-agent-core.md |
| Coding agent (internals) | docs/internals/03-coding-agent.md |
| Tool development (internals) | docs/internals/09-tool-development.md |
| Tool security (internals) | docs/internals/tool-security.md |
- Docs site: https://sytone.github.io/botnexus/
- Getting Started — pick the right setup path
- Developer Setup — build, run, test from source
- Configuration Guide
- CLI Reference
- Architecture Overview
- Extension Development
Please review SECURITY.md for how to report vulnerabilities
responsibly. Do not open a public issue for a security problem.
Welcome aboard. Build something interesting, keep main clean, and let the build
warnings stay errors.