Skip to content
Back to search

waku-agent

Waku Waku! Waku Agent is a local-first AI agent harness you actually own, including loop, memory, eval, all in code built to stay legible as it grows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ShenSeanChen/waku-agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ShenSeanChen/waku-agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shenseanchen--waku-agent/badge.svg)](/listings/shenseanchen--waku-agent)

HTML

<a href="/listings/shenseanchen--waku-agent"><img src="/api/listings/shenseanchen--waku-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Just want to run it:

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

It will tell you which key to set the first time. Want to **read the code** (the point of this repo) or contribute — clone it instead:

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

**Now try it.** *"Remember that Alex prefers morning meetings."* Quit. Restart. *"Book a catch-up with Alex on Friday."* → it remembers, and books 9am. Your memory is one file: `~/.waku/state.db`, the same from every folder.

**Use the model you already pay for.** Anthropic (default), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter (one key, hundreds of hosted models), OpenCode Zen, or OpenCode Go — set `WAKU_PROVIDER=`, paste the key, done. One dialect in the loop; a [~60-line adapter](waku/loop/models.py) handles the rest.

New to it? **[Getting started](docs/getting-started.md)** walks the whole setup, with a check at the end of every step.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 146 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/waku-mark-on-dark.svg">
  3. <img src="docs/brand/waku-mark-on-light.svg" alt="Waku" width="76" align="right">
  4. </picture>
  5. # waku-agent
  6. **Your own AI assistant. On your laptop. In code you can read in an afternoon.**
  7. Meet **Waku** — a local-first personal assistant that shows the four pillars behind every
  8. serious agent: **Harness · Loop · Memory · Eval/LLM-Ops**. No frameworks hiding the good parts.
  9. Built by [seanchen.io](https://seanchen.io).
  10. - **Local-first.** Your memory is one SQLite file. Open it. Read it. It's yours.
  11. - **Memory is the hero.** Semantic + episodic + procedural — with a gate that decides *whether*
  12. to remember, and a pass that decides *what* to keep.
  13. - **The loop is ~95 lines** of plain Python. Step through it.
  14. - **Watch it think.** A local dashboard lights up every message as it flows through the harness.
  15. - **Eval built in.** Deterministic tests *and* LLM-as-judge, side by side, with a release gate.
  16. ![waku-agent architecture — the whiteboard](docs/architecture-whiteboard.png)
  17. > The system-design whiteboard from the series.
  18. > Every box maps to a file — see [the architecture](docs/architecture.md).
  19. **▶ [Watch the 20-min code walkthrough](https://www.youtube.com/watch?v=rvRyBhILrls&list=PLE9hy4A7ZTmpGq7GHf5tgGFWh2277AeDR&index=42)** — the loop, the memory pillars, the evals, the Telegram gateway and the "Waku Waku" wake word, live.
  20. **[Waku Memory](https://www.waku.one)** — the same memory in Claude Code, Codex, Grok Bot and this agent: [waku.one](https://www.waku.one) · [docs](https://www.waku.one/docs)
  21. [YouTube](https://www.youtube.com/@SeanAIStories) · [X](https://x.com/ShenSeanChen) · [LinkedIn](https://linkedin.com/in/shen-sean-chen) · [Instagram](https://www.instagram.com/sean_ai_stories) · [TikTok](https://www.tiktok.com/@sean_ai_stories) · [Discord](https://discord.gg/ebbdvSCXqu) ·
  22. [哔哩哔哩](https://space.bilibili.com/479332937) · [小红书](https://www.xiaohongshu.com/user/profile/5cf02cfb0000000005014371) · [抖音](https://www.douyin.com/user/MS4wLjABAAAAWCkd62_e8q4n-S34LIL04HsYN3m03l8MFdVYZToojP8)
  23. ### [Buy me a coffee](https://buy.stripe.com/5kA176bA895ggog4gh) — it keeps this repo (and the videos) coming
  24. ## Quickstart
  25. Just want to run it:
  26. ```bash
  27. pip install waku-agent
  28. waku # talk to your Waku in the terminal
  29. waku dashboard # …or the browser cockpit → localhost:7777
  30. ```
  31. It will tell you which key to set the first time. **No paid key?** With OpenRouter, Waku
  32. uses free models by default: make a key at [openrouter.ai/keys](https://openrouter.ai/keys), then run
  33. `WAKU_PROVIDER=openrouter OPENROUTER_API_KEY=<your-key> waku`. Free models are rate-limited.
  34. Want to **read the code** (the
  35. point of this repo) or contribute — clone it instead:
  36. ```bash
  37. git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
  38. uv venv && uv pip install -e . # create the env + install the `waku` command
  39. cp .env.example .env # pick a provider, paste ONE key
  40. uv run waku # talk to your Waku in the terminal
  41. uv run waku dashboard # …or the browser cockpit → localhost:7777
  42. ```
  43. To run the evals, install the test extras first. `make eval` then runs the offline checks
  44. with no API key:
  45. ```bash
  46. uv pip install -e ".[dev,eval,hosted]"
  47. make eval
  48. ```
  49. **Now try it.** *"Remember that Alex prefers morning meetings."* Quit. Restart.
  50. *"Book a catch-up with Alex on Friday."* → it remembers, and books 9am. Your memory is one
  51. file: `~/.waku/state.db`, the same from every folder.
  52. **Use the model you already pay for.** Anthropic (default), OpenAI, Gemini, DeepSeek, MiniMax,
  53. Kimi, GLM, OpenRouter (one key, hundreds of hosted models), OpenCode Zen, or OpenCode Go —
  54. set `WAKU_PROVIDER=`, paste the key, done. One dialect in the loop;
  55. a [~60-line adapter](waku/loop/models.py) handles the rest.
  56. New to it? **[Getting started](docs/getting-started.md)** walks the whole setup, with a check
  57. at the end of every step.
  58. ## Connect Waku Memory
  59. Waku's own memory is local. **[Waku Memory](https://www.waku.one)** is the hosted memory you
  60. share across agents: save something in Claude Code, recall it here.
  61. ```bash
  62. waku plugin install waku@waku-memory # or /plugin install waku@waku-memory in the dashboard chat
  63. waku mcp login waku_memory # sign in, once, in your browser
  64. waku skill export --to claude,codex # carry Waku's skills to Claude Code and Codex too
  65. ```
  66. That installs the Waku plugin, the one Claude Code and Codex use. To connect Claude Code, Codex, Hermes or Grok Bot to the
  67. same memory, see [integrations](docs/integrations.md#share-one-memory-with-your-other-agents-waku-memory).
  68. For live data when it researches, `waku connect treg` (or `/connect treg`) signs in to your own
  69. [treg](https://treg.to) account the same way; see [integrations](docs/integrations.md#live-data-for-research-treg).
  70. ## What's inside
  71. | Pillar | In one line | Read more |
  72. |---|---|---|
  73. | **Harness** | gateways (terminal, dashboard, voice, Telegram, Discord, WhatsApp) and tools around one loop | [architecture](docs/architecture.md) |
  74. | **Loop** | ~95 lines of plain Python: reason, act, repeat, with two ways to stop | [the tour](docs/tour.md#the-loop) |
  75. | **Memory** | semantic, episodic and procedural (skills); a gate decides *whether* to remember, consolidation decides *what* to keep | [the tour](docs/tour.md#the-retrieval-gate) |
  76. | **Eval / LLM-Ops** | deterministic tests and LLM-as-judge side by side, a release gate, a trace for every turn | [evals](docs/evals.md) |
  77. **How is this different from ChatGPT or Claude Desktop?** Those are products you *use*. This is a
  78. codebase you *own*: the loop, the memory schema, the gate and the eval harness are all yours to
  79. read and change. Versus the big open-source assistants (OpenClaw, Hermes)? Same architecture,
  80. 1/100th the code.
  81. ## Docs
  82. | Read | For |
  83. |---|---|
  84. | [Getting started](docs/getting-started.md) | installing, the first run, connecting Waku Memory |
  85. | [The tour](docs/tour.md) | the dashboard, things to try, the loop, graph workflows, skills |
  86. | [Architecture](docs/architecture.md) | every box on the whiteboard, and the file behind it |
  87. | [Integrations](docs/integrations.md) | voice, Telegram, calendars, MCP servers, Waku Memory |
  88. | [Commands](docs/commands.md) | every `waku` and `make` command |
  89. | [Evals & tracing](docs/evals.md) | the two kinds of eval, the Docker tier, the release gate, traces and spend |
  90. | [Roadmap](docs/roadmap.md) | what is live, what is still a skeleton, upgrade paths |
  91. | [Whiteboards](docs/README.md#whiteboards) | the editable system-design charts from the videos |
  92. | [lab/](lab/README.md) | Waku meets other agents and models: the video experiments |
  93. | [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) | the rules, and how to send a PR |
  94. ## Community
  95. Star the repo, join the [Discord](https://discord.gg/ebbdvSCXqu), and grab a
  96. [good first issue](https://github.com/ShenSeanChen/waku-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
  97. — that link is the live list, so it's always current. Gateways, memory backends and
  98. community skills are all shaped to be first PRs; the easiest needs no Python at all
  99. (see [contributing a skill](CONTRIBUTING.md)).
  100. **Comment on an issue before you start** and it gets assigned to you, so two people
  101. never build the same thing.
  102. ## Also from me
  103. - **[launch-mvp-stripe-nextjs-supabase](https://github.com/ShenSeanChen/launch-mvp-stripe-nextjs-supabase)** — NextJS + Supabase + Stripe, everything you need to ship a SaaS.
  104. - **[AutoManus.io](https://automanus.io)** — my AI startup: a sales lead manager for made-to-order products. It embeds where conversations already happen (WhatsApp, email, web chat) to capture inbound, automate follow-ups and kill CRM busywork. Pre-seed backed by Character VC. ([AutoManus Discord](https://discord.gg/SxXATg9rSK))
  105. Code is MIT — see [LICENSE](LICENSE) — **except `hosted/`, which is Elastic
  106. License 2.0**: run it yourself, including commercially, but not as a service for
  107. others. See [hosted/LICENSE](hosted/LICENSE). `waku/`, the harness itself and
  108. everything PyPI ships, is MIT. The Waku name, mark and design system belong to
  109. AutoManus Technologies, Inc. and are not MIT — see [LICENSE-BRAND](LICENSE-BRAND). Built by [@ShenSeanChen](https://github.com/ShenSeanChen)
  110. ([YouTube](https://www.youtube.com/@SeanAIStories) · [X](https://x.com/ShenSeanChen)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.