open-shrimp

Claude Code in your pocket. No laptop required.

OpenShrimp puts a full Claude coding agent in Telegram — complete with file editing, tool use, and project awareness. It's the shrimp 🦐 to OpenClaw's lobster.

Small, personal, gets the job done.

Quick Start · Commands · Code Review · Scheduled Tasks · Voice Notes · macOS App · Deployment

OpenShrimp vs OpenClaw

Both are self-hosted and open source. They solve different problems.

TL;DR: OpenClaw is a Swiss Army knife for daily life. OpenShrimp is a scalpel for code — it does one thing and does it well.

OpenShrimp vs Claude Code Remote Control

Both let you use Claude Code from your phone. They take very different approaches.

TL;DR: Remote Control mirrors a terminal session to your phone. OpenShrimp is the session — always on, in Telegram, with a proper code review flow. No extra app required.

Why OpenShrimp?

You're away from your desk but need Claude to fix a bug, review a diff, or scaffold something quick. OpenShrimp gives you a proper Claude Code session from any Telegram chat — on your phone, your tablet, wherever.

• Real agent, not a chatbot. Claude can read, edit, and write files in your actual project directories. Full tool use, not just text completion.
• You stay in control. Every file mutation requires your explicit approval via inline keyboard buttons. One tap to approve, one tap to deny. Or hit "Accept all edits" when you trust the flow. When you're ready to commit, /review opens a swipe-based UI to stage exactly the hunks you want.
• Talk to it. Send a voice note and it gets transcribed automatically as a prompt — no typing needed. Great for quick instructions when you're on the go.
• Multiple projects, one bot. Switch between project contexts on the fly with /context. Each context has its own working directory, CLAUDE.md, model, and tool permissions.
• Persistent sessions. Pick up where you left off. Sessions survive restarts, and you can /resume any previous conversation.
• Forum topic support. Use Telegram forum channels to organize conversations — each topic thread gets its own independent Claude session. Run parallel tasks in the same chat without them stepping on each other. Claude auto-titles each topic for easy navigation.
• Container isolation. Run each context inside a Docker container with only the project directory mounted. On macOS, use Lima for full VM isolation via Apple's Virtualization.framework.
• Computer use. Enable a headless desktop inside the container — Claude can launch Chromium, click around, take screenshots, and interact with GUIs. Watch live via VNC.
• Group chat ready. Add the bot to a team chat. It responds to @mentions and replies, so it stays out of the way until you need it.
• Schedule recurring tasks. Tell Claude to check your repo every morning, monitor a CI pipeline, or run a one-shot task later — all via natural language. Tasks run in isolated sessions automatically.
• Watch background tasks. When Claude runs a long command in the background, tap "View output" to open a live terminal viewer right in Telegram.
• Locked down by default. User allowlist, path-scoped file access, and granular tool approval. The agent can't silently read your ~/.ssh or write outside your project.

Code Review

OpenShrimp includes a mobile-first code review UI built as a Telegram Mini App. Send /review to open it.

It works like Tinder for diffs — each hunk is a card. Swipe right to stage, left to skip, down to undo. You review at the hunk level, not the file level, so you can cherry-pick exactly the changes you want — like git add -p, but designed for your phone.

Voice Notes

Send a voice message instead of typing. OpenShrimp automatically transcribes it using Moonshine — a fast, lightweight speech-to-text model that runs locally. The transcribed text is sent to Claude as a prompt, prefixed with [Transcribed from voice note] so it knows the input came from speech.

The moonshine-stt binary is auto-downloaded on first use. No setup required.

Scheduled Tasks

Set up recurring or one-shot tasks that Claude runs automatically. Just describe what you want in natural language — "check for broken tests every morning at 9am", "summarize the git log every Friday", or "run this migration in 30 minutes".

Claude manages schedules via built-in tools. Use /schedule to see what's active or remove tasks. Scheduled tasks run in isolated sessions with read-only access, so they can report but not modify your code without a follow-up conversation.

Container Isolation

You can run each context inside a Docker container by adding a container: block to your context config. The Claude CLI runs inside the container with only the project directory bind-mounted — so it can't touch anything else on the host.

Session state is stored separately per context under ~/.config/openshrimp/containers/, so containerized contexts don't interfere with each other or your host ~/.claude.

On Linux, this uses Docker or libvirt VMs. On macOS, use backend: lima for full VM isolation via Apple's Virtualization.framework.

macOS App

On macOS, OpenShrimp is also available as a menu bar app. Download the .dmg from Releases, drag to Applications, and launch — no terminal needed.

• Lives in the menu bar (shrimp icon) with no Dock icon
• First-run setup wizard walks you through configuration with native macOS dialogs
• Start/stop the bot, open config, view logs — all from the menu bar
• "Start at Login" toggle for automatic launch

Note: The macOS app is currently unsigned. On first launch, macOS will block it — right-click the app and choose "Open" to bypass Gatekeeper, or go to System Settings → Privacy & Security and click "Open Anyway".

Quick Start

Prerequisites

• Claude Code CLI installed and authenticated (via claude login or an Anthropic API key)
• A Telegram bot token from @BotFather — we strongly recommend enabling Threaded Mode (Settings → Bot Settings → Threads Settings → Threaded Mode). This lets each conversation run in its own forum topic with an independent Claude session.

Option 1: Download Binary (recommended)

Grab the latest binary from Releases. No Python or package manager required — just download, configure, and run.

Note: The Linux binaries require glibc ≥ 2.39 (Ubuntu 24.04+, Debian 13+, Fedora 40+). On older distros, use the from-source install instead.

# Linux x86_64
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-linux-x86_64 -o openshrimp
# Linux ARM64
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-linux-aarch64 -o openshrimp
# macOS Apple Silicon
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-macos-aarch64 -o openshrimp

chmod +x openshrimp

On first run, the binary will automatically set up an isolated Python environment and install dependencies. If no config file exists, an interactive setup wizard walks you through creating one. Subsequent runs start instantly.

Option 2: From Source

Requires Python 3.11+ and uv.

git clone https://github.com/yjwong/open-shrimp.git
cd open-shrimp

# Build the web apps (requires Node.js 18+)
for app in review-app terminal-app markdown-app vnc-app; do
  (cd "web/$app" && npm install && npm run build)
done

# If you don't need the web features, create empty placeholders instead:
# for app in review-app terminal-app markdown-app vnc-app; do mkdir -p "web/$app/dist"; done

uv sync

Just like the binary, running uv run openshrimp without a config file will launch the interactive setup wizard. Or configure manually:

cp config.example.yaml ~/.config/openshrimp/config.yaml

Edit ~/.config/openshrimp/config.yaml with your bot token, Telegram user IDs, and project directories:

telegram:
  token: "YOUR_BOT_TOKEN"

allowed_users:
  - 123456789  # Your Telegram user ID

contexts:
  my-project:
    directory: /home/you/projects/my-project
    description: "My awesome project"
    model: claude-sonnet-4-6

default_context: my-project

Run

# Binary
./openshrimp

# From source
uv run openshrimp

# If using an API key instead of Claude Code login
ANTHROPIC_API_KEY=sk-ant-... ./openshrimp

If no config file exists, OpenShrimp starts an interactive setup wizard that walks you through creating one — no need to copy or edit YAML manually.

Or deploy as a systemd service for always-on access — see Deployment.

Commands

How Tool Approval Works

OpenShrimp enforces a layered permission model:

• Read-only tools (Read, Glob, Grep) — auto-approved within the context directory
• Write tools (Edit, Write) — always require manual approval via Telegram inline buttons
• Bash and other tools — configurable per-context via allowed_tools patterns (e.g., Bash(git *))
• Paths outside the context directory — always require manual approval, regardless of tool type

When a tool needs approval, you get three options: Allow (once), Accept all [tool] (auto-approve that tool for the session), or Deny. Edit/Write get the familiar "Accept all edits" button instead. All session-level approvals reset on /clear or context switch.

Deployment

The easiest way to deploy is with the built-in install command:

# Install as a systemd user service (Linux) or launchd agent (macOS)
openshrimp install

# Remove the service
openshrimp uninstall

This auto-detects your platform, finds the executable path, and sets everything up — including enabling lingering on Linux so the service runs without an active login session.

If you prefer to set up the service manually:

# ~/.config/systemd/user/open-shrimp.service
[Unit]
Description=OpenShrimp Telegram Bot

[Service]
ExecStart=/path/to/uv run openshrimp
# Only needed if not using Claude Code login:
# Environment=ANTHROPIC_API_KEY=sk-ant-...
Restart=always

[Install]
WantedBy=default.target

systemctl --user enable --now open-shrimp

License

MIT