Skip to content

Commit 508be98

Browse files
committed
humanize prose in README + bridge pattern doc
Tighten the high-visibility prose so it reads like the person who actually built this wrote it. No content changes — just rhythm, voice, and a few aphoristic phrases removed: * Why intro: less enumeration, more 'I got tired of that' * Substrate-not-opinion callout folded into a flatter sentence * Origin section: 'after the third time writing the same glue' is the actual reason, said plainly * Acknowledgments: shorter, less ceremonial * BRIDGE_PATTERN.md why-section: 'I wrote this because I wanted to talk to my laptop from my phone' instead of 'this pattern was originally invented mid-conversation'
1 parent 30eabec commit 508be98

2 files changed

Lines changed: 14 additions & 15 deletions

File tree

README.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -68,19 +68,19 @@ End to end: Linux VM hosting the hub + publisher → Cloudflare tunnel → Windo
6868

6969
## Why
7070

71-
Today, exposing a custom AI (an agent, a fine-tuned local model, a custom RAG stack, an MCP server) to the rest of your tools means re-writing the same plumbing every time: auth, tunnel, API gateway, SDK, retries, MCP bridge, identity, federation.
71+
Every time you want a custom AI reachable from your tools — an agent, a local model, a RAG stack, an MCP server — you end up rewriting the same plumbing: auth, tunnel, API gateway, SDK, retries, MCP bridge, identity, federation. I got tired of that.
7272

73-
`zhub` is the substrate that does all of that once. Whatever brain you have, plug it in. Whatever client you use (Pocket, Cursor, TypingMind, Continue, Claude Desktop, openai-py, curl), it just works — same OpenAI Chat Completions wire format.
73+
`zhub` does that plumbing once. Plug in any brain. Use any client (Pocket, Cursor, TypingMind, Claude Desktop, openai-py, curl) — they all speak OpenAI Chat Completions, and so does the hub.
7474

75-
> **Substrate, not opinion.** zhub knows nothing about your AI's identity, your devices, your business logic. It routes bytes, multiplexes WebSockets, validates schemas, resolves tool calls, federates across hubs. The thing on top is yours.
75+
The hub stays neutral on purpose. It doesn't know your AI's identity, your devices, or your business logic. It routes bytes, holds keys, resolves tool calls, peers with other hubs. Whatever you put on top is yours, not zhub's.
7676

7777
### Origin
7878

79-
I built zhub for my own private AI**ZAI** — that I want reachable from everywhere: phone chat ([Pocket](https://github.com/Zawwarsami16/pocket)), laptop dev tools (Claude Desktop, Cursor), custom surfaces — without writing the same auth/tunnel/SDK plumbing five times. ZAI itself stays private. What made it interesting to *build the connector right* is what's open source here.
79+
zhub started as the connector for my own private AI, **ZAI**. I wanted ZAI reachable from anywhere: phone chat via [Pocket](https://github.com/Zawwarsami16/pocket), dev tools like Claude Desktop and Cursor, my own scripts, a friend's hub. After the third time writing the same auth + tunnel + SDK glue, I pulled it out into a library. That library is what you see here. ZAI itself stays private.
8080

81-
I can't show ZAI directly, so the [LinkedIn demo](https://www.linkedin.com/in/zawwarsami) instead wraps a **Claude Code session** as a zhub publisher and reaches it from Pocket on a phone — same substrate, different brain. The screenshots above are a separate reproducible flow: a fresh `git clone` on a Linux virtual machine, a Groq brain published with the API key the user generated, and Windows PowerShell talking to it through the tunnel. Every screenshot, every URL, every response is from a real first-time install — nothing staged.
81+
I can't demo this on ZAI, so the [LinkedIn post](https://www.linkedin.com/in/zawwarsami) wraps a **Claude Code session** as a zhub publisher instead — same substrate, different brain — and reaches it from Pocket on a phone. The screenshots above are a separate, reproducible run: fresh `git clone` on a Linux VM, a Groq brain published in one command, Windows PowerShell talking through the Cloudflare tunnel. Nothing staged.
8282

83-
The same primitive works for any AI — yours, mine, a model someone hasn't trained yet. zhub doesn't care.
83+
The same primitive works for whatever brain you point it at.
8484

8585
---
8686

@@ -433,7 +433,7 @@ For larger changes, walk through `docs/superpowers/specs/` to see the design con
433433

434434
### Acknowledgments
435435

436-
Built collaboratively with **Claude (Anthropic)** as a pair-programming partner. The git history is the trail — every commit is co-authored. Specs and plans live under `docs/superpowers/`. Architecture decisions, primitive choices, and the "substrate not product" stance were worked through in conversation; implementation followed strict spec → plan → TDD discipline. Same craftsmanship standard would have applied without an AI partner; with one, it shipped faster.
436+
Built side-by-side with **Claude (Anthropic)** as a pair-programming partner. The git history shows it — every commit co-authored, every spec under `docs/superpowers/`. Architecture, primitives, and the "stay neutral" decision were worked out in conversation. Implementation followed strict spec → plan → TDD. The same standard would've applied solo; with a partner it shipped faster.
437437

438438
---
439439

docs/BRIDGE_PATTERN.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,10 @@ that matches what you're actually doing on the other side.
9393
| Replies are empty | Outbox JSON missing `"text"` field | Watcher must write `{"text": "..."}` exactly |
9494
| Two watchers, double replies | Race | Run only one watcher per inbox |
9595

96-
## Reasoning trace (why this exists)
97-
98-
This pattern was originally invented mid-conversation as a way to talk
99-
to a Claude Code session running on a laptop from Pocket on a phone.
100-
It worked, but the hack lived in `/tmp/`. Promoting it to a proper
101-
example + this doc means future sessions don't have to rediscover it,
102-
and anyone cloning the repo can wrap their own interactive agent the
103-
same way.
96+
## Why this exists
97+
98+
I wrote this the first time because I wanted to talk to a Claude Code
99+
session on my laptop from Pocket on my phone. The original lived in
100+
`/tmp/` as throwaway. After it kept working I moved it into the repo
101+
so I (and anyone else) wouldn't have to redo the trick from scratch
102+
every time.

0 commit comments

Comments
 (0)