A persistent Creator Partnership Director built on Minds by Animoca Brands.
The creator chooses the relationship. CollabOS runs everything in between.
CollabOS remembers creator relationships, finds aligned collaborators, brings approved partners into a trusted Mind Circle, coordinates the joint campaign, follows up autonomously, and learns which partnerships actually grow the audience.
It is built to be an operator, not a recommendation chatbot.
This is an in-progress hackathon build. What is actually working right now, verified:
| Milestone | Status |
|---|---|
| 0 — Repository & documentation inspection | Complete — see docs/implementation-plan.md |
| 1 — Minds platform proof | Complete — 8/8 PASS against the live platform |
| 2 — Foundation | Complete — Postgres + Prisma + migrations + seed + env validation + Minds wrapper + audit log + state machine |
| 3 — Recommendation & approval | Complete — objective form, structured Mind ranking with repair-retry, Partner Review UI, approval gates, Activity Log |
| 4 — Circle & campaign | Complete — Circle admission, shared brief, deliverable, Collaboration Room, signed collaborator link, emergency cleanup command |
| 5 — Autonomous follow-up worker | Complete — separate worker process, lease-based claiming, max-one follow-up enforced in the database, bounded retries, live UI polling |
| 6 — Completion loop | Complete — final approval, completion, relationship write-back, revision round, campaign report |
| 7 — Quality & demo polish | Complete — Playwright E2E, loading/error states, accessibility basics, demo reset, full documentation, demo script |
Quality gates as of the last run: lint ✅ · typecheck ✅ · test ✅ (232 tests) · build ✅ ·
test:e2e ✅ (2 tests)
The full vertical slice has been run end to end against the real Minds platform, with no
fixture or scripted component anywhere — all 16 Definition-of-Done items are proven. The real
Mind ranked Mira first (fit 96, smallest audience) citing her stored collaboration history,
rejected Nova on brand-safety grounds without needing CollabOS's override, and wrote the
follow-up wording itself. A real Circle mutation created a real party, confirmed independently
via minds circle show.
CollabOS also boots and runs without credentials, reporting the Mind as disconnected rather
than fabricating a recommendation, a follow-up, or a Circle result. See
Connecting a Mind and
docs/known-limitations.md §1 for the measured evidence.
Plan for latency: a full campaign takes ~13 minutes and ~15.4 cognition. Partner
ranking alone is 86–145 s. MINDS_REPLY_TIMEOUT_MS must stay at 240000 — the original 120 s
default timed out on a healthy Mind.
CollabOS is not "an app that calls an LLM". The division of responsibility is structural:
| Minds owns — relationship intelligence | CollabOS owns — deterministic execution |
|---|---|
| Creator and brand context | Campaign state machine |
| Relationship memory across sessions | Database records |
| Partner-fit reasoning | Scheduling and the follow-up worker |
| Context-aware message wording | Approval enforcement |
| Campaign continuity | Circle mutations and transport |
| Follow-up reasoning | Audit log, retries, idempotency |
Minds owns contextual memory. CollabOS owns operational state.
Chat history is never used as the operational database, and Postgres is never asked to make a judgement.
Memory — Maya's brand voice, target audience, prohibited topics, and her full
relationship history with each partner live in Postgres and are sent to the Mind as
structured context on every call. The Mind is asked to return the specific remembered
facts it used (memoryUsed), which the Partner Review UI renders as evidence that
memory drove the decision rather than decorating it.
Continuity — one durable conversation alias per creator
(CreatorProfile.mindConversationAlias, e.g. collabos-maya), bound idempotently via
ensureConversation(). Every session and every worker run reuses it, so the Mind is
never re-briefed and the creator never re-explains the campaign.
Circle — an approved collaborator is added to the Mind's Circle through
addCircleMembers(), verified before and after mutation. Circles are the platform's
actual trust gate ("Circles are how Minds and humans get permission to talk to each
other"), so this is a real permission change, not a cosmetic one.
Autonomy — a server-side worker polls nextActionAt, claims work with
SELECT … FOR UPDATE SKIP LOCKED, asks the Mind to compose a contextual follow-up, and
sends it. There is no manual "Follow Up" button anywhere in the UI, by design.
- Node.js ≥ 22 (tested on 22.13.1)
- Docker + Docker Compose
- A Minds Builder API key (for the Mind-backed features)
npm installpostinstall runs prisma generate automatically.
cp .env.example .env| Variable | Required | Purpose |
|---|---|---|
MINDS_BUILDER_API_KEY |
for Mind features | Builder API key. Server-side only. |
MINDS_MIND_ID |
for Mind features | Which Mind acts as Partnership Director |
COLLABORATOR_TEST_EMAIL |
for Circle step | The only address CollabOS will add to a Circle |
DATABASE_URL |
yes | Postgres connection string (SQLite is rejected) |
APP_URL |
yes | Base URL for signed collaborator links |
EMAIL_TRANSPORT |
no | mailpit (default) or console |
MAILPIT_HOST / MAILPIT_SMTP_PORT |
no | Local test SMTP, defaults localhost:1025 |
FOLLOW_UP_DELAY_SECONDS |
no | Deliverable window. 180 = the 3-minute demo |
LINK_SIGNING_SECRET |
no | HMAC secret for acceptance links; dev default if unset |
MINDS_REPLY_TIMEOUT_MS |
no | Mind reply timeout, default 240000. Do not lower — ranking takes 86–145 s |
Configuration is validated by Zod at startup (src/env.ts) — the app refuses to boot
on a bad config rather than failing later inside a request.
⚠️ Port note:APP_URLmust match the port you actually serve on, or the signed collaborator acceptance links in outbound email will point at the wrong server. On the development machine port 3000 is occupied by an unrelated service, so this repo runs on 3100 (npm run dev -- -p 3100) withAPP_URL=http://localhost:3100.
npm run infra:upStarts two containers:
- Postgres 17 on
localhost:5432 - Mailpit — SMTP on
1025, web UI on http://localhost:8025
npm run db:migrate # apply migrations
npm run db:seed # load the demo scenarionpm run db:reset wipes and reseeds for a clean demo take.
npm run dev -- -p 3100The port is not optional. next dev defaults to 3000, but APP_URL is http://localhost:3100
— serve on the wrong port and the signed acceptance link in the outbound email points at a
server that isn't there, which breaks the collaborator step mid-demo.
The autonomous follow-up worker is a separate process — this is what makes the autonomy real rather than a request-triggered illusion.
npm run worker # continuous polling loop (Ctrl-C to stop)
npm run worker:once # single pass, then exit
npm run worker -- --interval 2000 # faster polling for a live demoBecause it is a separate process, you can close the browser entirely and the follow-up still fires — which is the point. The Command Center, Room, and Activity Log poll every 5 seconds (there is a pausable "Live" indicator in the nav), so the follow-up appears without any interaction.
How "at most one follow-up" is guaranteed, in layers:
- Lease claim —
SELECT … FOR UPDATE SKIP LOCKEDplus alockedUntilexpiry. A second worker skips the row rather than blocking, and a crashed worker's claim frees itself. followUpCountcompare-and-swap — the hard cap, incremented in the same transaction as thefollow_up_senttransition and conditional on it still being0.- Unique
dedupeKey— a success marker written in that same transaction, so Postgres itself rejects a second recorded success.
Failed attempts are recorded without a dedupeKey, so a transient failure stays retryable (bounded at 3 attempts with backoff) while a successful send closes the door for good.
- Create a Builder API key at https://build.hellominds.ai/console → sign in → Keys → Create.
- Put it in
.envasMINDS_BUILDER_API_KEY. Never commit it. - Find your Mind ID:
Add it as
minds list --pretty
MINDS_MIND_ID. Create a Mind at https://hellominds.ai/profile if needed. - Set
COLLABORATOR_TEST_EMAILto an inbox you control. - Verify:
npm run minds:smoke
npm run minds:smoke runs every Milestone 1 check and regenerates
docs/minds-smoke-test.md from the real results, so that
evidence file is never hand-written or stale. It is safe to run without credentials —
authenticated checks simply report BLOCKED.
The CLI is used for setup and diagnostics only. Runtime integration goes through
@animocabrands/minds-client-lib; no request handler shells out to the CLI.
Being precise about this matters more than making the demo look impressive.
| Action | Reality |
|---|---|
| Partner-fit reasoning, follow-up wording | Real — live Minds API call |
| Cognition balance | Real — live read |
| Circle add / remove / read | Real — genuinely mutates the Mind's Circle |
| Conversation history & continuity | Real — persisted on the platform |
| Campaign state, approvals, audit log | Real — Postgres |
| Outreach & follow-up email | 🟣 LOCAL TEST TRANSPORT (Mailpit) — captured at http://localhost:8025, never delivered to the internet |
| Partner identities | 🟣 Synthetic — seeded demo records on the reserved @example.com domain |
| Partner replies / acceptance | 🟣 Human tester via a signed local link — never fabricated by the system |
Not done, in any form: no Instagram / X / TikTok / YouTube message is sent or claimed; no social platform is scraped; no X embed; no blockchain, token, NFT, escrow, or payment; no multi-agent orchestration.
Every mocked or local-transport action is labelled as such in the UI. A failed external
call is recorded as attempted + failed and can never render as success.
npm test # 232 tests — unit + integration
npm run test:unit # pure, no infrastructure needed
npm run test:integration
npm run test:e2e # Playwright — the full vertical slice in a browserTime is injected through src/lib/clock.ts, so the overdue-deliverable and
autonomous-follow-up tests advance a controlled clock instead of waiting three real
minutes. The E2E test drives a real HTTP server, so it shortens the configured deadline to
5 seconds rather than sleeping.
Tests bind a scripted MindsPort double. That is dependency injection for
determinism — the production binding is always the real client library, and a failed
integration is never hidden behind a mock. No automated test proves the Mind reasons well —
that was verified manually against the live platform instead, and the evidence is recorded in
docs/known-limitations.md §1.
Full detail in docs/test-plan.md.
The Playwright test needs a Mind, and no API key exists here, so
COLLABOS_UNSAFE_FIXTURE_MIND=1 swaps in canned responses. It is a labelled test seam, not a
hidden mock:
- throws under
NODE_ENV=productionrather than degrading quietly - every page renders a permanent red warning banner while it is active
- every stored exchange is marked
fixtureMode: trueand badged in the Activity Log - warns on the server console at construction
Never use it for a demo or a screenshot presented as real. It proves nothing about the Minds integration.
npm run lint
npm run typecheck
npm test
npm run buildFull list in docs/known-limitations.md. The headlines:
- Milestone 1 is not fully proven — listing Minds, validating the Mind ID, reading cognition balance, reading Circle state, and sending a test message all require a Builder API key that is not present. The live API is reachable (verified against the public Bazaar catalogue: 3,506 skills).
- Milestones 3–7 are not built yet. The recommendation flow, Circle wiring, Collaboration Room, worker, and completion loop are designed and scaffolded but not implemented.
- No authentication — single seeded creator, local demo only.
- Email delivery is Mailpit only; there is no real provider transport.
npm auditreports upstream advisories ineslint→brace-expansionandnext→postcss/sharpat their latest published versions. Not introduced by version pinning here; no non-breaking fix is available.
| Document | Contents |
|---|---|
CLAUDE.md |
Project instructions and spec |
docs/product-spec.md |
What CollabOS is, the seeded scenario, requirement mapping |
docs/architecture.md |
Responsibility split, process topology, key design decisions |
docs/implementation-plan.md |
Verified platform contract and stack decisions |
docs/security-and-approvals.md |
Approval matrix, secret handling, trust boundaries |
docs/test-plan.md |
Coverage map, what is real in each layer, bugs caught |
docs/demo-script.md |
Two-minute demo script with setup checklist |
docs/minds-smoke-test.md |
Generated Milestone 1 evidence |
docs/known-limitations.md |
Honest limitations and blockers |
docs/roadmap.md |
What would come next, and what is deferred by design |