convez.ai
AgenteAutomaçãoAvançado
iconiczack93

Photon Gateway

iconiczack93/photon-gateway

IA pessoal no iMessage com Claude Code, rodando sempre ligado em VPS

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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-gateway

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Full control of the brain invocation (Claude Code, not Poke's built-in LLM)
  2. Access to the FORGE DB and second-brain MCP without middle layers
  3. Direct shell-out to claude -p, reusing the exact pattern forge-bot uses on the Telegram side
  4. 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/dashboard
  • PHOTON_PROJECT_SECRET: from https://photon.sh/dashboard
  • ALLOWED_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 just claude
  • LOG_LEVEL: debug, info, warn, error
  • CLAUDE_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 8601
  • level: DEBUG, INFO, WARN, ERROR
  • message: 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

License

MIT. Deploy and own your brain.

Ver o original no GitHub

Bom para

Relacionados