Pinch — a local-first personal AI assistant

A personal AI assistant that runs on your own computer.
It reads your code, runs commands, remembers you, sends you reminders, and runs the tasks you schedule.
You talk to it from Telegram, Discord, Slack, WhatsApp — or your phone's browser, by voice.

_{Not the other Pinch projects. This is a personal AI assistant. It is unrelated to pinchtab (browser automation), abhinav/pinch (a Haskell serialisation library), Martin-Nyaga/pinch (process-engineering pinch analysis), YoussefAbdelkawy/Pinch (an Android widget) and Pinch Payments.}

Try it before connecting your accounts

Clone the repository, enter its directory, and run npm run demo with Node.js 22+. This uses a canned brain: it demonstrates the interaction flow, not a real model’s reasoning quality. You do not need a bot token or cloud API key for that demo. Demo mode disables the panel key and is not a security sandbox; keep it on a trusted local machine and do not expose or forward its port.

For real use, follow the guided setup below, then run npm run doctor and npm run brain. Try a harmless read-only question before granting approvals for file changes or commands. Local inference is the default; optional cloud providers and messaging services have their own data boundaries. Read the guide and security limitations before exposing the panel or enabling powerful tools.

Facts

Install it in two commands

git clone https://github.com/pinchfoundry/Pinch && cd Pinch
npm run setup     # one guided command: model → channels → voice → key
npm start         #     http://localhost:7777

npm run setup checks your model, writes .env, generates a key, and prints the URL to
open on your phone. No account. No cloud. Nothing to configure by hand.

Something not working? Two read-only checks, safe to run any time:

npm run doctor    # reads .env and calls each service: model, Telegram/Discord/Slack tokens, access key
npm run brain     # asks your model for a short reply and a tool call: speed, and whether it can use tools

No model installed? See the whole thing work right now, with a canned brain:

npm run demo

What it actually is

• An assistant that lives where your files are. Not a chat window with a browser
  plugin: it can read and write files, run commands, and search, up to 8 tool rounds per turn.
• Send it a file. Drop a PDF, a screenshot or a spreadsheet on the panel and ask
  about it — extracted in-process, never uploaded anywhere. No OCR for scans, and it
  says so instead of pretending.
• On your machine, with your model. Default is Ollama on the same laptop. Your
  conversations are JSON files in data/ — rm -rf data is a valid uninstall.
• Answers you can check. When it reads a file or searches the web, the reply cites what it
  actually used, and a citation that points at nothing is flagged rather than shown as a link.
• With a gate on anything destructive. Shell commands that could change something, file
  writes, screenshots and system actions stop and ask you first. Deny it and it genuinely does
  not run. Turning down the noise is deliberate: ls, cat, grep, git status and friends
  run straight through, and a command only earns that by passing a fixed read-only allowlist and
  keeping every path inside your workspace — so the worst case of a misjudgement is still a prompt.

You message it like a person, and it works like a very fast intern who has your laptop.

How it works

Five stages, and only one of them can touch your machine:

The two files that decide whether you trust this with a shell are
src/risk.js and src/guard.js. Both are short. Read them.

How this is different

Ask it things like

"scan ~/code and tell me which repos have uncommitted changes"
"this test is failing with a weird error — read it and fix it"
"remind me in 40 minutes to check the deploy" — it messages you back, in the same app
"remember I only deploy on Fridays" — it still knows next week
"what's on my screen right now?" — screenshot, then it reads it
"explain this stack trace" — dictated into your phone's mic

What's inside

24 built-in tools. The five that change something ask permission first. Add your own from a JSON manifest — no code, and every call still asks.

✅ = asks you first.

Why not just use ChatGPT?

Private by default

The honest version, not a paragraph of reassurance:

grep -r "fetch(" src/    # every outbound call in the product

It has been attacked on purpose

An assistant with a shell deserves more than "we take security seriously". The build was
attacked from the outside, six real defects were found, all six were fixed, and each one
has a regression test that fails on the old code.

npm run audit     # 14 probes, ~2 seconds, no model, no network — try it on your own install

Full method, results and what is still not fixed: docs/AUDIT.md.

Where you can talk to it

Documentation

Honest limits

• It can do anything you can do in a terminal, if you approve it. Narrow PINCH_WORKSPACE, read the command in the prompt.
• No GPU? A 7B model on CPU is 2–4 tokens/sec — usable, not pleasant.
• WhatsApp is unofficial and can get a number banned. Telegram does the same job, officially.
• The command screen is a denylist. Obfuscated commands still reach you for approval; that is the design.
• The tier check is a convenience, not a sandbox. It saves you prompts on ls and git status; it cannot contain a destructive command that looks read-only, so the deny rules and the approval gate still do the real work.
• More limits in the guide, including screenshots, voice notes and wake-word caveats.

_{MIT licensed · built to run on a laptop, in a room, for one person}

Maintainer

Ranjith Rosan maintains Pinch with its open-source contributors. Pinch is a local-first personal AI assistant published by Pinch Foundry; see the contributor history for everyone’s work.