Lagrange.Core: a pure C# NTQQ protocol implementation for .NET bot developers

What Lagrange.Core is for, and who it is not for

Lagrange.Core is described in the README as an implementation of the NTQQ protocol written in pure C#, derived from Konata.Core. That sentence is the whole scope. It is a protocol library, not a bot framework, not a hosted service, and not a plugin host. The intended user is a developer who wants to connect a QQ account to their own program and is willing to write the connection, login and event-handling code themselves, or who is building a higher-level layer on top of it.

The repository topics list csharp, ntqq, onebot11 and qq-protocol, which matches the README's framing. Note the distinction between the library and the ecosystem around it. The README says that for web service to bot applications you should look at Lagrange.Milky, a separate project that implements the Milky protocol and is hosted in the LagrangeV2 repository. If what you actually want is an HTTP endpoint that a Python bot framework can talk to, Lagrange.Core is one layer below that need.

The README also states that the current branch is the V2 implementation and that V1 has sunset, with a pointer to the v1 branch. Anyone arriving from an older tutorial should treat the v1 branch as historical rather than a supported alternative.

How the NTQQ implementation is split across the repository

The top-level layout is unusually explicit about the architecture, and it is worth reading before you decide where to plug in. Lagrange.Core/ holds the protocol implementation itself. Lagrange.Codec/ and the Lagrange.Proto.* directories (Lagrange.Proto, Lagrange.Proto.Generator, Lagrange.Proto.CodeGen, Lagrange.Proto.Runner, Lagrange.Proto.Test, Lagrange.Proto.Benchmark) handle protobuf definitions and their code generation, which is what you would expect from a protocol library that has to encode and decode wire messages. Proto.md at the root documents that side.

Lagrange.Core.NativeAPI/ is the bridge for non-.NET callers. The README describes it as providing a C ABI-compatible wrapper for 64-bit native libraries, which is the mechanism by which a Rust, Go, Python or C++ program can use the same protocol code without reimplementing it. Lagrange.Core.NativeAPI.Test/ exists alongside it, and Lagrange.Core.Runner/ appears to be an executable entry point rather than a library surface. Lagrange.Milky/ and Lagrange.Milky.Generator/ sit in the same repository but belong to the web-service story described in the README's usage section.

The practical consequence: the data flow is your application, then the C# protocol layer, then the QQ servers over the NTQQ wire format. There is no HTTP hop inside the library. If you need one, that hop is a different project.

Installing Lagrange.Core from NuGet and making a first connection

The README gives exactly one installation instruction for .NET: add the NuGet package to your project. There is no build-from-source walkthrough in the README, and no configuration file format is documented there, so the steps below stop at the point where the README stops and hand off to the documentation site.

The package is listed on nuget.org as Lagrange.Core, and the README's instruction is to add it to the project. After that, the README directs you to the Lagrange.Core documentation under lagrangedev.github.io/Lagrange.Doc/v2/Lagrange.Core for library usage. That page is where the actual API surface, configuration and login flow are described; the README does not reproduce them, so treat the documentation as the source of truth for anything beyond the package reference.

If you are not writing C#, the same documentation site has a separate section for Lagrange.Core.NativeAPI, described in the README as a C ABI-compatible wrapper for 64-bit native libraries. The README does not list the exported function names or the calling convention, so the NativeAPI documentation page is the place to look before binding it from another language.

For the web-service route, the README points at Lagrange.Milky and its own README rather than giving commands here. The only concrete instruction it offers is to check that README for more information, so the setup steps for a Milky deployment are not in this repository's README at all.

What you should expect at this stage is a library you can reference and a documentation site to read. There is no single command in the README that starts a working bot.

Where the README leaves you on your own

The README is short, and the gaps are worth naming because they are the places a new integrator will lose time. There is no documented configuration schema, no environment variable list, no port numbers, and no example of a login sequence. The usage section has three subsections and roughly a paragraph each. Everything operational lives on the external documentation site.

The licence field is the sharper problem. The repository metadata supplied for this project does not state a licence, and the README contains only a disclaimer, which is a statement of liability rather than a grant of rights. The disclaimer says the developers disclaim association with illegal behaviour and that users are responsible for compliance with their own laws, and it explicitly says community discussion should not be read as legal advice. That is not the same as telling you what you may do with the code. If you are integrating this into anything commercial or redistributed, resolve the licence question before you write code, not after.

There is also a maintenance caveat in the release history. The most recent release listed is a nightly build dated 2025-08-02. The last push to the repository was on 2026-09-07, so the code is being touched, but the release channel shown is nightly rather than a stable tagged version. Anyone who needs pinned, versioned dependencies should check what the NuGet package actually publishes before assuming a stable line exists.

Lagrange.Core compared with OpenShamrock and Chronocat

The README's related projects table is the most useful comparison available, because it names two alternatives and states their approaches in one line each. OpenShamrock is described as based on Xposed and as a OneBot bot framework. Chronocat is described as based on Electron and as a modular Satori bot framework.

The difference is where the protocol work happens. Lagrange.Core reimplements the NTQQ protocol in C# inside your process, so there is no separate runtime to install and no injection into a QQ client. OpenShamrock's Xposed basis means it operates by hooking a running Android QQ client, which ties it to that platform and that client. Chronocat's Electron basis means a Node.js runtime sits in the picture, and it speaks Satori rather than OneBot. If your existing bot code is written against OneBot, the README's own pointer is toward Lagrange.Milky, not toward Chronocat.

None of these is strictly better. A pure-library approach means you own the process lifecycle, the reconnection logic and the storage of session state, and you get a dependency you can version. A hooking or sidecar approach means someone else owns that, at the cost of a runtime you do not control.

FAQ

The questions below are answered only from what the repository states. Where the README is silent, the answer says so rather than guessing.

Editorial conclusion

Adopt Lagrange.Core if your bot logic already lives in .NET and you want the QQ protocol as a library rather than a sidecar process, or if you need the C ABI wrapper to call it from another language. Do not adopt it if you want a ready-made HTTP or WebSocket bot service: that is Lagrange.Milky's job, and the README points you there instead. Before writing code, check the NuGet package version, read the v2 documentation pages for Lagrange.Core and Lagrange.Core.NativeAPI, and confirm the licence terms, since the repository metadata does not state one.

Frequently asked questions

Official sources

1. Issues
2. LagrangeDev/Lagrange.Core on GitHub
3. README
4. Releases