convez.ai
AgenteAutomaçãoAvançado
techfreakworm

Claude Soma

techfreakworm/claude-soma

Orquestrador multi-canal para Claude Code com voz, projetos e automação social

Ver no GitHub
BomPluginScore · de 0 a 100

Um agente orquestrador que dá um corpo ao Claude Code, integrando Telegram, voz, equipes de agentes persistentes, postagem em redes sociais e dashboard administrativo. Roda inteiramente via Claude Max OAuth em uma única VPS ARM, sem necessidade de chaves de API Anthropic.

Instalação

$npx convez-ai techfreakworm/claude-soma

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
5
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Orquestração de equipes de agentes independentes por projeto
  • Automação de postagens em redes sociais (X, LinkedIn, Medium)
  • Processamento de tarefas longas via Telegram com resposta imediata

Veredito

Projeto ambicioso que reduz drasticamente a complexidade de plataformas de agentes, aproveitando nativo do Claude Code. Excelente para quem quer orquestração sofisticada sem infraestrutura pesada, mas requer conhecimento profundo de Python e arquitetura de sistemas.

README

A tradução para o português deste README ainda está na fila.


Claude Soma (Greek soma, "body") gives Claude Code a body: a Telegram channel, voice in and out, a project orchestrator that spawns persistent, independent agent teams per workstream, social posting, and a showcase dashboard. It is authed entirely through a Claude Max subscription — no Anthropic API keys — and runs on a single Oracle Cloud Ubuntu ARM free-tier VPS.

The thesis

Hermes-Agent by Nous Research is a ~27,000-line platform for self-improving messaging agents: channels, cron, skills, memory curation, sandbox backends, trajectory tooling. After studying it, the question this project answers is:

What if your engine is Claude Code? How much do you actually need to build?

The answer is a few thousand lines. Channels (Telegram, Discord, custom), agent teams, server-hosted scheduled routines, Remote Control, mobile push, MCP, hooks, plugins, and auto-memory are all native to Claude Code if you know where to look. The platform layer collapses; Claude Soma is the missing slice — a voice pipeline, a project orchestrator, social posting, a dashboard, and curated workflows — riding Claude Code's native rails.

Features

  • Telegram channel — DM the bot (text or voice); it replies in text or voice. The bot is an orchestrator: anything slow is dispatched to a background subagent and acked immediately, so your chat never blocks.
  • Voice in / out — voice-stt (whisper.cpp) transcribes voice memos; voice-tts (piper -> opus) speaks replies.
  • Project orchestration — spin up a persistent project-lead per workstream. Each lead is an independent Claude Code session in its own working directory, with its own Remote Control URL, that can run its own agent team.
  • cgroup-isolated leads — every lead runs in its own transient systemd unit and tmux server, so a channel restart can't take it down.
  • Social posting — per-platform Playwright MCP servers post to X, LinkedIn, and Medium using a shared, persistent browser-auth store (log in once via VNC, reused everywhere, refreshed weekly).
  • Scheduled routines — server-hosted cron via Claude's cloud routines, plus systemd timers and crontab, all surfaced together.
  • Dashboard — a FastAPI + Next.js admin/showcase site behind Caddy, gated by GitHub OAuth, reading live Claude state over a Unix-socket bridge.
  • Max OAuth only — every Claude call draws on your Max plan; there is no Anthropic API key anywhere in the system.

Architecture

The Telegram session is an orchestrator, not a team-lead. It spawns multiple independent project-leads, each in its own cgroup, each able to run its own agent team — sidestepping Claude Code's "one team per lead" constraint while giving you per-project specialization.

A request flows in on Telegram (text or voice); fast work is answered inline, slow work is dispatched to a background subagent so the channel stays responsive. Messaging a project-lead is delivered by typing into its tmux pane and reading the reply back from it — leads are independent processes, not chat teammates.

Each project-lead is spawned via sudo systemd-run into its own transient unit and dedicated tmux socket, inherits all MCP servers except Telegram, and can be attached to directly from the Claude mobile app or claude.ai/code via its Remote Control URL. Three control surfaces, one Max account.

Diagram sources (Mermaid) live next to the images in docs/images/. Full design: docs/superpowers/specs/2026-05-22-hermes-claude-design.md.

How you use it

You say (Telegram)Claude Soma doesYou get
"What am I working on?" (voice)portfolio-status skillVoice/text reply listing repos + active project-leads
"Build a scraper for the F1 standings that tweets on change"spawn-project -> orchestrator spawns a cgroup-isolated lead (sudo systemd-run + tmux) running its own agent teamA persistent f1-scraper lead with its own cwd, team, and Remote Control URL
"Tell f1-scraper to use httpx"message-project -> tmux send-keys into the lead's pane; reply scraped backThe message delivered to the lead; its answer relayed to you
"Post this to LinkedIn"a playwright-linkedin MCP session using the shared auth storePosted, no per-task login
"Draw the system architecture"codex-image-gen -> Codex CLI (your ChatGPT sub, not Max)The image returned as a Telegram photo
"Every weekday 8am IST, send me a brief"schedule-routine -> a cloud routine on Anthropic infraFires while you sleep; no local machine needed

Quickstart

On a fresh Ubuntu 24.04 VPS (2 GB+ RAM, public IPv4, DNS A-records configured):

sudo mkdir -p /opt/claude-soma && sudo chown ubuntu:ubuntu /opt/claude-soma
cd /opt/claude-soma
git clone https://github.com/techfreakworm/claude-soma.git .
sudo bash scripts/bootstrap.sh --cloud=oci  # or omit --cloud=oci on non-OCI; ends with DNS records you must add at your DNS provider
sudo cp secrets.env.example /etc/claude-soma/secrets.env
sudo nano /etc/claude-soma/secrets.env  # fill in the required keys
sudo bash scripts/smoke_install.sh       # verify

For the full install runbook with prerequisites, external CLI setup, and troubleshooting: see INSTALL.md.

Configuration

  • Auth: Claude Max OAuth only. The token lives in /etc/claude-soma/secrets.env as CLAUDE_CODE_OAUTH_TOKEN; nothing reads an Anthropic API key.
  • Telegram: the bot opts into the Telegram plugin via config/claude/channel-settings.json (so it never leaks into project-leads).
  • Social auth: run node scripts/pw-login.js once on the VNC desktop to log into X / LinkedIn / Medium; pw-refresh keeps the sessions warm.
  • Sessions: somux ls | a <name> | peek <name> lists/attaches/peeks the channel + every project-lead (each on its own tmux socket).

Forking — replace the author's personal defaults

Shipped install artifacts (Caddyfile, caddy/files.caddyfile, the API CORS fallback, the frontend metadata, the engagement-drip URL template, the channel bot's system prompt) all read their domain from envs in /etc/claude-soma/secrets.env. To stand up your own instance, set these keys in that file:

SOMA_DOMAIN=example.com            # base domain — dashboard goes on soma.<this>
FILES_DOMAIN=files.example.com     # optional override; defaults to files.<SOMA_DOMAIN>
ACME_EMAIL=you@example.com         # Let's Encrypt registration email
HERMES_ALLOWED_GITHUB_HANDLES=your-github-username

scripts/finalize-caddy.sh renders the Caddyfile + site configs from those values. The frontend reads NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_AUTHOR_NAME, and NEXT_PUBLIC_AUTHOR_URL at build time for footer attribution + OpenGraph metadata. The .claude-plugin/*.json files are plugin marketplace metadata — keep the original author there unless you're publishing a fork to your own plugin marketplace. The docs/superpowers/ specs are frozen historical artifacts — leave them as-is.

Project layout

claude-soma/
  .claude-plugin/        Claude Code plugin + marketplace metadata
  .mcp.json              wires the MCP servers into the bot
  config/claude/         channel-settings.json (telegram opt-in), lead-mcp.json
  src/claude_soma/
    mcp_servers/
      voice_stt/         whisper.cpp wrapper
      voice_tts/         piper + ffmpeg -> opus
      project_orchestrator/   registry + spawner + templates + server
      hermes_api/        Unix-socket state bridge for the dashboard
    api/                 FastAPI dashboard backend (routes/, auth, SSE)
    wizard/              interactive setup wizard
  frontend/              Next.js dashboard (standalone build)
  skills/                11 Claude Code skills (spawn/message/kill/list project,
                         schedule-routine, portfolio-status, voice, codex-image-gen, ...)
  agents/                subagent template(s) for spawned leads
  templates/projects/    project-type templates (web-scraper, llm-app, ...)
  hooks/                 SessionStart + UserPromptSubmit + PostToolUse hooks
  scripts/               deploy, bootstrap, healthcheck, voice intake, somux,
                         pw-login / pw-refresh, ...
  systemd/               channel, api, frontend, timers (healthcheck, reaper, ...)
  tests/                 pytest suite across the MCP servers + API
  docs/                  design spec + plan, images, engineering notes

Status

A personal-use-first build, deployed and actively developed on a single OCI ARM VPS, on its way to a polished portfolio showcase. The Telegram orchestrator, cgroup-isolated project-lead spawning, the MCP toolset, and the dashboard are in place; the voice and social-posting pipelines are wired and in bring-up. Docs that lag the code are noted as such — trust the code and git log.

Contributing

Issues and PRs welcome. Repo conventions live in CLAUDE.md: Python 3.12, ruff (line length 100), mypy --strict, pytest (asyncio_mode = "auto"); conventional-style commit subjects; no emoji in code or commits. Run the suite with pytest -v (voice tests skip without whisper/piper installed).

License

MIT (c) Mayank Gupta.

Acknowledgements

  • Hermes-Agent (Nous Research) — the platform whose product surface this project distills onto Claude Code.
  • Anthropic Claude Code — the engine: channels, agent teams, Remote Control, MCP, hooks, routines.
  • whisper.cpp, piper, Playwright, Caddy, FastAPI, and Next.js.
Ver o original no GitHub

Bom para

Relacionados