BlueOctopusDocs Download
Documentation · version 0.1.0

BlueOctopus documentation

Install BlueOctopus, read its alerts, and decide what each AI agent may see. Everything here applies to the free preview for Mac and Windows.

Overview

BlueOctopus shows you every personal file an AI agent opens on your computer, and warns you when something sensitive is read or sent away.

AI agents such as Claude Code, Cursor and ChatGPT can read files on your computer. Antivirus treats them as ordinary apps, and a firewall only sees network traffic, so nothing tells you that an agent just opened your bank statement. BlueOctopus watches the agents, labels each file they open, and alerts you about the sensitive ones.

It runs entirely on your computer. There is no account, no cloud service and no telemetry.

Install on Mac

Needs macOS 13 Ventura or later on an Apple Silicon Mac (M1 or later). The download is about 196 MB.

  1. On the download section, choose Download for macOS to get BlueOctopus-0.1.0-arm64.dmg.
  2. Open the .dmg and drag BlueOctopus into Applications.
  3. The first time, right-click BlueOctopus in Applications and choose Open, then Open again. This preview isn't notarised by Apple yet, so a normal double-click is refused once.
  4. The BlueOctopus window opens and the octopus icon appears in the menu bar. Protection starts straight away.

No administrator password is needed. Everything BlueOctopus needs, including its own Python and the model, is inside the app.

Install on Windows

Needs Windows 10 (22H2) or Windows 11 on an x64 PC. The download is about 194 MB. Windows is in beta.

  1. Choose Download for Windows to get BlueOctopus-0.1.0-x64.zip.
  2. Right-click the zip, choose Extract All, and pick a folder you'll keep, such as Documents\BlueOctopus.
  3. Open BlueOctopus.exe. If Windows says it protected your PC, choose More info, then Run anyway. The beta isn't signed yet.
  4. The window opens and the BlueOctopus icon appears in the system tray, next to the clock.
Windows beta. File watching, labels, alerts and trap files work. Leak alerts and blocking folders for Claude Code are Mac only for now.

First run

The Overview page shows today's numbers: files opened by AI, how many were sensitive, data sent right after a sensitive read, and trap files opened. Below that are the alerts that need your attention and a chart of the week.

A blue box at the top tells you if anything needs doing. On a Mac you'll usually see Claude Code isn't connected; see Connect Claude Code.

Closing the window doesn't stop protection. BlueOctopus keeps watching from the menu bar or tray. To stop it, choose Quit BlueOctopus from that icon.

How it works

1. Recognise the agents

BlueOctopus recognises AI agents by their programs and follows every process they start. If Claude Code runs cat, grep or a Python script, a file opened by that command is counted as Claude Code's.

2. See which files they open

Twice a second it lists the files each agent holds open. On a Mac connected to Claude Code it also gets every file Claude Code is about to read, before it reads it.

3. Label each file

Only files in your home folder count. App data (~/Library on Mac, AppData on Windows), code dependencies and the programs agents run are skipped. Each remaining file gets a label from two parts: rules that find exact things such as Aadhaar or card numbers, and a small model that recognises the type of document. Labels are cached, so a file is only read again when it changes.

4. Log or alert

Every access goes into the activity log. High and critical files also raise a notification.

Sensitivity levels

LevelMeaningExamples
CriticalCould cause real harm if it leaked. Always alerts.Aadhaar or passport copies, card numbers, API keys and passwords, medical records, trap files
HighClearly personal or financial. Alerts by default.Bank statements, salary slips, marksheets, private diaries
MediumPersonal, but lower risk. Logged.Resumes, unpublished papers, files with a phone number or email
LowBarely personal. Logged.Notes with a name in them
NoneNothing personal found. Logged quietly.Source code, recipes, configuration files

You can raise the alert threshold to critical only in Settings.

What it recognises

Document types (35)

GroupTypes
IdentityAadhaar, PAN, passport, driving licence, voter ID, other ID
FinanceBank statement, salary slip, tax document, cheque, investment, loan, invoice
LegalContract, NDA, property, court
EmploymentOffer letter, resume, HR record
MedicalPrescription, lab report, insurance, medical record
EducationMarksheet, student records, exam paper, admission
WorkUnpublished paper, grant proposal, confidential
PersonalSignature, ID photo, family

Anything that fits no type still gets a personal score from 0 to 1, so a private note or diary is flagged even without a category.

Details found inside files

Numbers with a check digit are verified, so random digits don't trigger alerts: Aadhaar (Verhoeff), card numbers (Luhn) and GSTIN.

AadhaarPANPassportVoter IDDriving licenceABHAUANGSTINBank accountIFSCUPI IDCard numberPhoneEmailAddressDate of birthGradesHealth

Secrets

AI API keysCloud keysPrivate keysDatabase URLs.env filesJWTsGit tokensChat tokensPayment keysPasswordsRecovery codes

Text, Word, Excel, PowerPoint, CSV and .env files are read on both systems. On a Mac, PDFs, photos and scans are read too, with Apple's on-device text recognition. On Windows, PDFs and images are not read yet.

Supported AI agents

Claude CodeClaude DesktopChatGPTCodex CLICursorWindsurfGitHub CopilotGemini CLIOllamaLM StudioAiderGooseopencodePerplexity

Every command and MCP server these agents start counts as theirs. The AI Agents page shows which are running now and how many files each opened today.

Cursor and Windsurf are editors too, so files you open yourself in them are also logged.

Alerts and the activity log

When an agent opens a high or critical file, you get a notification such as Claude Code opened a critical file, with the file name and folder. Click it to open the file's details in BlueOctopus. The same file and agent alert at most once every 10 minutes.

The Activity page lists every file an AI opened, newest first, with the time, the agent and the command it used, the file, its type and level. Filter it to Sensitive or Trap Files, or search by file or agent name.

Select a row to see the details: what was found inside (counts only, never the values), the folder rule, and whether data was sent soon after. From there you can block that agent from the folder or mark the file as allowed.

Protected folders

On the Folders page, give each folder a rule:

RuleWhat it does in 0.1.0
PrivateClaude Code is blocked from reading files in the folder (Mac, after connecting Claude Code). Every agent's access is still logged and alerted.
AskSaved for a later version that will ask before each read. Today it logs and alerts as usual.
AllowedSaved for a later version that will log quietly. Today it logs and alerts as usual.

Add a folder by typing its path, for example ~/Documents/Tax, and choosing Protect Folder. Choosing Block on an alert marks that file's folder Private.

Connect Claude Code

Mac only. Lets BlueOctopus see every file Claude Code reads and stop it from reading Private folders.

  1. Choose Connect Claude Code… in the blue box on Overview, or from the menu-bar icon.
  2. Confirm. BlueOctopus adds a hook to ~/.claude/settings.json and saves a copy of your old file as settings.json.bak-blueoctopus. Your other settings and hooks are kept.
  3. Restart any open Claude Code sessions.

When Claude Code tries to read, edit or search a file in a Private folder, the hook refuses and Claude Code is told the folder is blocked.

Trap files

Trap files are decoys, such as passwords.txt, bank_login.txt and aadhaar_scan_copy.txt. They contain no real data and no real task needs them, so an AI that opens one is looking around where it shouldn't.

On the Trap Files page, choose Plant Trap File… to place the three decoys in your Documents folder. Opening one raises a critical alert marked Trap. Removing a trap deletes only the decoy BlueOctopus created, and never a real file with the same name.

Leak alerts

Mac only in 0.1.0.

BlueOctopus counts the data each agent sends to the internet. If an agent reads a high or critical file and sends 2 KB or more within the next 90 seconds, you get a possible data leak alert with the amount and where it went.

It can't see inside encrypted traffic, so it can't prove the file itself was sent. Agents like Claude Code send what they read to their AI service, so after a sensitive read the alert is usually right.

Settings

Open Settings with the gear button in the toolbar.

  • General: open at login, show the count in the menu bar, log code files quietly.
  • Alerts: the lowest level that notifies you (high or critical), sounds, and leak alerts.
  • Detection: how files are seen. The app uses basic polling, plus the Claude Code hook when connected.
  • Model: which model version labels your files.

The pause button in the toolbar, or Pause Protection in the menu-bar icon, stops watching until you resume.

Your data and privacy

Nothing leaves your computer. BlueOctopus has no account, sends no telemetry, and never uploads files or labels. The model runs locally.

What it stores, in one folder:

  • The activity log: time, agent, file path, level and document type.
  • Labels for files it has checked, with counts of what was found (for example gov.pan ×1), never the numbers themselves.
  • Your folder rules, trap list and settings.
SystemData folder
Mac~/Library/Application Support/BlueOctopus
Windows%APPDATA%\BlueOctopus

The on-device model

A small transformer trained from scratch to recognise personal documents. It reads the start of each file as raw bytes, so it works with any language or script.

Parameters4.9 million (about 19 MB)
Training data15,840 synthetic documents. No real personal data was used.
Correct document type86.9% on 3,947 held-out documents with layouts it never saw
Personal files found99.5% (recall), with 96.8% precision
Runs onApple's MLX on Mac; NumPy on Windows, with identical results

These figures come from synthetic test documents. Expect lower accuracy on real files until it's tested more widely. Rules catch exact details such as Aadhaar and card numbers whatever the model says.

Limits of the preview

  • Polling checks twice a second, so a file opened and closed faster than that, such as a quick cat, can be missed. Claude Code on a connected Mac is the exception, because its hook sees every read.
  • Blocking works only for Claude Code on Mac. Blocking every agent needs Apple's Endpoint Security permission on Mac and a signed driver on Windows. Both are planned.
  • Leak alerts are Mac only.
  • On Windows, PDFs and images are not read yet, so their contents are not checked.
  • The model reads the first part of each file, so details deep inside a long document are found by the rules but may not change its type.
  • The Mac app needs Apple Silicon. Intel Macs are planned.
  • Neither app is signed yet, which is why the first launch needs an extra click.

Troubleshooting

"Running on rules only"

The model couldn't start, so only the rules are labelling files. Quit and reopen BlueOctopus. If it stays, reinstall the app.

"The watcher stopped"

The background watcher stopped more than four times in a minute. Choose Open Data Folder and look at engine-data/watcher.log. Quitting and reopening BlueOctopus starts it again.

A file an agent opened isn't listed

It was probably opened and closed in under half a second. On a Mac, connect Claude Code so every read by Claude Code is seen. Files in app-data folders and program files are skipped on purpose.

macOS says the app can't be opened

Right-click BlueOctopus in Applications and choose Open. You only need to do this once.

Windows says it protected your PC

Choose More info, then Run anyway.

See the watcher's log

# Mac
tail -n 30 ~/Library/Application\ Support/BlueOctopus/engine-data/watcher.log

# Windows (PowerShell)
Get-Content "$env:APPDATA\BlueOctopus\engine-data\watcher.log" -Tail 30

Uninstall

Mac

  1. Choose Quit BlueOctopus from the menu-bar icon.
  2. If you connected Claude Code, open ~/.claude/settings.json and remove the hook that mentions hook.py, or restore settings.json.bak-blueoctopus.
  3. Delete planted trap files from the Trap Files page first, then move BlueOctopus from Applications to the Bin.
  4. To remove your activity log and settings, delete ~/Library/Application Support/BlueOctopus.

Windows

  1. Remove planted trap files from the Trap Files page, then choose Quit BlueOctopus from the tray icon.
  2. Delete the folder you extracted BlueOctopus into.
  3. To remove your activity log and settings, delete %APPDATA%\BlueOctopus.

Release notes

0.1.0 · preview

  • First release for Mac (Apple Silicon) and Windows (beta).
  • Live activity log, notifications, menu-bar and tray icon.
  • On-device model with 35 document types, plus rules for Indian ID, financial details and secrets.
  • Protected folders with Claude Code blocking, trap files, and leak alerts on Mac.