Megavibe

Give Claude Code a memory that never dies.

Megavibe makes Claude Code remember everything — decisions, mistakes, progress, and context — across sessions, compactions, and crashes. One command to install, one command to use. Optionally, control it from your phone or Apple Watch.

macOS, Linux, and Windows (Git Bash or WSL). Requires a Claude Code subscription. Everything else is optional.

Get Started

1. Open a terminal

• macOS: Press Cmd + Space, type Terminal, press Enter
• Linux: Open your terminal emulator
• Windows: Open Git Bash (from git-scm.com) or WSL

2. Install Megavibe

Copy-paste this into Terminal and press Enter:

curl -fsSL https://raw.githubusercontent.com/poma-ai/megavibe/main/install.sh | bash

The installer detects your OS and package manager (Homebrew, apt, dnf, pacman, winget, choco) and installs everything needed — Node.js, Python, jq, AI tools — then walks you through each step. Takes about 5 minutes.

3. Use it

Navigate to any project and run:

cd ~/my-project
megavibe

That's it. Claude now remembers everything you work on together. Run megavibe every time you start working — it's always safe to re-run.

Every session automatically has Remote Control enabled — you can connect from your phone via the Claude app at any time (see Remote Access below).

What Does It Actually Do?

The problem

Claude Code forgets things. Every time it "compacts" (runs out of memory), it loses detail. After a few compactions, it forgets constraints, repeats mistakes, and loses track of decisions.

The solution

Megavibe creates a durable memory layer that Claude writes to continuously and recovers from automatically:

your-project/
├── .agent/                          <- Claude's memory (survives everything)
│   ├── FULL_CONTEXT.md              <- everything that happened (append-only)
│   ├── DECISIONS.md                 <- why things were done a certain way
│   ├── TASKS.md                     <- what's done, what's pending
│   ├── LESSONS.md                   <- patterns from your corrections
│   └── sessions/{id}/
│       └── WORKING_CONTEXT.md       <- focused summary (~400 lines)
│
├── .claude/                         <- automation (hooks, rules, skills)
│   ├── hooks/                       <- auto-logging, safety, search
│   ├── rules/                       <- extended protocols
│   ├── skills/                      <- slash commands (/catchup, /rehydrate)
│   └── settings.json                <- hook configuration
│
└── CLAUDE.local.md                  <- your personal overrides (gitignored)

How recovery works:

1. An out-of-band watcher daemon reads the live transcript and writes summaries to .agent/ files between turns — no in-session token tax, on by default. (Hook-based nudges are still there as a safety net when the watcher is off.)
2. When Claude's context gets compacted, a hook fires automatically
3. Claude calls Gemini (or ChatGPT, or a built-in subagent) to read the full log and produce a focused summary
4. Claude reads the summary and continues — zero information loss, no human intervention

Features

Continuous out-of-band context flush (the watcher)

A background Python daemon (~/.megavibe/scripts/context-watcher.py) tails the live transcript JSONL and, on a 5-minute trickle, asks Gemini to extract decisions, lessons, task changes, and a narrative recap — then writes them straight to .agent/ files under flock. No in-session token cost, no prompts for Claude. Decisions are staged to a per-session queue for human review (low-stakes items auto-apply); review with python3 ~/.megavibe/scripts/review-decisions.py.

The watcher is on by default — set MEGAVIBE_WATCHER=0 to opt out. When it's running, in-session tier nudges suppress automatically (no double-up). Full design and operations notes: README-watcher.md.

Automatic context recovery

When Claude runs out of memory and compacts, megavibe detects it and triggers recovery. Three tiers:

• Small projects (< 10KB context): injects the full log directly — no AI needed
• Normal projects: Claude calls Gemini to produce a focused ~400-line summary
• Empty context (first compaction): instructs Claude to save the compaction summary before it's lost

Recovery uses a fallback chain: Gemini (subscription) → Gemini (API key) → ChatGPT/Codex → Claude subagent (always works, same subscription).

Semantic search augmentation

Every time Claude searches your code (Grep), a hook automatically searches your project memory too and injects relevant context. Claude sees both code results AND related decisions/history — without you asking.

Powered by poma-memory (pip-installed): hybrid BM25 + local vector search (model2vec) over your .agent/ files. Works locally, no API calls. A reindex-agent.sh hook keeps the index fresh — it re-indexes changed .agent/*.md after edits and Bash appends (debounced, mtime-gated), so semantic recall never drifts stale.

Self-improvement

When you correct Claude, it records the pattern in LESSONS.md. Before every plan, it checks its lessons to avoid repeating mistakes. Your Claude gets better at YOUR project over time.

Safety hooks

Automatically blocks dangerous commands before they execute:

• rm -rf / or rm -rf ~
• git push --force main
• git reset --hard
• DROP TABLE

Phone access (built-in)

Every megavibe session has Remote Control enabled by default. Type /rc in your terminal session to get a QR code — scan it with your phone and continue the same session in the Claude app. Walk away from your desk, keep working from the couch.

Multi-agent orchestration

Megavibe works with only a Claude Code subscription. Everything else adds capabilities but is never required.

Setup installs Gemini/Codex/Playwright CLIs and walks you through login. You can skip any — megavibe adapts.

Structured workflow

Explore → Plan → Implement → Verify → Commit → Learn → Reflect

Parallel tasks (spinouts)

When a plan has 3+ independent tasks, Claude can spin them to parallel subagents. Each gets a fresh context window. The primary benefit is context freshness, not just speed.

Slash commands

Inside a megavibe session:

Remote Access (optional)

Control Claude Code from your iPhone, Apple Watch, or any device — with or without Telegram.

Without Telegram (built-in)

Every megavibe session has Remote Control enabled. In your terminal:

/rc

Scan the QR code with your phone → Claude app opens → same session. Type on either device. Works immediately, no setup needed.

With Telegram (personal assistant + project launcher)

Add a Telegram bot for a richer experience: a personal assistant that answers questions, checks project status, and launches Claude sessions — all from a chat message or voice note on your Watch.

What it does

The personal assistant runs as a full Claude session (not a limited headless mode) — it has access to all tools including web search, and maintains conversation history across messages.

Setup

# 1. Install tmux (needed for persistent personal session)
#    macOS:  brew install tmux
#    Ubuntu: sudo apt install tmux
#    Fedora: sudo dnf install tmux
#    Arch:   sudo pacman -S tmux

# 2. Create a Telegram bot
#    Message @BotFather on Telegram → /newbot → copy the token
#    Message @userinfobot → copy your numeric user ID

# 3. Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):
export MEGAVIBE_TELEGRAM_TOKEN="your-bot-token"
export MEGAVIBE_TELEGRAM_USER_ID="your-user-id"

# Optional: for voice transcription (Watch voice notes)
export OPENAI_API_KEY="your-key"

# 4. Start the bot — ONCE. It stays up (supervised, auto-restart) and you
#    rarely touch it again; re-running is a harmless no-op.
megavibe remote

#    Occasional controls (you won't need these often):
megavibe remote --status        # is it running?
megavibe remote --stop          # stop it
megavibe remote --autostart on  # also start it at login, macOS (off | status too)
megavibe remote --fg            # run in foreground to watch logs (debugging)

# 5. Register your projects (in Telegram DM with the bot):
#    /register megavibe ~/Documents/megavibe
#    /register officeqa ~/Documents/_1_WORK/poma/poma-officeqa

Day to day — what to type, when

After the one-time setup above, the bot stays up on its own. You don't keep starting it. In normal use you only ever do one of these:

You normally never re-type megavibe remote — it's idempotent and supervised, so it's only for the very first start (or after a --stop). megavibe remote (phone) and megavibe assistant (keyboard) are two doors into the same live Claude.

How it works

megavibe remote
  │
  ├─ Personal assistant (full Claude in tmux)
  │   └─ ~/.megavibe/personal/ — standard megavibe project
  │   └─ Messages injected via tmux, responses read from session JSONL
  │   └─ Visible in Claude app via Remote Control
  │
  ├─ Project launcher
  │   └─ Mention a project name → spawns claude remote-control
  │   └─ Sends session URL to Telegram → tap to open in Claude app
  │
  └─ Status reader
      └─ Reads .agent/TASKS.md directly (instant, no Claude call)

The personal assistant is a standard megavibe project at ~/.megavibe/personal/ — same .agent/ files, same poma-memory indexing. Your personal context persists across sessions just like project context.

One brain, reachable two ways. The personal assistant is a single persistent Claude running in the megavibe-personal tmux session, working out of ~/.megavibe/personal/ (its own .agent/ memory and poma-memory index). You reach the same live session two ways: megavibe remote drives it from your phone or Watch over Telegram, and megavibe assistant attaches your terminal straight to it. Start a thought at your desk, continue it on your phone — one conversation, not just shared files. (megavibe assistant spins the brain up if it isn't running yet; detach with Ctrl-b d and it keeps going.) Run either from any directory: everything uses absolute ~/.megavibe/ paths, so there's no folder you need to cd into first.

Apple Watch

Install Pigeon for Telegram (~$2/month). Record voice notes on your wrist → OpenAI Whisper transcribes them → the bot routes to the right project or answers personally. Responses are concise and Watch-readable.

Bot commands

Optional API Keys

Megavibe works without any API keys. Adding them unlocks extra capabilities:

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.) for persistence
export GEMINI_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"

What Gets Installed

Machine-wide (by setup)

Per-project (automatic on first megavibe run)

Performance

Megavibe adds minimal overhead. The main cost is the poma-memory vector search database, which stores embeddings of your .agent/ files locally.

Real measurements from an active project (megavibe itself — 1,500-line context log, 50+ sessions, 3,000 chunks indexed):

For a typical project (shorter context, ~500 chunks), expect ~1 MB disk and sub-100ms warm search.

poma-memory uses brute-force cosine similarity on numpy arrays — no external vector DB needed. This scales comfortably to ~10K chunks (~30 MB DB) before you'd notice any slowdown. Most projects will never reach that.

Updating

Re-run the installer. It's idempotent:

curl -fsSL https://raw.githubusercontent.com/poma-ai/megavibe/main/install.sh | bash

Or if you have a local clone: bash megavibe/setup.sh

Troubleshooting

megavibe: command not found

# Add ~/.local/bin to your PATH (add to ~/.zshrc, ~/.bashrc, or ~/.profile)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Hooks aren't firing — Install jq: brew install jq (macOS), sudo apt install jq (Ubuntu), sudo dnf install jq (Fedora)

Gemini/Codex not connecting — Run the CLI directly (gemini or codex) to re-authenticate. Megavibe works without them.

Context recovery not working — Check that .agent/FULL_CONTEXT.md has content. If empty, the watcher hasn't flushed yet (cycles every 5 min by default) or it isn't running. Verify with tmux ls | grep '^mvw-'; tail its log at .agent/LOGS/watcher.<sid12>.log. If the watcher is off (MEGAVIBE_WATCHER=0), the safety-net hook nudges Claude to flush manually after the first few tool calls.

poma-memory search not working — Check Python deps: python3 -c "import numpy, model2vec". If missing: pip3 install numpy model2vec

Memory recall returns stale or off-topic hits — An older index can be stale (built against a prior checkout) or cross-project-contaminated (an early poma-memory index run from a parent dir swept sibling .agent/ dirs into one db). poma-memory index is additive and won't clear that. Self-heal: re-run bash ~/.megavibe/setup.sh (upgrades poma-memory to ≥0.3.7) and bash ~/.megavibe/init.sh <project> (or /megavibe-restart) — init does a one-time clean rebuild of that project's index, gated on .agent/LOGS/.poma-heal-v1. Force a re-heal anytime by deleting that marker and re-running init, or manually: rm -f .agent/.poma-memory.db*; poma-memory index .agent/ from inside the project. Never run poma-memory index from a parent dir containing sub-project .agent/ dirs — that is what causes the contamination.

Remote bot: "No response received" — Check the tmux session: tmux attach -t megavibe-personal. Claude may be waiting for input or stuck on a prompt.

Remote bot: voice not working — Requires OPENAI_API_KEY and httpx: pip3 install httpx

Debug hooks — claude --debug shows hook execution details.

FAQ

Does this work with any language/framework? Yes. Megavibe is language-agnostic — it's just files and shell hooks.

Can my team use it on the same project? Yes. .agent/ files are designed for concurrent access. Commit .agent/ to git so the team shares decisions and lessons.

Does this replace Claude Code's built-in memory? No, it complements it. Claude's auto-memory handles cross-session preferences. Megavibe handles detailed project context, decisions, and task state.

What if I don't have Gemini or ChatGPT? Megavibe still works. Context recovery falls back to a built-in Claude subagent (same subscription). External backends improve quality but are never required.

Do I need Telegram for remote access? No. Every session has /rc (Remote Control) built in — connect from the Claude app on your phone with no extra setup. Telegram adds a personal assistant and project launcher on top.

Does the Telegram bot need to run all the time? No. It's optional. Run megavibe remote to spin it up in the background (it will persist across terminal closes). To make it automatically start when your computer boots up, run megavibe remote --autostart on. Your normal terminal sessions work exactly the same either way.

How do I uninstall?

rm -rf ~/.megavibe ~/.local/bin/megavibe
# Remove the megavibe block from ~/.claude/CLAUDE.md (between <!-- megavibe-v3 --> markers)
# In each project: rm -rf .agent .claude/hooks .claude/rules .claude/skills CLAUDE.local.md

Architecture (for contributors)

See CLAUDE.md for full contributor documentation.

• Idempotency is sacred. Both setup.sh and init.sh are safe to re-run.
• Marker-based protocol updates. <!-- megavibe-v3 --> markers enable surgical replacement.
• Infrastructure vs. user data. Hooks/rules/skills are always overwritten. Context files are never overwritten.
• Session isolation. Multiple Claude sessions can run on the same project safely.
• Remote Control by default. Every session launches with --remote-control.

License

MIT