waku-agent is a local-first, MIT-licensed Python AI agent harness for developers who want an assistant whose loop, memory and evaluation code they can read and own, rather than a hosted assistant that keeps those parts out of sight.

What it is

waku-agent is the implementation behind Waku, a local-first personal assistant that exposes the four pillars of a serious agent as ordinary, readable code: the Harness, the Loop, Memory, and Eval/LLM-Ops. The project lives in the Python ecosystem, in the AI & Machine Learning / AI Interaction & Interfaces category, and every architectural box maps to a file in the repository, documented in docs/architecture.md. The loop is roughly 95 lines of plain Python; the harness wraps it with gateways (terminal, dashboard, voice, Telegram, Discord, WhatsApp) and tools; memory is split into semantic, episodic and procedural layers; and evaluation ships in-tree rather than as an afterthought. Memory itself is a single SQLite file at .waku/state.db.

The concrete problem it solves is legibility in agent frameworks. The README states the goal directly: "No frameworks hiding the good parts." That is the thing it replaces — the black-box agent framework where the reasoning loop, the memory retention policy and the eval harness are library internals a developer can only observe through logs and configuration. waku-agent instead lets a developer step through the loop, open the memory file, and read the gate that decides whether something is remembered and the pass that decides what is kept. Provider access is abstracted into one dialect inside the loop, with a roughly 60-line adapter in waku/loop/models.py covering the rest.

Key capabilities

• Local-first memory stored as one SQLite file, .waku/state.db, which can be opened and read directly.
• Three memory types — semantic, episodic and procedural — with a gate that decides whether to remember and a pass that decides what to keep.
• A reasoning loop of about 95 lines of plain Python that a developer can step through line by line.
• A local dashboard cockpit that runs on localhost:7777 and lights up every message as it flows through the harness.
• Built-in evaluation with deterministic tests and LLM-as-judge running side by side, gated into a release check.
• Multiple gateways around one loop: terminal, dashboard, voice, Telegram, Discord and WhatsApp, including the "Waku Waku" wake word.
• Provider portability through WAKU_PROVIDER=, with Anthropic as the default plus OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, OpenCode Zen and OpenCode Go.

Who uses it and how

• Developers who want to read rather than merely configure an agent clone the repository, create the environment with uv venv, install with uv pip install -e ., copy .env.example to .env, and run the loop locally with uv run waku.
• Solo builders running a personal assistant on their own laptop point it at a model they already pay for by pasting a single key and setting WAKU_PROVIDER=.
• People who keep memory across a session demonstrate the workflow in the README: say "Remember that Alex prefers morning meetings", quit, restart, then ask to book a catch-up with Alex on Friday and get a 9am slot.
• Users who work across several agents — Claude Code, Codex, Grok Bot and Hermes are named — install waku-agent[mcp], run waku connect waku-memory, and share one memory through the hosted service at waku.one.
• Skills can be carried outward with waku skill export --to claude,codex, so the same memory and skills follow the developer between agents.

Getting started

Install from PyPI with pip install waku-agent, then run waku for the terminal assistant or waku dashboard for the browser cockpit on localhost:7777; the first run reports which key to set. Contributors and readers clone the repository instead and use uv venv, uv pip install -e ., cp .env.example .env, and uv run waku.

How it compares

The facts name no paid products this project replaces, only the agents it interoperates with: Claude Code, Codex, Grok Bot and Hermes appear as integration targets rather than competitors. Where those tools are closed, hosted surfaces, waku-agent is MIT-licensed Python whose loop, memory and eval code sit in the repository, and its cross-agent story runs through Waku Memory at waku.one instead of through a single vendor's account. The distinction is ownership and composability: the developer supplies the model key, keeps the memory file locally, and exports skills to the other agents rather than migrating into one.

When to use it — and when not to

A self-hoster must operate a Python environment built with uv, a .env holding at least one provider API key, and the local SQLite state file, and sharing memory across agents additionally depends on the hosted Waku Memory service and a browser sign-in. Anyone who wants a zero-setup managed assistant, or who will not manage an environment and keys, should pick something else, because waku-agent assumes the operator does that work. The repository is also a single-authored project built by seanchen.io, with 24 open issues at last push on 2026-09-16, so the bus factor and the breadth of supported gateways are worth weighing before depending on it in production.

pip install waku-agent
waku                                    # talk to your Waku in the terminal
waku dashboard                          # …or the browser cockpit → localhost:7777

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .          # create the env + install the `waku` command
cp .env.example .env                    # pick a provider, paste ONE key
uv run waku                             # talk to your Waku in the terminal
uv run waku dashboard                   # …or the browser cockpit → localhost:7777

pip install 'waku-agent[mcp]'           # in a checkout: uv pip install -e '.[mcp]'
waku connect waku-memory                # or /connect waku-memory in the dashboard chat
waku skill export --to claude,codex     # carry Waku's skills to Claude Code and Codex too