Tarsee

Tarsee is built for Claude Max subscribers. It runs a persistent Claude Code agent that uses your subscription for every message. Pro subscribers will hit usage limits quickly — Max (especially 5x) is strongly recommended for daily use.

Why Tarsee?

I was using OpenClaw to run Claude Code 24/7. It worked — until Anthropic changed their billing so OAuth tokens used through these wrappers started counting against your subscription usage. That's fine, but the resource overhead was heavy for what I needed.

I just wanted Claude Code running 24/7 that I could talk to from my phone. So I wrapped the Claude Code SDK directly and built a lightweight frontend. No build step, no TypeScript compile, no framework overhead.

Haven't looked into Claude Cowork yet, but if you love Claude Code and want it always on from any device, this is it.

How Tarsee Compares

Being honest — some of these projects are massive with huge communities. Tarsee is small and focused. Here's where it fits:

Why choose Tarsee?

• You want simplicity — no build step, no TypeScript, no framework. Just Node.js serving HTML.
• You want Claude specifically — Tarsee wraps Claude Code SDK directly. Not multi-provider, not trying to be everything.
• You want it cheap — runs on $2-10/mo Railway. No API costs with Claude Max.
• You want voice + mobile — PWA with local speech-to-text, hold-to-talk, iOS PIN pad login.
• You want memory — persistent memory across sessions with deep semantic search.
• You want browser automation — stealth Playwright with captcha solving built in.

Why choose something else?

• You need 20+ channels — OpenClaw or PicoClaw support way more platforms.
• You need native mobile apps — OpenClaw has actual iOS/Android apps.
• You need multi-provider — PicoClaw supports 30+ LLMs. Tarsee is Claude-only.
• You need minimal resources — PicoClaw runs on <10MB RAM. Tarsee needs ~200MB.
• You want a massive community — OpenClaw has 353K stars and thousands of contributors.

Tarsee is a Claude Code wrapper — not a fork, not a rewrite. It uses @anthropic-ai/claude-agent-sdk directly, so you get the exact same Claude Code experience with all built-in tools (Read, Write, Edit, Bash, Grep, Glob) plus Tarsee's own tools on top.

Quick Start (Railway)

1. Click Deploy on Railway above
2. Change the SETUP_PASSWORD — this is your 4-digit PIN to access the web UI. Everything else is pre-configured.
3. Deploy — open the URL, log in with your PIN
4. The setup wizard will guide you through connecting your Claude account:
   • Click "Open Tarsee's Terminal" — this opens a terminal on the server (not your local machine)
   • Click inside the terminal, then type claude login
   • A login link will appear — highlight it and right-click → Copy (Ctrl+C won't work in the terminal)
   • Open the link in your browser and authenticate with your Claude Max account
   • Come back and click "I'm connected" — done!

That's it. Credentials are stored on the Railway volume and auto-refresh. No env vars to manage. Claude Code CLI auto-updates on every restart.

Authenticating with Claude

You need an active Claude Max subscription with Claude Code enabled. Max is strongly recommended — Pro will hit usage limits with a persistent agent.

Credentials are saved to the Railway volume at /data/tarsee/.claude-code-home/.credentials.json and persist across restarts, redeploys, and image rebuilds. The SDK auto-refreshes tokens — you only need to log in once. If you ever get logged out, just run claude login again from the terminal (icon in topbar).

Why not an env var? OAuth refresh tokens are single-use. If you set credentials as an env var, every redeploy overwrites the SDK's refreshed token with the stale original, causing auth failures. Logging in directly on the server avoids this entirely.

Staying Updated

If you deployed from the Railway template, your instance is a snapshot — it won't auto-update. To get the latest features:

1. Go to your Railway service → Settings → Source
2. Connect it to projectservan8n/Tarsee on GitHub
3. Every push to main will auto-deploy to your instance
4. Your data on /data is safe — the volume persists across redeploys

What You Get

Chat Everywhere

• Web UI — Full chat with markdown rendering, code blocks, tables, file attachments, image paste, drag-and-drop, multi-file upload. PWA — save to homescreen on iOS/Android.
• Telegram — Text, photos, PDFs, voice messages, video notes. Group @mention support, inline buttons, forwarded message detection.
• Discord — Text, images, PDFs, voice messages. Always-online bot with presence status.
• Email — Real-time over IMAP IDLE + SMTP. Mention keyword (default @tarsee) gates replies; CC/BCC/forwards are absorbed as context without an outbound. Works with any mailbox you own (Gmail, Outlook, iCloud, Zoho, FastMail, Yahoo, self-hosted).
• WhatsApp — Text, images, PDFs, voice notes (Whisper-transcribed), and documents via WHAPI Cloud (free tier OK). Direct messages only. Per-channel webhook secret in URL, auto-generated on first enable.
• Attachment save-to-disk — every image, PDF, voice note, and document sent via Discord, Telegram, email, WhatsApp, or web lands in workspace/uploads/ so Claude can read, transform, and reference it across turns (not just in the message it arrived on).
• Cross-device sync — all devices update in real-time via WebSocket. See tool calls, text streaming, and typing indicators across devices.
• Session recap — resume a conversation idle >30 min and a dismissible "Last time" card summarizes the last few exchanges before the first new message. Zero AI cost (extractive summary).
• Web Push notifications — iOS/Android/desktop push via VAPID when cron jobs finish, webhooks fire, or Claude proactively pings you via the tarsee_push_notification MCP tool. Opt-in from Settings > Appearance.
• All channels share the same AI, memory, and tools.

Voice Mode

• Hold-to-talk or tap-to-toggle — full-screen conversational UI with waveform visualization.
• Live tool status — shows "Reading file...", "Running command...", "Calculating..." instead of generic "Thinking..."
• Spacebar shortcut — hold space to talk, Space+C to cancel.
• Drag to cancel — slide away from the orb or mic button to discard recording.
• Local speech-to-text — faster-whisper (CTranslate2, 4x faster than OpenAI whisper). Configurable models: tiny.en / base.en / small.en. No API key. Runs on CPU.
• Free text-to-speech — Microsoft Edge TTS with 19 voices, 3 retries, markdown stripping. No API key, no rate limits.
• Smart TTS — tables and code shown visually, spoken response is a clean conversational summary.

Canvas / Artifacts

• Live HTML/CSS/JS — Ask for a dashboard, chart, calculator, or mini-app → renders as an interactive iframe right in chat.
• Canvas gallery — browse all your canvases at /canvas/.
• Persistent — Canvases are saved to the volume and accessible at /canvas/<id>/.

Tools & Automation

• 20+ MCP tools — send messages, schedule tasks, remember facts, search the web, create canvases, manage files, encrypted vault, calculator, browser, push notifications, email threads, and more.
• Calculator — precise math tool so Claude never hallucinates numbers. Arithmetic, percentages, Math.* functions.
• Stealth browser — Playwright with anti-detection (real fingerprints, no webdriver flag). Navigate, fill forms, screenshot, scroll, wait, run JS.
• Captcha solver — auto-detect and solve reCAPTCHA, hCaptcha, Cloudflare Turnstile via 2Captcha or Capsolver API.
• Proactive briefings — /briefing on schedules a daily morning summary pushed to all channels.
• Auto model routing — /auto on picks haiku/sonnet/opus based on message complexity.
• Deep memory search — AI reads all memories semantically when keyword search fails.
• Cron scheduler — recurring AI tasks or direct tool actions. One-time reminders auto-delete.
• Web terminal — browser-based shell access via xterm.js.
• File manager — browse, edit, and create workspace files from the UI.
• REST API — /api/v1/message endpoint for iOS Shortcuts, scripts, and automations.
• Skills — modular instruction packs with credentials and configs. Claude reads them automatically when relevant. Ships with /ultrareview (3-agent parallel branch review — correctness / architecture / UX-a11y) and /fewer-permission-prompts (proposes a tool-allowlist patch from your audit log) preinstalled.
• /checkpoint — cross-restart handoff — manual AI-synthesized CHECKPOINT.md before a known redeploy, plus an activity-gated auto-checkpoint every 6h as a safety net. On the next boot, the checkpoint is injected into the system prompt so work picks up mid-thought instead of starting cold.
• Retention — daily 03:00 sweep prunes conversations idle >14 days and checkpoint archives older than 30 days (or >50 files). Keeps the most recent thread per channel so Discord/Telegram/email session continuity never breaks. One-line summaries of pruned conversations append to memory/archived-conversations.md so nothing vanishes without a record. Configurable via retention.* settings or /retention command.

Search & Analytics

• Live context meter — the session bar shows a real-time prompt-token fill % against the active model's context window (1M for Opus/Sonnet, 200K for Haiku). Counts cache reads and cache writes too — that's the actual prompt size hitting the model. Bar turns yellow at 75%, red and pulsing at 90%, with a dismissible banner above the composer. At 95% Tarsee writes a mechanical snapshot to CHECKPOINT.md automatically; if a turn still trips "prompt is too long", the snapshot is written from the catch path and a recovery card is shown in chat with a one-click "Start fresh session" button. The next boot reads that checkpoint as the handoff so you pick up mid-thought.
• Token usage chart — daily/weekly visual bar chart with model breakdown in Settings > Usage.
• Audit log — timestamped log of all tool executions, logins, and settings changes.
• QR code — scan from desktop to instantly open Tarsee on your phone.
• Typing indicator — see when you're typing on another device in real-time.
• Todo rendering — Claude's task lists render as styled checklists with progress indicators.

Memory & Identity

• Workspace files — SOUL.md (personality), MEMORY.md (knowledge), USER.md (user info), IDENTITY.md.
• Auto-memory — Claude saves important facts as you chat. Memories persist across sessions.
• Daily logs — timestamped notes auto-appended to memory/YYYY-MM-DD.md.
• Checkpoints — CHECKPOINT.md on the volume survives redeploys. Read once on the next boot, then archived to memory/checkpoints/<timestamp>.md for grep-able history.

Appearance & Controls

• Themes — warm-charcoal (default, terracotta accent), noir (pure black OLED-friendly), solarized-light (daylight), jarvis-blue (cyan accent). Switch from Settings > Appearance or via /theme <name>. Plugin-shipped themes are loaded from ui.themes.plugin automatically.
• Effort slider — 6-notch touch-native slider (auto / low / medium / high / max / xhigh) for setting Claude's thinking effort. Long-press the effort toggle on the composer to open; /effort opens it via keyboard. xhigh (Ultra) is available on Opus 4.7.

How It Works

You (web / telegram / discord / email / voice / iOS push)
  |
  v
Tarsee Server (Railway)
  |
  +-- Claude Code Agent SDK (subscription auth, auto-updates)
  |     +-- Built-in: Read, Write, Edit, Bash, Grep, Glob
  |     +-- MCP tools: send_message, schedule_task, remember,
  |         create_canvas, calculator, browser, web_search,
  |         push_notification, send_email_thread, configure_email, etc.
  |
  +-- Voice:      faster-whisper STT + Edge TTS
  +-- Browser:    Playwright (stealth) + captcha solving
  +-- Workspace:  SOUL.md, MEMORY.md, USER.md, CHECKPOINT.md
  +-- SQLite:     conversations, settings, vault, bot_memory, push_subs
  +-- Channels:   Telegram, Discord, Email (IMAP IDLE + SMTP)
  +-- Continuity: /checkpoint + 6h auto-checkpoint + session recap card
  +-- Retention:  daily 03:00 sweep (14d convs, 30d/50-file checkpoints)
  +-- Push:       VAPID + service worker — cron/webhook/tool fires

Channel Setup

Configure in Settings > Channels after deploying. Channels auto-start when you save the token.

Discord: Enable Message Content Intent in Bot settings. Invite with Send Messages, Read Messages, Add Reactions permissions.

WhatsApp: Tarsee uses WHAPI Cloud as the WhatsApp gateway (free tier is enough for personal use). Setup:

1. Sign up at panel.whapi.cloud, create a channel, scan the QR code with the WhatsApp account you want Tarsee to use.
2. Copy the Bearer token from the channel's Token tab.
3. In Tarsee → Settings > Channels > WhatsApp, paste the token, check Enable, click Save. A webhook URL appears.
4. Copy that URL into WHAPI dashboard → Settings > Webhooks, select event messages, save.
5. Send a WhatsApp message to your bot's number — Tarsee replies via Claude.

Direct messages only; group messages are silently ignored. Voice notes are transcribed locally via faster-whisper. Images and PDFs go to Claude vision. Other documents (DOCX, XLSX, ZIP, TXT, CSV, etc.) are saved to workspace/uploads/ and Claude can Read them with the file tool.

Email channel

Tarsee can live in any mailbox you own and reply in real-time. Inbound mail where the body contains @tarsee (configurable) triggers a reply; everything else is absorbed silently so Claude remembers the thread and can answer questions about it later. CC'd, BCC'd, and forwarded mail never triggers an outbound reply.

Setup (two paths — pick one):

1. Settings UI — open Settings > Channels > Email, click a provider preset (Gmail / Outlook / iCloud / Zoho / FastMail / Yahoo), paste your email + app password, save.
2. Chat — tell Tarsee in conversation: "Set up email. Mailbox [email protected], Gmail app password xxxx-xxxx-xxxx-xxxx, only allow [email protected]." Tarsee calls the tarsee_configure_email_channel MCP tool and the channel starts immediately.

Both paths write to the same channel.email record. The Settings UI renders whatever's configured regardless of which path set it.

App passwords (most providers require one instead of your login password):

Self-hosted IMAP/SMTP works too — pick Custom and fill in your host/port.

Mention keyword — defaults to @tarsee. Change it in Settings to @jarvis, @bot, or whatever alias you want. The leading @ is part of what you type so it's obvious what you're setting.

Reply-all — opt-in only. Include [reply-all] in the subject (or type @tarsee reply-all in the body) and Tarsee will reply to everyone in To + CC. Default is reply-to-sender only.

Sender allowlist — strongly recommended. Only emails from listed addresses get processed. Leave empty for dev mode (not safe for production mailboxes). Newsletters and auto-reply loops are always dropped regardless (RFC 3834 Auto-Submitted / Precedence / List-Id headers).

Troubleshooting:

• "Authentication failed" — you probably pasted your login password. Most providers require an app-specific password (usually 16 characters with hyphens). See the table above.
• "IDLE disconnected" — harmless. IMAP servers close IDLE after ~29 minutes; Tarsee reconnects automatically.
• Gmail "less secure apps" — not relevant anymore. Use an app password and keep 2FA on.
• Outlook modern auth — enterprise tenants may require OAuth instead of app passwords. If your admin disabled basic auth, ask them to allow it for this mailbox or use a different provider.
• Reply arrived but wasn't threaded — verify your mail client shows In-Reply-To and References headers. Some bespoke clients strip them.

Commands

Settings

Environment Variables

Note: Claude credentials are NOT set via env var. Run claude login in the web terminal after deploying. See Authenticating with Claude.

Self-Hosting with Docker

docker build -t tarsee .

docker run -d \
  --name tarsee \
  -p 8080:8080 \
  -v tarsee-data:/data \
  -e NODE_ENV=production \
  -e SETUP_PASSWORD=your-password \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  tarsee

After starting, open the web terminal and run claude login to authenticate.

Requirements: Docker, Claude Max subscription (Pro will work but will hit limits quickly).

Security

• AES-256-GCM encrypted credential vault
• Timing-safe authentication
• CSRF protection on all mutations
• Content Security Policy headers
• Rate limiting (10 auth attempts/min/IP)
• Path traversal protection
• OAuth auto-refresh (tokens never stored in plain text)
• Session isolation per conversation
• Audit log for all tool executions and logins

Contributing

Tarsee is open source. PRs welcome.

src/
  server.js                    # Express + HTTP server
  ai/
    providers/claude-code.js   # Agent SDK wrapper
    tarsee-mcp.js              # 20+ MCP tools
  lib/
    tools.js, commands.js      # Tool registry + chat commands
    cron.js                    # Scheduler
    canvas.js                  # Canvas/artifact server
    security-audit.js          # Security checks
  channels/
    telegram.js, discord.js    # Bot integrations
    websocket.js               # Web UI real-time + cross-device sync
  voice/
    stt-handler.js             # faster-whisper STT
    edge-tts-engine.js         # Free TTS (19 voices)
  routes/
    chat.js                    # Chat API + SSE streaming
    external-api.js            # REST API (/api/v1/)
    analytics.js               # Token usage stats
  public/                      # Web UI (vanilla HTML/CSS/JS, PWA)

License

MIT