Photon Gateway
iconiczack93/photon-gateway
IA pessoal no iMessage com Claude Code, rodando sempre ligado em VPS
Ver no GitHubAgent pessoal que roda via iMessage usando Photon + Claude Code. Um serviço Node.js que funciona 24/7 em VPS, recebe mensagens do iMessage, roteia para Claude Code com acesso ao seu segundo cérebro (MCP), e devolve respostas. Substitui serviços hospedados multi-tenant por controle total local.
Instalação
npx convez-ai iconiczack93/photon-gateway1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistente de IA acessível via iMessage com contexto personalizado
- Integração do Claude Code com banco de dados pessoal e segundo cérebro
- Notificações proativas e nudges agendados para o celular
Veredito

Projeto altamente especializado para quem quer IA pessoal resiliente no iMessage com controle total da inteligência. Requer conhecimento de DevOps, Node.js e arquitetura de agents, mas oferece integração profunda com Claude Code e contexto local sem intermediários.
README
A tradução para o português deste README ainda está na fila.
Photon Gateway
Zack's FORGE brain on iMessage via Photon. A small Node.js service that runs on a VPS, receives iMessages, routes them to Claude Code via shell-out, and sends replies back. Replaces Poke as the brain surface.
Why Photon over Poke
Poke is a hosted multi-tenant AI service. Photon is a bare iMessage protocol bridge that lets us run our own agent. This gives us:
- Full control of the brain invocation (Claude Code, not Poke's built-in LLM)
- Access to the FORGE DB and second-brain MCP without middle layers
- Direct shell-out to
claude -p, reusing the exact pattern forge-bot uses on the Telegram side - Resilience and fallback when the DB bridge is unreachable (PC asleep): the brain still answers general queries via Claude's base knowledge
Photon handles the iMessage protocol; we own the intelligence layer.
Architecture
[iPhone Messages]
|
v
[Photon iMessage Provider]
|
v
[Photon Gateway Node.js Process]
|
| stdin with message text
v
[claude -p] (shell-out)
|
| reads .mcp.json: second-brain + DB bridge
v
[Claude Code + FORGE Context]
|
| stdout -> reply
v
[Photon API - send() reply back]
|
v
[iPhone Messages]
Running
Local Development
npm install
cp .env.example .env
# Edit .env with your Photon credentials
npm run dev
Production (VPS)
See deploy.md for step-by-step provisioning.
systemctl start photon-gateway
journalctl -u photon-gateway -f
Configuration
Copy .env.example to .env and fill in:
PHOTON_PROJECT_ID: from https://photon.sh/dashboardPHOTON_PROJECT_SECRET: from https://photon.sh/dashboardALLOWED_SENDER: your phone number (only this sender is served)FORGE_PROJECT_DIR: path to your forge-recruiting clone (must contain .mcp.json)CLAUDE_CODE_BINARY: typically justclaudeLOG_LEVEL: debug, info, warn, errorCLAUDE_TIMEOUT: max wait for claude -p (ms, default 30000)
See .env.example for all options.
Proactive Nudges (send_nudge.ts)
To push outbound notifications to the owner's phone:
node --loader ts-node/esm src/send_nudge.ts "Your message here"
The script finds the existing conversation with ALLOWED_SENDER and sends the message. Useful for scheduled tasks:
# In a cron job on the VPS
0 8 * * * photon cd /opt/photon-gateway && node --loader ts-node/esm src/send_nudge.ts "Morning brief" 2>&1 | logger -t photon
Or from the PC via SSH (during a scheduled task):
# PowerShell on PC
$msg = "Your scheduled nudge"
$result = ssh user@vps "cd /opt/photon-gateway && node --loader ts-node/esm src/send_nudge.ts '$msg'"
Write-Host $result
Logs
Structured JSON logging to stdout and optionally to a file. Key fields:
timestamp: ISO 8601level: DEBUG, INFO, WARN, ERRORmessage: human-readable summary- Context fields (e.g., sender, contentLength, delayMs)
# Live tail
journalctl -u photon-gateway -f
# Search for errors
journalctl -u photon-gateway | grep ERROR
Resilience
- Auto-reconnect: if the Photon stream drops, reconnects with exponential backoff
- DB bridge fallback: when the PC is asleep and the bridge is unreachable, Claude still answers general queries; only DB-backed answers degrade
- Message chunking: long replies are split into iMessage-safe chunks (1600 chars each)
- Sender whitelisting: only ALLOWED_SENDER is served; all others are rejected and logged
Building from Source
npm run build
# outputs to ./dist/
Technology Stack
- spectrum-ts: Photon's TypeScript SDK
- Node.js 18.17+: runtime
- TypeScript: source language
- systemd: service management on Linux
Common Tasks
Check service status
systemctl status photon-gateway
systemctl logs -u photon-gateway -n 50
Restart service
systemctl restart photon-gateway
Send a test nudge
node --loader ts-node/esm src/send_nudge.ts "Test message"
Increase log verbosity
# Edit .env
LOG_LEVEL=debug
systemctl restart photon-gateway
Debugging
Enable debug logs and watch in real-time:
LOG_LEVEL=debug npm run dev 2>&1 | jq '.'
Or from systemd:
journalctl -u photon-gateway -f --output short-iso
Related
- Deploy guide
- Photon docs
- Replaces: Poke (via second-brain MCP) as the iMessage AI brain
License
MIT. Deploy and own your brain.