banner.png

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 ProviderPlugin hook interface. Built-ins: openai-compatible (default), minimax (M3 / M2.x with reasoning_split and continuous_usage_stats), moonshot (kimi-k2.7-code with prompt_cache_key, kimi-k3 with reasoning_effort), and lmstudio (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 / a2a tool behaviour replaces it.
  • MCP support — client plus server manager, integrated via the mcp unified 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 persistent auto_approve row all live here. No more hand-edited config.json.
  • Session memory — long-term SQLite memory/memory.sqlite lives 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 / SIGILL that flush messages.json to messages.json.crash and recover the transcript on the next launch. Drop-last-message recovery is automatic.
  • Tool registry — BashTool, SkillTool, MemoryTool, SerperSearchTool, and a demos/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 ThinkingLevel enum (Default / None / Low / High / Max) that the provider plugins translate into the right provider-specific field. kimi-k3 gets reasoning_effort; MiniMax-M3 gets reasoning.split with disabled for None; LM Studio strips both fields silently.
  • Approval handling — AgentConfig::auto_approve is now std::optional<bool>, with runtime controls set_auto_approve, clear_session_approvals, clear_persisted_approvals, and set_remember_approvals. The AgentSink::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 under src/library/, src/api/, src/core/, src/mcp/, and src/tools/ must not call std::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::cout or std::cerr corrupts 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 ProviderPlugin interface was redesigned at v0.5 — older ad-hoc provider code was retired and the new hook interface lives in include/daedalus/ProviderPlugin.h. The public way to remove a model is Agent::delete_model(), which passes through to SettingsStore::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.md and 22-file docs/ 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."