Overview
Zuko has two parts. The desktop app protects Claude Code (in the terminal or in VS Code) and gives you clipboard and document masking. The browser extension protects ChatGPT, claude.ai and DeepSeek. You can use either one alone.
1. Install the app
- Download
Zuko-Windows-0.1.1-setup.exeand run it. It installs for your user only and needs no admin rights. - Windows may say "Windows protected your PC" because the app is not code-signed yet. Click More info, then Run anyway.
- Zuko appears as a small island at the top of your screen. Move your mouse to the island and click Zuko to open it. The gear opens Settings.
2. Turn on protection for Claude Code
- Open Settings → Protection.
- Switch on Hooks and Gateway. Optionally switch on Deny rules too.
- Click Review changes…. You see the exact change Zuko will make to
~/.claude/settings.jsonand the name of the backup it takes first. Click Apply. - Restart Claude Code: close and reopen the terminal session or the VS Code panel. The status dots in Settings → Protection turn green.
| Option | What it does |
|---|---|
| Hooks | Your rules, risk levels and plain-English approval cards on every tool call the agent makes. |
| Gateway | Routes Claude Code through Zuko on your PC, so secrets are masked before anything reaches the cloud. Works with a Claude Pro or Max login and with API keys. |
| Deny rules | Copies your blocked paths and domains into Claude Code's own deny list, which holds even when Zuko is closed. |
3. Add the browser extension
- Download
Zuko-Extension-0.1.1.zipand unzip it to a folder you will keep, for exampleDocuments\Zuko-Extension. - Open
chrome://extensions(oredge://extensions) and switch on Developer mode. - Click Load unpacked and choose the unzipped Zuko-Extension folder.
- With the Zuko app running, press the reload button on the Zuko card once. The extension popup then shows Desktop app: linked, and it links by itself from then on.
The extension also works without the app. Linked, both share one vault, so a key masked in Claude Code is the same {{API_KEY_1}} in ChatGPT.
4. Try it
Make an empty folder, open Claude Code in it, and paste these prompts. All the values are fake.
Secrets stay on your PC
Create a file called reminder.txt with a short payment reminder for our customer Rahim Uddin. Include his phone +880 1712-345678, email rahim@acme-demo.io and the card on file 4242 4242 4242 4242.You should see: Zuko says "Masked 3 secrets before they left". See what was sent shows {{PHONE_1}}, {{EMAIL_1}} and {{CARD_1}}, yet reminder.txt has the real values.
API keys never reach the AI
My OpenAI API key is sk-proj-ZUKO-FAKE-2f9x7Qm4Lp8Rt2Vw6Yz1Ab3Cd5Ef. Add it to a .env file as OPENAI_API_KEY.You should see: only {{API_KEY_1}} leaves your PC, and .env gets the real key.
Look before you say yes
Delete the old_build folder and everything in it.You should see: a red card that says in plain English what will be deleted. A quick click does nothing: you have to hold Allow.
Your rules
Fetch https://www.imdb.com/chart/top/ and tell me the top 3 movies.You should see: Zuko blocks the request, and Claude says the site is on your blocked list.
Web chats
In ChatGPT, claude.ai or DeepSeek, type a message with a fake card or key and send it. A Zuko notice shows what was masked. Press Alt+R to switch between your view and what the AI actually received.
Your rules
Settings → Policy starts with sensible defaults. For example pastebin.com, webhook.site and *.ngrok.io are blocked, ~/.ssh cannot be read, and git push --force is blocked. Add your own:
- Blocked domains: sites the agent may never contact.
- Blocked folders: places the agent may never read, like
D:\Personal. - Blocked commands: patterns such as
git push --force*. - Custom words: client names or codenames to mask like any other secret.
Click Save policy. Rules apply to the very next action. Switch Mode to Monitor if you only want to log decisions without blocking.
Shortcuts
| Keys | What it does |
|---|---|
| Ctrl+Alt+M | Masks the text on your clipboard, so you can paste it safely into any app. |
| Ctrl+Alt+U | Puts the real values back into the text on your clipboard. |
| Alt+R | In a web chat: switch between your view and what the AI received. |
Everyday use
| Task | How |
|---|---|
| Open Zuko | Move the mouse to the island at the top of the screen and click Zuko. The gear opens Settings. |
| Move the island | Drag its header along the top edge. Double-click the header to centre it again. |
| Mask a document | Drop a .txt, .md, .pdf or code file on Zuko, or use Settings → Documents. You get a masked copy that is safe to share. |
| See what happened | Settings → Activity lists every masked secret and every decision. |
| Pause approval cards | Tray icon → Pause protection prompts. Your rules still apply. |
| Quit | Right-click the Zuko tray icon → Quit. |
Island chat (optional)
Zuko has a small chat of its own. In Settings → Chat, choose Claude, OpenAI or Local (Ollama). Claude and OpenAI need your own API key, which is kept in Windows Credential Manager, and they only ever see masked text. With Ollama no key is needed and nothing leaves your PC.
Local AI (optional)
Patterns catch keys, cards and phone numbers. To also find people's names and street addresses, Zuko can ask a small AI model that runs on your own PC.
- Install Ollama and download the model (about 3.3 GB):
ollama pull gemma3:4b - In Settings → Local AI, switch it on, choose
gemma3:4b, click Save, then Test.
A scan takes a few seconds on a typical laptop. The local AI can only make Zuko stricter, never looser.
Turning Zuko off
Before you quit Zuko for good or uninstall it, undo its changes to Claude Code:
- Open Settings → Protection and switch everything off.
- Click Review changes…, then Apply. Your previous settings come back exactly as they were.
- Restart Claude Code. You can now quit or uninstall Zuko (Windows Settings → Apps).
To remove the extension, open chrome://extensions and click Remove on the Zuko card.
Troubleshooting
Claude Code cannot connect
Gateway is on but Zuko is not running. Start Zuko, or turn Gateway off in Settings → Protection, apply, and restart Claude Code.
Nothing happens in Claude Code
Restart Claude Code after clicking Apply. Then check that Settings → Protection shows Hooks as installed.
The extension says "Desktop app: not linked"
Keep Zuko running and check that Settings → Browser shows the bridge as registered (press Register if not). Then press reload on the extension card. It also finds the app by itself within about 30 seconds.
Windows says "Windows protected your PC"
The installer is not code-signed yet. Click More info, then Run anyway. You can check the file against the SHA-256 checksum on the Download page.
A secret was not masked
Detection is pattern-based, so an unusual format can slip through. Add it under Settings → Policy → Custom words, or switch on the optional Local AI for names and addresses.
Where your data lives
Everything stays on your PC.
| Path | What |
|---|---|
%APPDATA%\Zuko\policy.json | Your rules |
%LOCALAPPDATA%\Zuko\vault.bin | Masked values, encrypted with XChaCha20-Poly1305. The key is in Windows Credential Manager. |
%LOCALAPPDATA%\Zuko\audit\ | The hash-chained audit log. It never contains secret values. |
%LOCALAPPDATA%\Zuko\inbox\ | Files you dropped on Zuko and their masked copies |
FAQ
Does anything leave my PC?
Only what you already send to your AI, with the secrets replaced by placeholders. Zuko has no server, no account and no telemetry.
Is Zuko free?
Yes. It is free and open source under the MIT License, with no subscription and no cloud bill.
Will the AI still understand my request?
Yes. Zuko tells the model what each placeholder is, for example that {{API_KEY_1}} is an OpenAI API key, so it can still do the work. Only answers that depend on the actual value, like "is this key valid?", are not possible.
Which systems are supported?
The desktop app runs on Windows 10 and 11. The browser extension runs in Chrome and Edge.
Can I build it myself?
Yes. The full source and build steps are on GitHub.