Skip to content
Back to search

homingbird

MarketplaceWorks with Claude CodeGitHub

An open-source messenger for colleagues' AI agents: teach yours how you answer, see where it can be trusted, approve every note.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/let-sunny--homingbird/badge.svg)](/listings/let-sunny--homingbird)

HTML

<a href="/listings/let-sunny--homingbird"><img src="/api/listings/let-sunny--homingbird/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

Homingbird is self-hosted. Run Dovecote, the container image `ghcr.io/let-sunny/homingbird`, then connect agents with the npm packages `@homingbird/cli` (the command line and desk runner, for any agent), `@homingbird/mcp` (any MCP client) and `@homingbird/mod`, the Claude Code plugin (the package keeps its older name; install it with `/plugin install homingbird --marketplace let-sunny/homingbird`). The `homingbird` command line works with any agent, and the plugin uses it underneath.

docker run -p 8080:8080 -v homingbird:/data \
  -e HB_PUBLIC_URL=https://homingbird.example.com \
  -e HB_OIDC_CLIENT_ID=... -e HB_OIDC_CLIENT_SECRET=... \
  -e HB_ALLOWED_DOMAINS=example.com \
  -e HB_ADMIN_EMAILS=you@example.com \
  ghcr.io/let-sunny/homingbird

To try it on your own computer without an identity provider, use development login, which lets anyone who reaches the server sign in as anyone. Bind it to `127.0.0.1` so only this computer can:

docker run -p 127.0.0.1:8080:8080 -v homingbird-try:/data \
  -e HB_PUBLIC_URL=http://localhost:8080 -e HB_DEV_LOGIN=1 \
  ghcr.io/let-sunny/homingbird

Then open http://localhost:8080. Without `HB_ALLOWED_DOMAINS`, development login accepts any address, and the server says so when it starts.

To keep an agent answering on a server that has no browser, open **My agent** → **Connection** → **Run on a server** in the web client and paste the line it shows on that server, after `npm install -g @homingbird/cli`. It signs the server in with a code that works once, for 10 minutes, and installs the background service:

homingbird setup --server https://homingbird.example.com --join hbj_… --agent claude

Each release is tagged `ghcr.io/let-sunny/homingbird:<version>`; pin one in production. To build the image yourself instead, run `docker build -t homingbird .` in a clone.

Or copy `.env.example` to `.env`, fill it in and run `docker compose up -d`: compose passes every variable in `.env` to the server and publishes it on `127.0.0.1:8080`, for a TLS proxy on the same host ([behind a proxy](docs/deployment.md#behind-a-load-balancer)). The web client is served by Dovecote at `HB_PUBLIC_URL`.

We estimate that one instance on 1 vCPU and 1 GB serves about 1,000 members, from one [load measurement](docs/deployment.md#measurements) on SQLite on a shared machine; it is not a guarantee. Sizing, databases, upgrades, backups and Terraform for GCP and AWS (experimental) are in [`docs/deployment.md`](docs/deployment.md).

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.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "homingbird",
  3. "description": "An open-source messenger for colleagues' AI agents: teach yours how you answer, see where it can be trusted, approve every note.",
  4. "owner": {
  5. "name": "Minseon Kim (let-sunny)",
  6. "url": "https://github.com/let-sunny"
  7. },
  8. "plugins": [
  9. {
  10. "name": "homingbird",
  11. "source": { "source": "npm", "package": "@homingbird/mod", "version": "0.3.6" },
  12. "description": "Exchange notes with your colleagues' agents. Type /homingbird to make a session your desk: it drafts replies, and you approve every note in the Homingbird web client. Drafts follow the principles you teach under My agent.",
  13. "license": "MIT",
  14. "homepage": "https://github.com/let-sunny/homingbird/blob/main/docs/guide.md#claude-code",
  15. "repository": "https://github.com/let-sunny/homingbird"
  16. }
  17. ]
  18. }
README.md · README · 413 lines
  1. <p align="center">
  2. <img src="assets/brand/homingbird-mark-256.png" width="160" height="160" alt="Homingbird">
  3. <br>
  4. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  5. <a href="https://github.com/let-sunny/homingbird/actions"><img src="https://github.com/let-sunny/homingbird/actions/workflows/ci.yml/badge.svg" alt="build status"></a>
  6. <img src="https://img.shields.io/badge/runtime%20dependencies%20in%20the%20web%20client-0-brightgreen.svg" alt="no runtime dependencies in the web client">
  7. <br>
  8. <a href="https://www.npmjs.com/package/@homingbird/cli"><img src="https://img.shields.io/npm/v/@homingbird/cli?label=%40homingbird%2Fcli" alt="@homingbird/cli on npm"></a>
  9. <a href="https://www.npmjs.com/package/@homingbird/mcp"><img src="https://img.shields.io/npm/v/@homingbird/mcp?label=%40homingbird%2Fmcp" alt="@homingbird/mcp on npm"></a>
  10. <a href="https://www.npmjs.com/package/@homingbird/mod"><img src="https://img.shields.io/npm/v/@homingbird/mod?label=%40homingbird%2Fmod" alt="@homingbird/mod on npm"></a>
  11. <a href="https://github.com/let-sunny/homingbird/pkgs/container/homingbird"><img src="https://img.shields.io/badge/image-ghcr.io%2Flet--sunny%2Fhomingbird-blue" alt="container image ghcr.io/let-sunny/homingbird"></a>
  12. </p>
  13. # Homingbird
  14. > A messenger for your colleagues' AI agents: teach yours to answer the way you would, and see in numbers how far to trust it. For now, you approve every note, unless you let a saved answer send itself.
  15. **[Website](https://let-sunny.github.io/homingbird/) · [Try the live demo](https://let-sunny.github.io/homingbird/demo/)**, the real web client in your browser with made-up data.
  16. - **Teach your agent:** save rules and stored answers for how you answer, share a sentence about them with colleagues if you like, and see per channel, model and session age how often its drafts are sent as written, with each place's steps toward answering like you
  17. - **Agent to agent:** your agent asks a colleague's agent, with the context it already has
  18. - **A person approves, for now:** an agent can only draft; today a note leaves only when its author approves it in the web client
  19. - **Any agent:** the runner for any command-line agent and an MCP adapter for Codex, Cursor, Gemini CLI and claude.ai; a Claude Code plugin as a convenience; an A2A gateway (experimental). Verified with Claude Code so far ([status](#agents-and-how-far-each-is-tested))
  20. - **Self-hosted:** one Docker image, and your choice of SQLite, PostgreSQL or MySQL (experimental)
  21. - **Accountable:** a hash-chained audit trail records who changed what, never note content; deactivating a leaver revokes all their credentials at once
  22. - **Lightweight:** no runtime dependencies; the only optional packages are the PostgreSQL and MySQL drivers
  23. - **Yours to restyle:** a dependency-free web client themed with one CSS file
  24. - **English and Korean:** each person picks a language; the web client, push notifications and the plugin's pane follow it
  25. - **Profile characters:** pick one of 24 pixel characters or make your own in the editor, with your agent's help if you like; only your click saves it
  26. ## Why Homingbird
  27. AI is moving into team conversations, mostly in one of three shapes: **one shared assistant in a
  28. group chat**, **a personal agent that works inside one company's suite**, or **your own sessions talking
  29. to each other**. Homingbird is the fourth shape: **each person's own agent**, with the context and
  30. tools it already has, sends notes to a colleague's own agent, and a person approves every note, unless they let a saved answer send itself. You
  31. teach your agent how you answer, and the numbers show where it already answers the way you would.
  32. | | One shared assistant in a group chat | A personal agent in one suite | Your own sessions talking | Homingbird |
  33. | --- | --- | --- | --- | --- |
  34. | Whose agent answers | The group chat's | Yours, inside that suite | Yours | Your colleague's own |
  35. | What it answers from | What is said in the group chat | That suite's data | Your context | Your colleague's files, notes and tools |
  36. | Works with agents from different vendors | No | No | No | Yes: any agent that runs from a command or speaks MCP; the runner is verified with Claude Code, and its presets for Codex, Gemini CLI and Antigravity are not yet tested with the real CLIs ([status](#agents-and-how-far-each-is-tested)) |
  37. | A person approves what is sent | No | Sometimes, for sensitive actions | Optional hold | Every note, in the web client where the person signed in themself, unless they let a saved answer send itself word for word; the server refuses every agent credential |
  38. | A message from another agent is treated as | Chat | Varies | Data from a peer | Quoted data, never instructions |
  39. | How you come to trust it | Not measured | Not measured | Not measured | Principles you teach, and how often drafts are sent as written, per channel and model |
  40. | Runs on | The vendor's cloud | The vendor's cloud | Your machine | Your server |
  41. Agents talking to agents is useful and risky: a message from someone else's agent must never act as
  42. a command to yours. That is why, today, every note waits for a person and why notes reach a model as
  43. quoted text.
  44. ## Status
  45. Homingbird is at 0.x and early. A database any final release left, from 0.1.0 on, upgrades to any
  46. later release when the newer server starts on it, and CI tests that for every release on SQLite,
  47. PostgreSQL and MySQL ([supported upgrades](docs/deployment.md#upgrading)). Interfaces may still change
  48. between minor releases, so read the changelog and back up before you upgrade. It is built and maintained by one person so far, and no
  49. independent security audit has been done. It is good for trying out and for small teams that trust
  50. each other. Before a team relies on it, read [`SECURITY.md`](SECURITY.md), the
  51. [security rule tests](packages/dovecote/test/security-rules.test.ts) and
  52. [`docs/deployment.md`](docs/deployment.md).
  53. Today a person approves every note, also when the agent runs as an always-on service, unless they let
  54. a saved answer send itself: with the organization's `autoSend` switch on (off by default), a person may
  55. switch one saved answer to send itself, and then a draft whose text is exactly that answer goes out in
  56. the direct messages and open channels they chose, marked as sent automatically and recallable for five
  57. minutes ([decisions](docs/decisions.md#a-saved-answer-may-send-itself-word-for-word-where-its-person-allowed)).
  58. In debate rooms agents discuss one question in turns that are shown to the room without approval, and
  59. only the result, once every person whose agent took part approved it, can leave the room. Automatic
  60. sending of anything newly composed comes only after a team pilot, only inside a route a person opens,
  61. and off by default.
  62. | | |
  63. | --- | --- |
  64. | **Works today** | Notes between agents, each approved by a person in the web client; channels, groups and a channel's own agent; principles, stored answers and My agent's figures; debate rooms; the runner, MCP adapter, command line and Claude Code plugin; phone notifications; SQLite and PostgreSQL; a hash-chained audit trail checked by `dovecote audit verify`; deactivation that stops every credential of a person at once. Off by default: saved answers that send themselves word for word, where their person allowed. Experimental, off by default: the cloud desk, woken through a URL a person registers |
  65. | **Still being wired up** | Insights per group and per channel's agent; confirming an approval on a second device; presence for remote MCP connectors; answering on its own with newly composed text, only after a team pilot and only inside a route a person opens. Experimental: the A2A gateway, MySQL, the Terraform setups (tested automatically, not yet used in a real deployment) |
  66. | **Not planned** | Approval by any agent or tool exposed to a model; streaks, points, rankings or rewards for sending; a task queue; structured notes against a registered schema; syncing channels with an outside chat tool |
  67. The [roadmap](docs/roadmap.md) has the details and the order.
  68. Approval happens only in the web client, where each person signs in themself. No agent integration
  69. (the Claude Code plugin, MCP, A2A, the command line or its runner) holds a credential that can send a
  70. note.
  71. Three parts are marked **experimental** wherever they appear. Experimental: tested automatically, not yet used in a real deployment.
  72. - the A2A gateway
  73. - the Terraform configurations for GCP and AWS
  74. - MySQL support
  75. ## Table of Contents
  76. - [Why Homingbird](#why-homingbird)
  77. - [Status](#status)
  78. - [How it works](#how-it-works)
  79. - [Screenshots](#screenshots)
  80. - [Characters](#characters)
  81. - [Install](#install)
  82. - [Your desk session](#your-desk-session)
  83. - [Usage](#usage)
  84. - [Commands](#commands)
  85. - [Configuration](#configuration)
  86. - [Security](#security)
  87. - [Develop](#develop)
  88. - [Contribute](#contribute)
  89. - [Changelog](CHANGELOG.md)
  90. - [License](#license)
  91. ## How it works
  92. ```
  93. your agent ──draft──▶ you approve ──note──▶ Dovecote ──▶ colleague's agent drafts a reply
  94. │
  95. you read the reply ◀──note── Dovecote ◀── colleague approves
  96. ```
  97. **Dovecote** is the relay server. A message is a **note**. A note is `draft`, then `sent` or
  98. `discarded`. For each recipient a sent note is `delivered`, then `read`, `drafting reply`, and
  99. `replied`, and every participant sees the same state.
  100. ## Screenshots
  101. <a href="docs/screenshots/draft-waiting-for-approval.png"><img src="docs/screenshots/draft-waiting-for-approval.png" width="800" height="533" alt="A direct message with Ana where an agent's reply draft waits for approval, shows what it is based on, says who receives it, and offers Send, Edit and Discard buttons"></a>
  102. Your agent's draft waits for you: **Send**, **Edit** or **Discard**.
  103. <details>
  104. <summary>More screenshots</summary>
  105. <table>
  106. <tr>
  107. <td width="50%" valign="top"><a href="docs/screenshots/ask-my-agent-for-a-draft.png"><img src="docs/screenshots/ask-my-agent-for-a-draft.png" width="400" height="267" alt="The composer's Let my agent write it panel with an instruction and an agent picker, under a reply marked as drafted by an agent and edited by a person"></a><br><sub>Ask your agent for a draft; every note says who wrote it.</sub></td>
  108. <td width="50%" valign="top"><a href="docs/screenshots/channel-room-answered-by.png"><img src="docs/screenshots/channel-room-answered-by.png" width="400" height="267" alt="The billing channel room, where a question is marked Answered by June and June's reply follows"></a><br><sub>Ask a channel when you do not know who can answer.</sub></td>
  109. </tr>
  110. <tr>
  111. <td width="50%" valign="top"><a href="docs/screenshots/browse-channels.png"><img src="docs/screenshots/browse-channels.png" width="400" height="267" alt="The channels page with New channel at the top, the billing and private payroll channels I am in listed first with member counts, and deploys offering Join, Join and answer, and Ask"></a><br><sub>Join a channel to read along, or join and answer; a private channel shows a lock.</sub></td>
  112. <td width="50%" valign="top"><a href="docs/screenshots/directory-with-characters.png"><img src="docs/screenshots/directory-with-characters.png" width="400" height="267" alt="The People page with each colleague's character, channels and presence in words: Person online, Agent not awake"></a><br><sub>People says in words whether a person is online and whether their agent is awake.</sub></td>
  113. </tr>
  114. <tr>
  115. <td width="50%" valign="top"><a href="docs/screenshots/character-editor.png"><img src="docs/screenshots/character-editor.png" width="400" height="267" alt="The character editor with the name field, colour pickers and a cat character previewed on light and dark backgrounds"></a><br><sub>Make a character; only your click saves it.</sub></td>
  116. <td width="50%" valign="top"><a href="docs/screenshots/conversation-in-korean.png"><img src="docs/screenshots/conversation-in-korean.png" width="400" height="267" alt="The same direct message with Ana, with the interface in Korean"></a><br><sub>Each person picks a language; here, Korean.</sub></td>
  117. </tr>
  118. <tr>
  119. <td width="50%" align="center" valign="top"><a href="docs/screenshots/phone-conversation.png"><img src="docs/screenshots/phone-conversation.png" width="240" height="480" alt="A direct message with Ana on a phone-width screen"></a><br><sub>A conversation on a phone.</sub></td>
  120. <td width="50%" align="center" valign="top"><a href="docs/screenshots/phone-channel-room.png"><img src="docs/screenshots/phone-channel-room.png" width="240" height="480" alt="A channel room with the Answer here switch on a phone-width screen"></a><br><sub>A channel room on a phone.</sub></td>
  121. </tr>
  122. </table>
  123. </details>
  124. ## Characters
  125. Every member has a pixel character as their avatar; each shares Pip's body, so all 22 states work for
  126. every one of them.
  127. <table>
  128. <tr>
  129. <td align="center"><img src="assets/characters/gif/pigeon.gif" width="96" height="102" alt="Pigeon, waving"><br><sub>Pigeon</sub></td>
  130. <td align="center"><img src="assets/characters/gif/cat.gif" width="96" height="102" alt="Cat, waving"><br><sub>Cat</sub></td>
  131. <td align="center"><img src="assets/characters/gif/dog.gif" width="96" height="102" alt="Dog, waving"><br><sub>Dog</sub></td>
  132. <td align="center"><img src="assets/characters/gif/rabbit.gif" width="96" height="102" alt="Rabbit, waving"><br><sub>Rabbit</sub></td>
  133. <td align="center"><img src="assets/characters/gif/bear.gif" width="96" height="102" alt="Bear, waving"><br><sub>Bear</sub></td>
  134. <td align="center"><img src="assets/characters/gif/fox.gif" width="96" height="102" alt="Fox, waving"><br><sub>Fox</sub></td>
  135. </tr>
  136. <tr>
  137. <td align="center"><img src="assets/characters/gif/penguin.gif" width="96" height="102" alt="Penguin, waving"><br><sub>Penguin</sub></td>
  138. <td align="center"><img src="assets/characters/gif/duck.gif" width="96" height="102" alt="Duck, waving"><br><sub>Duck</sub></td>
  139. <td align="center"><img src="assets/characters/gif/frog.gif" width="96" height="102" alt="Frog, waving"><br><sub>Frog</sub></td>
  140. <td align="center"><img src="assets/characters/gif/owl.gif" width="96" height="102" alt="Owl, waving"><br><sub>Owl</sub></td>
  141. <td align="center"><img src="assets/characters/gif/panda.gif" width="96" height="102" alt="Panda, waving"><br><sub>Panda</sub></td>
  142. <td align="center"><img src="assets/characters/gif/hamster.gif" width="96" height="102" alt="Hamster, waving"><br><sub>Hamster</sub></td>
  143. </tr>
  144. <tr>
  145. <td align="center"><img src="assets/characters/gif/goldfish.gif" width="96" height="102" alt="Goldfish, waving"><br><sub>Goldfish</sub></td>
  146. <td align="center"><img src="assets/characters/gif/pufferfish.gif" width="96" height="102" alt="Pufferfish, waving"><br><sub>Pufferfish</sub></td>
  147. <td align="center"><img src="assets/characters/gif/octopus.gif" width="96" height="102" alt="Octopus, waving"><br><sub>Octopus</sub></td>
  148. <td align="center"><img src="assets/characters/gif/whale.gif" width="96" height="102" alt="Whale, waving"><br><sub>Whale</sub></td>
  149. <td align="center"><img src="assets/characters/gif/turtle.gif" width="96" height="102" alt="Turtle, waving"><br><sub>Turtle</sub></td>
  150. <td align="center"><img src="assets/characters/gif/hedgehog.gif" width="96" height="102" alt="Hedgehog, waving"><br><sub>Hedgehog</sub></td>
  151. </tr>
  152. <tr>
  153. <td align="center"><img src="assets/characters/gif/pig.gif" width="96" height="102" alt="Pig, waving"><br><sub>Pig</sub></td>
  154. <td align="center"><img src="assets/characters/gif/sheep.gif" width="96" height="102" alt="Sheep, waving"><br><sub>Sheep</sub></td>
  155. <td align="center"><img src="assets/characters/gif/ladybug.gif" width="96" height="102" alt="Ladybug, waving"><br><sub>Ladybug</sub></td>
  156. <td align="center"><img src="assets/characters/gif/bee.gif" width="96" height="102" alt="Bee, waving"><br><sub>Bee</sub></td>
  157. <td align="center"><img src="assets/characters/gif/robot.gif" width="96" height="102" alt="Robot, waving"><br><sub>Robot</sub></td>
  158. <td align="center"><img src="assets/characters/gif/dinosaur.gif" width="96" height="102" alt="Dinosaur, waving"><br><sub>Dinosaur</sub></td>
  159. </tr>
  160. </table>
  161. Members pick one of these or compose their own in the web client's editor. The pigeon is Pip's and
  162. stays with the project, as [TRADEMARKS.md](TRADEMARKS.md) says. The other 23 are
  163. [CC BY 4.0](assets/characters/LICENSE.md): credit them as "Homingbird characters". Regenerate the
  164. GIFs with `pnpm --filter @homingbird/sprites assets`.
  165. ## Install
  166. Homingbird is self-hosted. Run Dovecote, the container image `ghcr.io/let-sunny/homingbird`, then
  167. connect agents with the npm packages `@homingbird/cli` (the command line and desk runner, for any
  168. agent), `@homingbird/mcp` (any MCP client) and `@homingbird/mod`, the Claude Code plugin (the package keeps
  169. its older name; install it with `/plugin install homingbird --marketplace let-sunny/homingbird`). The
  170. `homingbird` command line works with any agent, and the plugin uses it underneath.
  171. ```sh
  172. docker run -p 8080:8080 -v homingbird:/data \
  173. -e HB_PUBLIC_URL=https://homingbird.example.com \
  174. -e HB_OIDC_CLIENT_ID=... -e HB_OIDC_CLIENT_SECRET=... \
  175. -e HB_ALLOWED_DOMAINS=example.com \
  176. -e HB_ADMIN_EMAILS=you@example.com \
  177. ghcr.io/let-sunny/homingbird
  178. ```
  179. To try it on your own computer without an identity provider, use development login, which lets
  180. anyone who reaches the server sign in as anyone. Bind it to `127.0.0.1` so only this computer can:
  181. ```sh
  182. docker run -p 127.0.0.1:8080:8080 -v homingbird-try:/data \
  183. -e HB_PUBLIC_URL=http://localhost:8080 -e HB_DEV_LOGIN=1 \
  184. ghcr.io/let-sunny/homingbird
  185. ```
  186. Then open http://localhost:8080. Without `HB_ALLOWED_DOMAINS`, development login accepts any address,
  187. and the server says so when it starts.
  188. To keep an agent answering on a server that has no browser, open **My agent** → **Connection** →
  189. **Run on a server** in the web client and paste the line it shows on that server, after
  190. `npm install -g @homingbird/cli`. It signs the server in with a code that works once, for 10 minutes,
  191. and installs the background service:
  192. ```sh
  193. homingbird setup --server https://homingbird.example.com --join hbj_… --agent claude
  194. ```
  195. Each release is tagged `ghcr.io/let-sunny/homingbird:<version>`; pin one in production. To build the
  196. image yourself instead, run `docker build -t homingbird .` in a clone.
  197. Or copy `.env.example` to `.env`, fill it in and run `docker compose up -d`: compose passes every
  198. variable in `.env` to the server and publishes it on `127.0.0.1:8080`, for a TLS proxy on the same
  199. host ([behind a proxy](docs/deployment.md#behind-a-load-balancer)). The web client is served by
  200. Dovecote at `HB_PUBLIC_URL`.
  201. We estimate that one instance on 1 vCPU and 1 GB serves about 1,000 members, from one
  202. [load measurement](docs/deployment.md#measurements) on SQLite on a shared machine; it is not a
  203. guarantee. Sizing, databases, upgrades, backups and Terraform for GCP and AWS (experimental) are in
  204. [`docs/deployment.md`](docs/deployment.md).
  205. ## Your desk session
  206. Keep one agent session open for Homingbird. It drafts replies to arriving notes; you approve them.
  207. There are two first-class ways to run a desk: the **runner** (`homingbird run --agent "<command>"`),
  208. which works with any agent that runs from a command, and the **Claude Code plugin**, a convenience for
  209. people who already work in Claude Code. The `homingbird` command line works with any agent, and the plugin
  210. uses it underneath.
  211. | Agent | Make it your desk | When a note arrives |
  212. | --- | --- | --- |
  213. | Codex CLI, Gemini CLI, Cursor agent | Keep `homingbird run --agent "codex exec"` running (or `"gemini -p"`, `"cursor-agent -p"`) | Drafts by itself; approve in the web client |
  214. | An MCP client whose chat stays open, such as Cursor | Run the `watch` prompt in one chat | Drafts while that chat is open; approve in the web client |
  215. | Claude Code | `/homingbird` in one session | Drafts by itself; approve in the web client, which each draft in the pane links to |
  216. | ChatGPT, claude.ai, other web connectors | Pick one chat with the connector | Cannot be woken: a phone notification tells you; say "check Homingbird" there, or answer in the web client |
  217. - Every other session drafts only when you ask it ("Ask June whether…").
  218. - **Agent awake** in the directory means your desk is running. A connected agent that is not running
  219. is not awake, and a note to it waits.
  220. - Approving happens only in the web client. Writing by hand works there too.
  221. The full guide, from signing in to phone notifications, is [`docs/guide.md`](docs/guide.md).
  222. ### Agents and how far each is tested
  223. A preset not yet tested was written from the tool's source code and has not been run against the real
  224. agent. `homingbird presets` prints the same state on your computer, with the version it found.
  225. | Agent | Runner preset | Tested |
  226. | --- | --- | --- |
  227. | Claude Code | `--agent claude` | Verified with Claude Code 2.1.327 |
  228. | Codex CLI | `--agent codex` | Not yet tested with the real CLI |
  229. | Antigravity CLI (`agy`) | `--agent antigravity` | Not yet tested with the real CLI |
  230. | Gemini CLI | `--agent gemini` | Not yet tested with the real CLI |
  231. | Any other command | `--agent "<command>"` | Your command: try one note before you rely on it |
  232. Try an untested preset on one person's desk before a team relies on it; the
  233. [command line's README](packages/cli/README.md#agent-presets) lists the exact commands.
  234. ## Usage
  235. **In the browser.** Sign in with your organization account, pick a colleague from the directory, and
  236. write. Drafts from your agents appear in the conversation with **Send**, **Edit** and **Discard**.
  237. **In Claude Code.** At the prompt of a Claude Code session in a terminal, run the line below, answer
  238. `y` to add the marketplace and pick a scope; then type `/homingbird` to open the pane:
  239. ```
  240. /plugin install homingbird --marketplace let-sunny/homingbird
  241. ```
  242. The marketplace always installs the version of the plugin that this repository's default branch names
  243. in `.claude-plugin/marketplace.json`, the same version as every other package.
  244. Ask in plain words, "Ask June whether the billing migration is safe to run today." Your agent drafts
  245. the note, and it is sent when you approve it. June's approved reply arrives in the same conversation.
  246. **In any MCP client** (Codex, Cursor, Gemini CLI, claude.ai). Register
  247. `https://homingbird.example.com/mcp` as a remote connector, or run the adapter locally as a stdio server:
  248. ```sh
  249. npx -y @homingbird/mcp --server https://homingbird.example.com # any chat session
  250. npx -y @homingbird/mcp --server https://homingbird.example.com --desk # your one desk session
  251. ```
  252. Drafts wait for your approval in the web client.
  253. **Ask a channel** when you do not know who can answer: "Ask the billing channel who owns the nightly export."
  254. It reaches the people who answer questions in billing. When no channel fits, the agent asks a colleague whose
  255. profile matches, or tells you it found no one. Joining a
  256. channel and answering in it are separate switches, and a channel can be private to the people its managers add
  257. ([guide](docs/guide.md#join-a-channel-answer-in-it-or-keep-it-private)).
  258. ## Commands
  259. The `homingbird` command line is what the plugin runs underneath, and it works on its own
  260. (`npm install -g @homingbird/cli`, Node 22 or newer):
  261. ```sh
  262. homingbird login --server https://homingbird.example.com # sign in this device with a code
  263. homingbird setup --server https://homingbird.example.com --join hbj_… --agent claude
  264. # on a server: the line from Run on a server
  265. homingbird inbox # notes waiting for a reply
  266. homingbird draft --to june@example.com "Is the billing migration safe to run today?"
  267. homingbird draft --channel billing "Who owns the nightly export?"
  268. homingbird drafts # drafts waiting for approval
  269. homingbird run --agent "codex exec" # be the desk: answer what arrives
  270. homingbird stream # live events, one JSON object per line
  271. ```
  272. The command line holds an agent credential only: it drafts, and never sends or discards. You approve
  273. in the web client (`homingbird open`). Every command accepts `--json`; the full list is in the
  274. [CLI's README](packages/cli/README.md).
  275. ## Configuration
  276. | Variable | Default | Meaning |
  277. | --- | --- | --- |
  278. | `HB_PUBLIC_URL` | required | The URL people and agents use to reach Dovecote |
  279. | `HB_DATABASE_URL` | `sqlite:./data/dovecote.sqlite` | `sqlite:`, `postgres:` or `mysql:` (MySQL is experimental: tested automatically, not yet used in a real deployment) |
  280. | `HB_OIDC_ISSUER` | `https://accounts.google.com` | Any OpenID Connect issuer |
  281. | `HB_OIDC_CLIENT_ID`, `HB_OIDC_CLIENT_SECRET` | required | From your identity provider |
  282. | `HB_ADMIN_EMAILS` | required | Members who administer the server; nobody becomes one implicitly |
  283. | `HB_ALLOWED_DOMAINS` | none | Email domains whose people may sign in without an invite, comma-separated; unset, only invited people and `HB_ADMIN_EMAILS` get in |
  284. | `HB_CHANNELS` | none | Channels to start with: `slug` or `slug: description`, comma-separated |
  285. | `HB_CONTACT_MODE` | `open` | `open`, or `contacts` to require an accepted request first |
  286. | `HB_TRUST_PROXY` | `0` | Number of proxies in front of Dovecote, when it is reachable only through them ([details](docs/deployment.md#behind-a-load-balancer)) |
  287. | `HB_LOGS` | `audit=full,operational=info,requests=off,auditCopy=off` | What the audit trail and the operational log record ([logs](docs/deployment.md#logs)) |
  288. | `HB_AUDIT_RETENTION_DAYS` | `400` | Days to keep audit rows, at least 90 |
  289. | `HB_ANALYTICS`, `HB_ANALYTICS_URL`, `HB_ANALYTICS_KEY` | `off` | Where anonymous product analytics go, if anywhere ([analytics](docs/deployment.md#product-analytics)) |
  290. | `HB_THEME_DIR` | none | A directory with `theme.css`, `branding.json`, and the fonts and images they use, served under `/theme/` ([guide](docs/guide.md#bring-your-own-web-client)) |
  291. Sessions, credential lifetimes, OAuth clients, push hosts and the rest are in
  292. [`docs/deployment.md`](docs/deployment.md#configuration).
  293. ## Security
  294. Nine rules are never broken, and each has a test:
  295. 1. Only a human credential can approve a note. Agent credentials can draft, read and pick up, never approve. The contract marks approval routes `access: 'human'` and the domain function checks again.
  296. 2. Drafts are invisible to recipients: inbox, stream, search, and lookup by id.
  297. 3. No tool exposed to a model can approve, change contacts, or read credentials. No agent integration can approve: approval happens only in a client where the person signed in themself, the web client.
  298. 4. Every received note is passed to a model wrapped as quoted data from a colleague, never as instructions. `wrapNote` in `packages/protocol/src/wrap.ts` is the only wrapper; never format a note for a model any other way.
  299. 5. Credentials are stored hashed and never logged. Tokens appear in exactly one response, when issued. A token a person gives Homingbird to wake an outside service cannot be hashed: it is stored encrypted, used only in the request that wakes that service, never shown again, and deleted when the person removes it.
  300. 6. A member sees only conversations they participate in. An administrator, as a person in the web client only, may also see which private channels exist and who is in them, never their notes, and may read private debate rooms. A private channel's managers are the members of the group that manages it, and only that group's members add people to the channel or to the group: an administrator outside the group can add no one, themself included. Every member sees teams and who is in them; a group made for one channel is shown only to people who can see that channel. Deactivating a member removes them from every group. An administrator's agent credentials get no such exception.
  301. 7. No tool exposed to a model can save or change a profile character. Only a person's click saves, and the server validates again; it never trusts a client's check.
  302. 8. No tool exposed to a model can save, change, enable, disable or delete a principle. Only a person's action in the web client saves, and the server validates it again.
  303. 9. No tool exposed to a model can open a debate room, opt an agent in, change its limits, or approve, post or export its result. A room's content leaves it only through a person: a member exports the closed room, or a person whose agent took a turn posts its result, which is sent like any note only after that person approves it. A turn is shown to the room without approval, so a debate tool returns nothing but room content wrapped by `wrapNote`.
  304. The tests are in [`security-rules.test.ts`](packages/dovecote/test/security-rules.test.ts), one block
  305. per rule, 1 through 9. Where each rule is enforced, and which adapter tests cover it again, is in
  306. [this table](docs/architecture.md#where-the-nine-security-rules-are-enforced-and-tested). See also
  307. [`.claude/rules/security.md`](.claude/rules/security.md) and [`SECURITY.md`](SECURITY.md).
  308. ## Develop
  309. Using the published packages needs Node 22 or newer; working on this repository needs Node 22.18 or
  310. newer, because development runs TypeScript files directly. If your shell loads nvm lazily, run
  311. `nvm use` (or check that `node -v` works) before `pnpm dev`.
  312. ```sh
  313. pnpm install
  314. pnpm dev # Dovecote with a development login on http://localhost:8080
  315. pnpm typecheck && pnpm lint && pnpm test
  316. pnpm build # server, CLI, MCP and web bundles
  317. ```
  318. How agents, the server and the web client interact is drawn in
  319. [`docs/architecture.md`](docs/architecture.md). Design decisions are recorded in
  320. [`docs/decisions.md`](docs/decisions.md). Ideas outside the current
  321. scope are in [`docs/roadmap.md`](docs/roadmap.md).
  322. ## Contribute
  323. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) first. The rules in [`CLAUDE.md`](CLAUDE.md) apply to every
  324. contributor and every coding agent.
  325. Check the [issues](https://github.com/let-sunny/homingbird/issues) before reporting a problem or
  326. asking for a feature, and report security problems privately, as [`SECURITY.md`](SECURITY.md)
  327. describes. A pull request runs `pnpm typecheck && pnpm lint && pnpm test`, records any new design
  328. decision in `docs/decisions.md`, and says why the change is needed.
  329. ## License
  330. Code: [MIT License](LICENSE) © 2026 Minseon Kim (let-sunny). The Homingbird name, logo and Pip the pigeon stay with the
  331. project; see [TRADEMARKS.md](TRADEMARKS.md). The built-in profile characters are
  332. [CC BY 4.0](assets/characters/LICENSE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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