ZYNKKK AI

[ what is zynkkk ]

// your own AI assistant — self-hosted, plug & play class zynkkk { function assist() { return "you message it, it acts — only after you approve"; } }

Zynkkk is an open-source AI assistant you run on your own machine. It talks to you the way you already talk — over WhatsApp and iMessage — proposes what it wants to do, and waits for your approval before anything consequential happens. It remembers your context across every conversation. Bring any AI model's API key (Claude is the default), and connect any MCP server to give it new powers. Clone it, run it, own it.

[ features ]

>

Message-first

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

channels: whatsapp, imessage

>

Approval gate

Nothing consequential runs without your yes. Reversible reads happen freely; sends, deletes and changes wait for you.

if (consequential) awaitApproval()

>

Any AI model

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

bring your own AI key · any model

>

Connect any MCP

Plug in any Model Context Protocol server. Its tools auto-register — read-only tools run free, the rest ask first.

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

>

Persistent memory

Decisions, people and projects are remembered across sessions — your assistant builds a second brain.

memory.recall(context)

>

Browser + web

It can open pages, read them, and fill forms — clicking submit only with your approval.

browse(url) · fillAndSubmit()

>

Self-hosted

Runs entirely on your machine. Your keys and data stay in a local database — nothing leaves without you.

storage: local sqlite

>

Custom agents

Start with the built-in main agent, then build your own specialized agents from the dashboard — no code.

agents.create() · schedule.cron()

[ agents & dashboard ]

Zynkkk ships with a ready-to-go main agent — the coordinator that reads your messages, calls tools, and drafts actions. It works the moment you start it, no setup required. When you want more, create your own custom agents — a coding agent, a research agent, a scheduler — right from the dashboard, no code needed.

The dashboard is your control room — everything below is editable in the UI:

>

Starter main agent

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

>

Build custom agents

Define specialized agents with their own instructions and tools — created and edited in the UI.

>

Edit everything

Channels, MCP servers, settings, schedules, memory and the approval queue — all editable in the dashboard.

[ how it works ]

01

Channels

You message zynkkk on WhatsApp or iMessage.

02

Coordinator

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

03

Approval gate

Anything consequential is held until you say yes.

04

Memory

The outcome is logged so it remembers next time.

[ install & setup ]

00

Prerequisites

You'll need Node.js 20+, git, and macOS if you want the iMessage channel. Grab an API key from your AI provider (Claude by default).

01

Clone the repo

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

02

Install dependencies

npm install

03

Start zynkkk

npm start

This boots the assistant and its local dashboard.

04

Open the dashboard

http://localhost:4590

Your control panel: channels, settings, agents, MCP servers, and the approval queue.

05

Add your AI API key

In Settings, paste your AI API key (any model). Claude is the default — point it at whichever model you use.

06

Link WhatsApp

Open the Channels tab and scan the QR code with WhatsApp → Linked devices. iMessage works automatically on macOS once you grant your terminal Full Disk Access.

07

Keep it always-on

npm run supervise

Runs zynkkk under a watchdog that restarts it if it ever stops — so it's there whenever you message.

[ plug & play mcp ]

Zynkkk speaks the Model Context Protocol. Add any MCP server from the MCP tab — give it a command to run, and every tool it exposes shows up instantly. Read-only tools (search, list, read) run freely; anything that sends, deletes or changes something is held for your approval automatically.

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

That's it — search, read, label, draft and send become available, with the sending and changing tools gated behind your approval.

[ run it 24/7 ]

Zynkkk is meant to stay on. Point it at any always-on machine and it's there whenever you message. A Mac mini at home is ideal — cheap, silent, low-power, and it runs the iMessage channel natively.

Keep it running around the clock with the built-in watchdog:

npm run supervise

It restarts zynkkk automatically if it ever 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 reopen the Channels tab and scan 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 or newer. Check with node -v and upgrade if needed.

!

No replies

Make sure your AI API key is saved in Settings 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 the process couldn't start — the logs there show why.

!

Port in use

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