
daedalus: A C++23 Agent Library You Can Actually Embed
Last week I wrote about icarus, Lee Stripp's C++23 CLI coding agent. The thing I kept striking in that post was the line: "icarus is a thin, opinionated shell over a general-purpose agent library." That library is daedalus, and if you thought icarus was interesting, daedalus is the one to actually read.
It's a single static library — libdaedalus.a — that you link into any C++23 host and drive one or more Agent instances through a narrow public API. No Python interpreter. No Node. No service to spawn. Just #include <daedalus.h> and a CMakeLists.txt line pointing at find_package(daedalus).
The repo is at gitlab.com/leestripp/daedalus. MIT-licensed, 20 tags, currently at v0.9.6 as of 2 August 2026, with a 75 KB CHANGELOG.md that doubles as a design journal.
The Whole API in One Class
The first thing that surprised me is how small the public surface is. Stripp has been ruthless about not leaking implementation types. The library exposes:
- One class:
daedalus::Agent— the agent loop. - One sink interface:
daedalus::AgentSink— the only way the library talks to you. - One config struct:
daedalus::AgentConfig— what to do, where to write, which model. - One settings store:
daedalus::SettingsStore— SQLite-backed, with a stable C++ API. - No internal headers are leaked through
include/daedalus/. PIMPL is used where the implementation is hairy.
The sink is the bit that matters most. Your host implements it, hands a shared_ptr to the Agent constructor, and observes the agent's life as a sequence of virtual calls. The embedding.md reference lists about fifteen callbacks, most of them with sensible defaults: on_assistant_delta(text), on_tool_call(name, call_id, args), on_tool_result(name, call_id, result), on_state_change(from, to), on_log(level, msg), request_command_approval(cmd), and a structured on_error(ErrorKind, msg, will_retry) channel that classifies failures as Network / Timeout / RateLimited / Auth / ClientError / ServerError / Parsed / ApiError / Internal.
The minimum viable host is absurdly small. Here is the canonical "embed example" straight from docs/embedding.md:
#include <daedalus.h>
#include <iostream>
class StdoutSink : public daedalus::AgentSink {
public:
void on_assistant_delta(std::string_view text) noexcept override {
std::cout << text << std::flush;
}
bool request_command_approval(std::string_view cmd) override {
std::cerr << "Approve: " << cmd << " [y/N] " << std::flush;
char c{}; std::cin.get(c);
std::cin.ignore(1 << 16, '\n');
return c == 'y' || c == 'Y';
}
};
int main() {
daedalus::AgentConfig cfg;
cfg.project_root = ".";
cfg.daedalus_home = daedalus::Paths::global().user_root();
cfg.session_id = "demo-session";
auto sink = std::make_shared<StdoutSink>();
daedalus::Agent agent(std::move(cfg), sink);
agent.initialize();
std::string input;
while (std::getline(std::cin, input) && input != "/quit") {
agent.submit_user_message(std::move(input));
agent.run_one_turn(); // one user msg ⇋ loop ⇋ stop/cancel/error
std::cout << '\n';
}
}
Link with -ldaedalus -lcurl -lpthread -lssl -lcrypto -lpng -lpoppler-cpp. That's it. Single binary, no IPC, no subprocesses, no JSON-RPC plumbing.
What's Actually Inside
Behind that tiny API is a real, full-fat agent runtime. The full feature surface:
- Provider plugins via a
ProviderPluginhook interface. Built-ins:openai-compatible(default),minimax(M3 / M2.x withreasoning_splitandcontinuous_usage_stats),moonshot(kimi-k2.7-code withprompt_cache_key, kimi-k3 withreasoning_effort), andlmstudio(auth-less loopback, discovery-driven). Auto-detected from the host name. Hosts can register their own plugins without forking the library. - A2A client and server — a full implementation of the Agent2Agent Protocol over HTTP+JSON. The legacy ACP v1 sub-library was removed at v0.5.0 and
--a2a-agent/a2atool behaviour replaces it. - MCP support — client plus server manager, integrated via the
mcpunified tool (one tool that routes to any configured server:mcp(server, tool, args)). - SQLite settings store with an XDG-compliant path layout (
$XDG_DATA_HOME/daedalus/daedalus.db). Models, providers, MCP servers, kv settings, and the persistentauto_approverow all live here. No more hand-editedconfig.json. - Session memory — long-term SQLite
memory/memory.sqlitelives under the per-project.daedalus/tree, never in the XDG user tier. - Crash resilience — the library installs async-signal-safe handlers for
SIGSEGV/SIGABRT/SIGFPE/SIGILLthat flushmessages.jsontomessages.json.crashand recover the transcript on the next launch. Drop-last-message recovery is automatic. - Tool registry —
BashTool,SkillTool,MemoryTool,SerperSearchTool, and ademos/example-tools/tree of optional references (GitTool,NetworkTool,SearchTool,PdfTool,SystemInfoTool,BackgroundTool). - Context compression — hosts can call
Agent::compress_context()themselves (the 70/30 split + LLM summary) instead of waiting for the 90%-of-window threshold. Safe to invoke mid-turn via a thread-safe flag. - Thinking-level controls — a
ThinkingLevelenum (Default / None / Low / High / Max) that the provider plugins translate into the right provider-specific field.kimi-k3getsreasoning_effort;MiniMax-M3getsreasoning.splitwithdisabledforNone; LM Studio strips both fields silently. - Approval handling —
AgentConfig::auto_approveis nowstd::optional<bool>, with runtime controlsset_auto_approve,clear_session_approvals,clear_persisted_approvals, andset_remember_approvals. TheAgentSink::on_command_auto_approved(cmd, ApprovalSource)callback tells hosts whenever a command was approved by an auto-mode cache or persisted-approvals cache instead of by the user.
The Library Design Rules
The docs/library_design.md document is unusually opinionated. There's really only one rule, and it's enforced:
Rule 1 — No stdio inside
libdaedalus.a. Code undersrc/library/,src/api/,src/core/,src/mcp/, andsrc/tools/must not callstd::cout,std::cerr,std::cin,printf,fprintf,fputs, or write directly to stdout/stderr/stderr fds.
The reasoning is laid out in the same doc and it is the kind of thing every C++ library should write down:
"A host that builds a TUI (ncurses, blessed, ratatui, raw terminal mode, vim-style status line, …) needs total control of stdio. Library code that reaches for
std::coutorstd::cerrcorrupts the terminal, blocks the host's input-handling thread, eats escape sequences the host is parsing, breaks mouse / keystroke routing."
The library may use exactly two output channels: the AgentSink callbacks and the core/Logger.h macros (LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR). The logger writes to per-project log files under .daedalus/[agent]/logs/ and never touches stdout. Anything that demonstrably needs to reach the child process's actual stdout (e.g. the BackgroundTool re-routing a child's stdio) is allowed to write to those fds — but those are its fds, not the host's.
The rule is verified two ways: a static grep -rn 'std::cout\|std::cerr\|std::cin' src/library src/api src/mcp over the source tree should return nothing outside comments, and a runtime test that overrides std::cout and std::cerr with a counting stringbuf, runs a full agent lifecycle, and asserts the counter is zero. Both checks were green as of 16 July 2026.
This is the kind of discipline that makes the library actually embeddable. Don't underestimate it.
Five Worked Demos
The demos/ directory is the on-ramp. Each demo is a self-contained executable that exercises the public API only — no reaching into internals. The README's table:
| Demo | Default | What it shows |
|---|---|---|
daedalus-cli |
ON | Console REPL: read user input, drive one run_one_turn(), render streamed tokens. The canonical "embed" example. |
daedalus-manager |
ON | 3-Agent orchestration (planner ⇨ actor ⇨ validator) from one host loop. |
daedalus-subagent |
ON | Parent agent spawns a child agent via a host-registered tool. |
daedalus-webui |
OFF | HTTP + SSE web host: one agent per browser session, streamed live. |
daedalus-settings-tui |
ON | FTXUI TUI for editing the SQLite SettingsStore — providers, models, MCP, agent options. Pure settings CRUD, no agent loop. |
Every demo follows the same shape: a CMakeLists.txt that declares the executable and links daedalus, a main.cpp (60–180 lines) doing the host loop, and a <helper>.h for any non-trivial sinks / parsers / HTML. The FTXUI tab sources from daedalus-settings-tui/ are reused by the icarus CLI so its /settings command opens the TUI in-process. If you want to start a new host, copy the closest demo and trim.
Build & Test It
System deps on Ubuntu (tested on 24.04+ / 26.04):
sudo apt install -y cmake clang libcurl4-gnutls-dev libssl-dev \
libsqlite3-dev libpng-dev libpoppler-cpp-dev
OmniNet (C++23 HTTP / WebSocket / DNS / TCP / TLS) is fetched from GitLab on the first build; nlohmann_json v3.11+ and sqlite-vec v0.1.6+ are pulled in transitively. doctest 2.5+ is fetched for the unit tests, FTXUI v7.0.1 for the settings-tui demo.
cmake -S . -B build
cmake --build build -j$(nproc)
cmake --install build # lands in ~/.local by default
Then either run ./build/demos/daedalus-cli/daedalus-cli for an interactive prompt, or point the CLI demo at a project:
./build/demos/daedalus-cli/daedalus-cli /path/to/project
Tests are two layers. Unit tests in tests/test_*.cpp use a tiny inline TEST() / EXPECT() macro pair — no external framework needed, no doctest boilerplate. They run hermetically and are expected to all pass on every CI run:
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
Integration tests live in /workspace/Testing/ and hit a real MiniMax API. They return exit code 77 (skip) by default behind the live-llm label; set DAEDALUS_RUN_LIVE_LLM_TESTS=1 to enable them. They're the right tool to verify provider plugins, MCP transport, and the SSE parser against the messy realities of the actual web.
Static analysis is optional but recommended. Several clang-tidy targets ship in the CMake — daedalus_static_analysis, daedalus_clang_tidy_lib, daedalus_clang_tidy_tests, daedalus_clang_tidy_demos, daedalus_clang_tidy_tools — and compile_commands.json is emitted automatically. cppcheck is not enabled (the library targets don't have unresolved poppler symbols any more).
Honest Caveats
I don't want to oversell. The library is at v0.9.6, which the README is — admittedly — underselling as "Current tag: 0.7.5 — stable library." The 0.9.x series is the API-settling series. The README's "no more hand-edited config.json" line is real, but the v0.4 → v0.5 storage migration is a one-time cost you'll pay if you have pre-0.5 data lying around (daedalus-cli --migrate-data-apply does it). The new SettingsStore deliberately supervises its own state and exposes a flat KV model with a kv_settings table, so old JSON files don't get silently rewritten.
There are also some smaller truths worth saying out loud:
- The
demos/daedalus-webui/is OFF by default, so a default build is UI-only on the console side. Enable it with-DDAEDALUS_DEMO_WEBUI=ON. - The
ProviderPlugininterface was redesigned at v0.5 — older ad-hoc provider code was retired and the new hook interface lives ininclude/daedalus/ProviderPlugin.h. The public way to remove a model isAgent::delete_model(), which passes through toSettingsStore::delete_model()(idempotent on unknown names). - The A2A implementation focuses on the HTTP+JSON/REST transport only — JSON-RPC 2.0, gRPC, push notifications, and authenticated extended agent cards are all documented as future work and not yet implemented.
- The library is the opposite of a thin wrapper — its 75 KB
CHANGELOG.mdand 22-filedocs/tree are more thorough than most published C++ projects I've read this year.
Why I'm Watching It
The whole AI-agent ecosystem is converging on a small handful of patterns: tool loops, token streaming, context-window management, MCP, A2A. daedalus is one of very few libraries that has implemented all of those in a single language-mature, embeddable, no-runtime form, with first-class docs and a test suite that isn't a single main() and a prayer.
If you're a C++ developer who has been working around the absence of an agent library because the only options were Python or Node, this is the one to look at. And if you already use icarus as your day-to-day CLI, the next time you wonder why a particular tool call behaves the way it does, the answer is now in a single git clone away.
git clone https://gitlab.com/leestripp/daedalus.git
cd daedalus
cmake -S . -B build && cmake --build build -j$(nproc)
./build/demos/daedalus-cli/daedalus-cli --help
It will not solve your prompt-cache headaches. But it might solve "I need to put a coding agent inside my own C++ application, and I don't want to shell out."