ZYNKKK AI

_

Get started View on GitHub
Overview

What is zynkkk

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.

Human-in-the-loop, always. Nothing consequential is sent or spent without your explicit approve — and that rule is enforced in code, not just asked of the AI.

Features

Everything it can do

Message-first, self-hosted, and extensible.

✉

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. 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 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

A starter agent, and a UI to build more

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 — 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 when needed.

⚙

Build custom agents

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

↻

Triggers & schedules

Run an agent when you message it, via a prefix, on a schedule, or when a matching event fires.

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

Set a schedule (every N minutes, or daily at a set time) and the agent runs itself — no message needed. On each run it can reach out through any MCP server you've connected to actually do the work, then message you the result. For example, a morning briefing that reads your email and calendar and texts you the rundown:

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 (search, list, read) run freely. If the agent wants to send or change something, it pauses and asks for your approval first — even on a scheduled run.

Dashboard

Your admin panel

A local, browser-based control 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 assistant's reply tone, and toggle features. Everything is read live — nothing to edit in files.

☶

Channels

Turn WhatsApp and iMessage on or off, scan the WhatsApp QR to link your phone, and watch each channel's real-time connection status.

◉

Agents

Create, edit and delete custom agents — name, instructions, the tools each may use, and how it triggers (message, prefix, schedule, or event).

⊞

MCP

Add any MCP server by URL or local command and connect it. Its tools auto-register for your agents — read-only run free, the rest are gated.

✓

Queue

Approvals come straight to your chat — reply approve or reject right in WhatsApp/iMessage. The Queue tab is an optional mirror: review, edit or decide from here if you prefer. You never have to open the dashboard.

▟

Knowledge

Browse the second-brain knowledge graph — the people, projects and decisions the assistant has learned and connected across conversations.

☰

Traces

A step-by-step record of every agent run: the reasoning, each tool call, and the outcome. In-house and self-hosted — no external service.

▪

Cost

Track exactly what the AI spends — today, this month and all-time — with a per-model breakdown of calls and tokens. Priced locally, no billing key.

How it works

From your message to a safe action

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.

Install & setup

Up and running in ~5 minutes

0

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).

1

Clone the repo

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

Install dependencies

npm install
3

Start zynkkk

npm start

This boots the assistant and its local dashboard.

4

Open the dashboard

http://localhost:4590

Your control panel: 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 — point it at whichever model you use.

6

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.

7

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

Connect any system

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

Perfect on a Mac mini

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

Common fixes

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.

Clone it. Run it. Own your assistant.

Open source. Self-hosted. Yours.

$ git clone Read the setup