Morning — what needs me today?
Hand work to your Hermes agent by message. It works on your machine, asks before anything sensitive, sends a morning brief, and pings your phone when something needs you.
Self-hosted, loopback by default. Your thread, files and keys stay on your machine; reach it from your phone over Tailscale.
- PWA
- Bun + SQLite
- Hermes /v1/runs
- 11 MCP tools
- Web push
- MIT
A phone surface for the agent you already run.
Not another model, and not a chat wrapper. Duet keeps the thread, drives Hermes’s own background runs, and puts the decisions in front of you as cards you can actually act on.
One thread.
Chat, tool activity and cards share one conversation. Tasks tracks running work, Make collects every file it hands you, and one search covers all of it.
It comes to you.
A morning brief at the time you pick, optional check-ins that stay quiet unless something needs you, and web push that respects quiet hours.
Asks before it acts.
Sending messages as you, paying, deleting, posting and signing stop at an Approve / Not now card. Drafts are editable, and your edits come back verbatim.
Works in the background.
Decks, dashboards and research run as tasks in their own Hermes session. The conversation stays free, and finished work returns as one handover card.
Steer or stop.
A message sent mid-run steers the live turn. Stop interrupts it. A steer that arrives too late goes out as the next turn instead.
Survives restarts.
If the gateway restarts mid-run, Duet unpauses the session, retries blocked work, and asks whether to pick up the interrupted job.
The approval is the feature.
The agent can prepare the email, pick the vendor, build the deck. The actions that need you — sending, paying, deleting, posting, signing — stop at this card with the exact text it intends to send.
- The turn ends while the card waits, so nothing happens behind your back.
- Tapping Approve resumes the same Hermes session; an edited draft comes back verbatim.
- Not now ends the turn without acting. A redraft withdraws the older card.
The card on the right is a browser-only simulation. It never contacts a server and never sends anything.
Send the reply to Dana
To: Dana Whitfield · Re: MSA redline
Edit the draft if you like. Your version is what would be sent.
Small server. Real agent. No second brain.
Duet serves the PWA and keeps the thread. Hermes does the thinking and the work. A loopback-only MCP shim is the only bridge, and every tool call becomes a card, a file or a task.
The PWA
Installed from Safari or Chrome. Approvals, briefs, tasks, files and push.
Bun + SQLite
Thread, cards, lanes, scheduler, uploads. One process, loopback only.
Your existing agent
POST /v1/runs, event stream, /steer, /stop.
Shell + MCP
Files, browser, calendar, mail, and the 11 duet tools.
Lanes are the concurrency model. Each Hermes session is a lane, and a lane runs one turn at a time. Your thread is one lane; every background task gets its own; check-ins use a daily side session. That is why a long deck never blocks a reply.
The chat you type into. Briefs, check-ins, approvals and task handovers land here.
Self-contained instructions; reports progress through update_task.
Rebuilds 30 minutes before the brief, in a fresh session that knows nothing else.
# Spawn the shim; it forwards calls to Duet's loopback API. mcp_servers: duet: command: /absolute/path/to/bun args: ["/absolute/path/to/hermes-duet/server/mcp-shim.ts"] tools: {} # {} — not "all"
Recent Hermes builds pick this up without a restart. If the mcp__duet__* tools don’t appear, restart the gateway.
Eleven tools on the wire.
Hermes spawns server/mcp-shim.ts as the duet MCP server. The shim holds no state;
every call lands on Duet’s loopback internal API. No tool can act directly — the agent gets a card, a
file, or a status line.
request_approval An Approve / Not now card for anything hard to undo.
Posts an editable draft and the exact action. The turn ends and the card waits. Tapping resumes the same session; an edited draft arrives as APPROVED with edits and must be sent exactly. replaces withdraws an earlier, superseded card.
request_payment An itemized receipt, a hard cap, and a single-use card.
The line items must add up to the total, and the total must sit under DUET_MAX_TRANSACTION_LIMIT (default $500) or nothing is posted. Approving issues a single-use virtual card capped at that exact total for one hour and types it into the live browser. Card numbers never reach the model, SQLite or a log line.
ask A quick decision with 2–4 tappable answers.
Returns immediately and ends the turn. The answer comes back as [answer <card_id>]. An optional context gives the background needed to choose; replaces withdraws an older question.
withdraw_card Take back your own waiting card when chat settled it.
For an approval or question the user answered in chat (“don’t send that”, “the second one”). The card leaves “Needs you” and can no longer be tapped. It is not a way to approve: a yes in chat still needs the card’s button.
post_brief A ranked brief with prepared drafts and a muted Watching list.
Up to five decisions, sorted high to low, each with an optional prepared draft and one-tap follow-up. Watching is muted and never notifies. A quiet morning brief may be Watching-only and posts without a push. “Skip” on a decision tells the next briefs not to raise it again unless something material changed.
post_card A checklist, metrics row or note — updatable in place.
Structured progress without another message. Pass a previous card_id to update that card as steps complete, rather than posting a new one.
deliver_file Hand over a doc, sheet, deck, PDF or live HTML dashboard.
The agent writes the file, then delivers its absolute path. HTML renders live but sandboxed; self-contained HTML is the best format for dashboards and decks. A window.Duet bridge lets buttons become chat turns or approval cards — one-way into a validator, never direct action.
save_page Turn a delivered file into a page rebuilt every morning.
Thirty minutes before the brief, a background task rebuilds the page from the saved instructions and replaces the old version. Refreshes never push; a failure leaves a card. One line on what changed is pinned at the top and called out in the brief.
start_task Start larger work in its own session so chat stays free.
Instructions must be self-contained because the task gets a fresh context. The result, files and up to three follow-ups return as one handover card. A failed task gets the same card, muted, with its reason and a “Try again” button.
update_task Keep the Tasks tab honest: progress, steps, result, follow-ups.
One line on what is happening now, optional step checklist, and a final outcome. changed carries the one-line diff for a standing page refresh; follow_ups adds up to three one-tap next steps to the handover card.
notify A push that opens a “Heads up” note in the thread.
Only for things that genuinely need the user soon. During quiet hours the push is held for “While you were away”. Check-ins and the morning brief cannot use it; they reach the user through post_brief.
No tools match that filter. Try “card”, “task”, “file” or “money”.
The full contract — descriptions, schemas and validation — is in server/tools.ts.
The actual app, not a render.
Captured from the project’s demo instance with made-up data. The ink, halftone, gold band and type are the shipped PWA, not a marketing skin. Click any screenshot to enlarge it.
The README also carries an illustrated overview and the original signal-path art.
Start it in four commands.
Duet is self-hosted on purpose. Clone it next to your Hermes install, run it as a service, and pair your phone once. Nothing is exposed to the internet by default.
- Bun 1.2 or newer.
- A running Hermes agent with
API_SERVER_ENABLED=trueand anAPI_SERVER_KEY. - macOS for launchd and the native Calendar, Reminders and Mail connectors. The server itself runs anywhere Bun does.
- Tailscale on the phone and the Mac for the private HTTPS URL that PWA install and push require.
Clone, install and build
One Bun workspace. The web build is a normal Vite production build.
git clone https://github.com/DevvGwardo/hermes-duet && cd hermes-duet bun install && bun run build
Install the service
launchd on macOS, bound to 127.0.0.1:7456. Linux uses systemd.
bin/hermes-duet install ln -sf "$PWD/bin/hermes-duet" ~/.local/bin/hermes-duet
Linux: hermes-duet install-systemd. Container: see docs/DEPLOY.md.
Connect Hermes
Add the MCP shim to ~/.hermes/config.yaml, then restart the gateway only if the tools don’t appear.
mcp_servers:
duet:
command: /absolute/path/to/bun
args: ["/absolute/path/to/hermes-duet/server/mcp-shim.ts"]
tools: {}
Pair your phone
Check the setup, open the app, then enter a one-time code. Use the Tailscale URL from your phone.
hermes-duet doctor hermes-duet pair tailscale serve --bg --https=8443 http://127.0.0.1:7456
Then open the HTTPS address, Share → Add to Home Screen, and enter the code.
Treat the URL like a shell.
This is a remote control for an agent with your files, calendar and browser. The defaults are built around that fact, and the project is candid about the edges.
approvals.mode. Its prompts show up as
Duet cards too.
- Nothing public by default. The server binds to
127.0.0.1; reach it over a tailnet, or put real authentication in front if you expose it another way. - Pairing is single-use. Codes expire after 10 minutes, wrong guesses are rate-limited, and only the token hash is stored in an HttpOnly, SameSite cookie.
- The internal API is loopback-only. Its own bearer token, and it refuses proxied requests.
- Deliverables are sandboxed. HTML gets
Content-Security-Policy: sandbox; its buttons feed a one-way validator that becomes a chat turn or approval card, never a direct action. - Uploads stay local. Server-generated names,
0600, a fixed type allowlist,nosniff, and a sandbox CSP. Photos never leave the machine. - Spending has a receipt. The items must add up, the total must be under the cap, and a virtual card is limited to that total for one hour. Only the last four digits are reported.
- Webhooks create turns, not commands. An unguessable URL token, rate-limited; payloads are passed to the agent as text.
Before you clone it.
The things people ask before handing an agent their phone and their machine.
Is this affiliated with Nous Research or Anthropic?
No. It is an unofficial community project. The product idea comes from Anthropic’s Claude Duet, and the mascot art comes from NousResearch/hermes-agent under MIT. See NOTICE.md.
Does it replace Hermes?
No. Hermes is the agent and does the work. Duet is the phone surface: it keeps the thread, drives Hermes’s background runs, and gives the agent a small MCP tool surface for cards, briefs, files, tasks and push.
Do I need a Mac?
The server runs anywhere Bun runs, including Linux and Docker. macOS is what gets the launchd service and the native Calendar, Reminders and Mail connectors. See docs/DEPLOY.md.
Does it work on Android?
It is an installable PWA served over HTTPS, so a modern Android browser can install it and receive web push. The README’s setup notes are written around iOS and Tailscale, including the service-worker behavior iOS requires.
What does it store?
A SQLite database under data/ holding the thread, cards, tasks, delivered files, pairing tokens and push keys, plus uploads under data/uploads. data/ and .env are gitignored. Nothing is sent to a Duet service; there isn’t one.
Can I try it without Hermes?
Yes. bun scripts/demo.ts --reset starts a throwaway instance with made-up data on port 7466; bun scripts/demo.ts pair gives you a pairing code. It never touches your real thread.
What is still open?
The project keeps a public GAPS.md ledger from a multi-agent audit: what was fixed, what is still open, and what was rejected as a false positive. Data is not encrypted at rest yet, and mutation rate limits are deferred for the single-user case.
Hand it something.
One thread, a morning brief, and an approval card before anything sensitive. Your agent, on your machine, in your pocket.