About Harvis
Harvis is a self-hosted AI second brain. It runs a persistent Claude Code session alongside your Obsidian vault so your AI assistant has full, always-on context over every note you've ever written ā accessible from your browser, phone, or Telegram.
What Harvis does
Most AI chat tools start from zero each conversation. Harvis is different: it keeps a Claude Code session alive inside a Docker container, permanently connected to your note vault. Ask it to research a topic, draft a note, find connections between ideas, or just tell you what you were thinking about last week ā it can do all of that because it can read and write your vault directly.
Always-on AI session
Claude runs 24/7 with full read/write access to your notes. No context reset between conversations.
Every access method
Chat via browser, claude.ai, Telegram, or attach directly in a terminal. Same live session, all channels.
Your data, your server
Self-host on any machine. Notes stay on your hardware and sync to a private GitHub repo you own.
How it works
Harvis is three layers that work together: a Next.js platform on Vercel handles your identity and routes browser traffic; a Cloudflare Tunnel carries that traffic securely into your container; and the container itself runs eight coordinated processes.
The 8 container processes
| Process | What it does |
|---|---|
| claude | Persistent Claude Code session in tmux ā your AI brain |
| claude-cred-watchdog | Refreshes OAuth tokens proactively every 15 min so Claude never drops mid-session |
| tunnel | Cloudflare cloudflared ā exposes the dashboard over HTTPS without opening ports |
| harvis-dashboard | Hono API server on port 3000 ā powers the chat, tasks, projects, and wiki UI |
| xvfb | Virtual framebuffer so Obsidian can run headless (no monitor needed) |
| obsidian | Headless Obsidian Electron ā manages the vault index and plugin ecosystem |
| syncthing | Bidirectional file sync with your phone for Obsidian Mobile |
| gitwatch | Auto-commits and pushes vault changes to GitHub within 15 seconds |
Auth chain
Harvis uses Clerk for identity on the platform side. Every request to your container is signed with a short-lived ES256 JWT ā the container verifies it against a public key endpoint without ever calling Vercel. Your container never handles passwords or Clerk sessions directly.
How to use Harvis
Browser ā Harvis Dashboard
Navigate to http://localhost:3000 (or your tunnel URL when away from home). The dashboard has four tabs: Tasks, Projects, Wiki, and Chat. Chat streams Claude responses live and persists every exchange.
claude.ai ā Remote session
Sign into claude.ai, look for Second Brain in the remote sessions list, and connect. This attaches you directly to the same live tmux session running in your container ā desktop and mobile both work.
Terminal ā tmux attach
For the full Claude Code TUI, attach directly:
Detach without stopping: Ctrl-b d
Telegram ā message from anywhere
Once the Telegram bridge is configured, any message you send to your bot is forwarded to Claude. Responses stream back in real time. Useful commands:
| Command | What it does |
|---|---|
| /status | Check if Harvis is online |
| /clear | Reset Claude's context window |
| /compact | Compact the conversation history |
| /cost | Show current session cost |
| /queue | List messages queued while offline |
Any other text is forwarded as a prompt. Claude Code slash commands like /save, /autoresearch, and /canvas all work in Telegram too.
Obsidian Mobile ā notes on your phone
Syncthing keeps your vault in sync with your phone in seconds. Install Obsidian Mobile, point it at the Syncthing-synced folder, and you have the full note-editing experience on your phone. Changes Claude makes in the container appear on your phone within seconds.
What to ask Claude
Claude has full read/write access to every file in your vault. Some ideas:
Vault structure
Your notes live in data/vault/ on the host, mounted at /vault inside the container.
Every save is auto-committed by Gitwatch and pushed to your private GitHub repo within 15 seconds ā a full version history of every thought.
Ready to set it up?
The setup guide walks you through every step ā from installing Docker to a fully running system with Telegram integration.
Setup guide ā