ZYNKKK AI — Documentation

Overview

Zynkkk runs on one machine you control. It talks to you the way you already talk, proposes actions, and never sends a message or spends money without your approval — a rule enforced in code, not just asked of the model. It remembers your context across conversations, can research and fill forms in a guardrailed browser, and extends through the Model Context Protocol.

Features

✉

Message-first

Reach it over WhatsApp and iMessage. No new app — text it like a person.

channels: whatsapp, imessage

✓

Approval gate

Reads run freely; sends, deletes and changes wait for your yes.

if (consequential) awaitApproval()

◆

Any AI model

Bring your own API key. Claude is the default — swap in what you prefer.

bring your own AI key

⊞

Connect any MCP

Add any MCP server; its tools auto-register — read-only free, the rest gated.

mcp.add("gmail", "calendar")

▟

Persistent memory

People, projects and decisions remembered across sessions — a second brain.

memory.recall(context)

↗

Browser + web

Opens pages, reads them, fills forms — submitting only with your approval.

browse(url) · fillAndSubmit()

▣

Self-hosted

One process, one local SQLite file. Your keys and data never leave your machine.

storage: local sqlite

⚙

Custom agents

Start with the main agent, then build your own from the dashboard — no code.

agents.create()

How it works

1

Channels

You message zynkkk on WhatsApp or iMessage.

2

Coordinator

The agent reasons, calls tools, and drafts an action.

3

Approval gate

Anything consequential is held until you say yes.

4

Memory

The outcome is logged so it remembers next time.

Agents

Zynkkk ships with a ready-to-go main agent that works the moment you start it. Build your own custom agents — a coding agent, a research agent, a scheduler — each with its own instructions, tools and triggers. Agents can run on a schedule and reach any connected MCP server to actually get things done.

★

Starter main agent

Works out of the box. Handles every channel and hands off to your custom agents.

⚙

Build custom agents

Give each a name, instructions and tools — built-in or from any MCP server.

↻

Triggers & schedules

Run on message, prefix, a schedule, or when a matching event fires.

Schedule an agent — and let it use MCP to get things done

Set a schedule and the agent runs itself — no message needed. On each run it can reach out through any MCP server you've connected, then message you the result:

Agent:   "Morning briefing"
Trigger: daily at 08:00
Tools:   mcp__gmail__search_threads, mcp__calendar__list_events
Task:    "Summarize my unread email and today's meetings,
          then message me the briefing."

Read-only MCP tools run freely; if the agent wants to send or change something, it pauses for your approval — even on a scheduled run.

Dashboard

A local admin panel for everything — no code, no config files, no restarts.

localhost:4590

Settings

Agents

Knowledge

MCP

Queue

Traces

Cost

Channels

AI API keyset

WhatsAppconnected

iMessageconnected

Reply toneclear and friendly

MCP serversgmail · filesystem

Approval queue2 waiting

Everything the assistant does is controlled from here. Each tab, and what it lets you do:

⚙

Settings

Paste your AI API key (any model), set the reply tone, toggle features. Read live — no files.

☶

Channels

Turn WhatsApp/iMessage on or off, scan the WhatsApp QR, watch live connection status.

◉

Agents

Create, edit and delete agents — instructions, tools, and how each one triggers.

⊞

MCP

Add any MCP server by URL or command; its tools auto-register — read-only free, rest gated.

✓

Queue

Approvals come to your chat; the Queue tab is an optional mirror to review, edit, approve or reject.

▟

Knowledge

Browse the second-brain knowledge graph — people, projects and decisions it has learned.

☰

Traces

Step-by-step record of every agent run: reasoning, tool calls, outcome. Self-hosted.

▪

Cost

Track spend today, this month and all-time, with a per-model breakdown. Priced locally.

Install & setup

0

Prerequisites

Node.js 20+, git, and macOS for the iMessage channel. Grab an API key from your AI provider (Claude by default).

1

Clone the repo

git clone https://github.com/thetpmguy/zynkkk.git
cd zynkkk

2

Install dependencies

npm install

3

Start zynkkk

npm start

Boots the assistant and its local dashboard.

4

Open the dashboard

http://localhost:4590

Channels, settings, agents, MCP servers, and the approval queue.

5

Add your AI API key

In Settings, paste your AI API key (any model). Claude is the default.

6

Link WhatsApp

In Channels, scan the QR with WhatsApp → Linked devices. iMessage works on macOS with Full Disk Access.

7

Keep it always-on

npm run supervise

A watchdog restarts it if it ever stops.

Plug & play MCP

Zynkkk speaks the Model Context Protocol. Add any MCP server from the MCP tab — give it a command, and every tool it exposes shows up instantly. Read-only tools run freely; sends, deletes and changes are gated. Example — connect Gmail:

# 1. authorize once (opens your browser)
npx @gongrzhe/server-gmail-autoauth-mcp auth

# 2. in the dashboard MCP tab, add a server:
#    command: npx
#    args:    -y @gongrzhe/server-gmail-autoauth-mcp

Search, read, label, draft and send become available — with sending and changing gated behind your approval.

Run it 24/7

Zynkkk is meant to stay on. A Mac mini is ideal — cheap, silent, low-power, and it runs the iMessage channel natively. Keep it running with the built-in watchdog:

npm run supervise

It restarts zynkkk automatically if it stops. Because zynkkk is message-first, the Mac mini does the work at home while you reach it from your phone — anywhere.

Troubleshooting

WhatsApp won't link

If pairing fails repeatedly, wait a few minutes — WhatsApp throttles rapid re-links — then rescan the fresh QR.

iMessage is empty

Grant your terminal Full Disk Access in System Settings → Privacy & Security, then restart zynkkk.

Node version error

Zynkkk needs Node 20+. Check with node -v and upgrade if needed.

No replies

Make sure your AI API key is saved and the Channels tab shows connected.

MCP tool missing

Re-check the server's command and args in the MCP tab; a red status means it couldn't start.

Port in use

Something on 4590? Set UI_PORT to a free port before starting.