Skip to content

README.md

Latest commit

 

History

History
308 lines (235 loc) · 12.3 KB

README.md

File metadata and controls

308 lines (235 loc) · 12.3 KB

Golems Mascot

Golems

AI agents that work everywhere you do.
Skills, plugins, and autonomous agents — use them in Claude Code, Telegram, any CLI, or Cowork (coming soon).

Docs Recruiter Teller Coach

What is this?

Golems is a personal AI agent ecosystem built as a Bun workspace monorepo. Each golem is a self-contained Claude Code plugin — install one into any Claude session and it brings its skills, rules, and context with it.

Use golems through any surface:

Surface How Status
Claude Code claude --plugin-dir packages/recruiter — any golem as a plugin Live
/agents Named agent profiles with specialized personalities Live
Telegram ClaudeGolem bot routes to domain golems via Composers Live
CLI golems status, golems doctor, golems wizard Live
Any AI agent Clone the repo, grab the skills/rules you need Live
Claude Cowork Same plugins + skills in collaborative workspace Live

It's not a Telegram bot — it's a collection of skills, rules, MCP tools, and agent profiles bundled into an ecosystem. Telegram is just one surface. A Codex agent, a Cursor session, or a fresh Claude Code instance can all use golems by pointing at the plugin directory.

Your Mac runs the brain (Telegram bot, Night Shift, memory). Railway runs the body (cloud worker, briefings). Every conversation gets indexed into searchable memory via BrainLayer (284K+ chunks, knowledge graph, 12 MCP tools).

Quick Start

git clone https://github.com/EtanHey/golems.git && cd golems
bun install
golems wizard      # Interactive setup — picks services, wires keys
golems status      # See what's running

Full docs →

Architecture

Four domain golems + an orchestrator + tools + infrastructure.

graph TB
    subgraph Surfaces["Access Surfaces"]
        CC[Claude Code]
        TG[Telegram]
        CLI[CLI]
        CW[Cowork]
    end

    subgraph Golems["Domain Golems"]
        RG["RecruiterGolem<br/>Outreach + Practice"]
        TL["TellerGolem<br/>Finance + Tax"]
        CG["CoachGolem<br/>Calendar + Plans"]
        CT["ContentGolem<br/>Publishing"]
    end

    subgraph Tools["Tools & Layers"]
        BL["BrainLayer<br/>284K+ chunks<br/>12 MCP tools"]
        VL["VoiceLayer<br/>TTS + STT"]
    end

    subgraph Infra["Infrastructure"]
        CW2["Cloud Worker<br/>Railway"]
        NS["Night Shift<br/>4am autonomous"]
        SH["Shared<br/>Supabase + LLM"]
    end

    CC & TG & CLI & CW --> RG & TL & CG & CT
    RG & TL & CG & CT --> SH
    CW2 --> SH
    NS --> SH
    RG & CG & CT --> BL
Loading

Golems (Domain Agents)

Golem Domain What it does
👔 RecruiterGolem Recruitment Finds contacts via GitHub + Exa + Hunter. Outreach campaigns. 7 interview practice modes with Elo tracking.
💰 TellerGolem Finance Categorizes transactions for tax. Payment failure alerts. Monthly expense reports.
🗓️ CoachGolem Scheduling Calendar management. Daily plans. Reads status from all other golems.
✍️ ContentGolem Publishing Visual content factory (Remotion, ComfyUI, dataviz) + LinkedIn posts, Soltome, ghostwriting.

Orchestrator

Component Role
🤖 ClaudeGolem Persistent Telegram bot. Routes messages to golems. Manages Night Shift + briefings.

Tools & Layers

Component Role
BrainLayer Persistent memory — 284K+ indexed chunks, knowledge graph, 12 MCP tools, entity contracts, BrainBar daemon
VoiceLayer Voice I/O — TTS + STT, VoiceBar daemon, 2 MCP tools

Infrastructure

Component Role
Night Shift Runs at 4am. Scans repos for TODOs, creates PRs, sends morning briefing.
Shared Supabase, LLM abstraction, state store, notifications, event log.

Packages

golems/
├── packages/
│   ├── claude/         # ClaudeGolem — Telegram bot + orchestrator
│   ├── recruiter/      # RecruiterGolem — outreach, contacts, interview practice
│   ├── teller/         # TellerGolem — finance, tax, subscriptions
│   ├── coach/          # CoachGolem — calendar, daily plans
│   ├── jobs/           # JobGolem — job scraping, LLM matching, auto-outreach
│   ├── shared/         # Supabase, LLM, email, state, notifications
│   ├── services/       # Night Shift, Briefing, Cloud Worker, Doctor, Wizard
│   ├── content/        # ContentGolem — publishing + content creation
│   ├── golem-skills/   # Golems CLI — install skills, MCP servers, agent configs
│   ├── docsite/        # Docusaurus documentation site
│   ├── golems-tui/     # React Ink terminal dashboard
│   └── (voicelayer)    # Voice I/O layer — external repo (github.com/EtanHey/voicelayer)
├── .claude/agents/     # 10 named agent profiles (/agents)
├── .claude/rules/      # Auto-loaded rules (survives compaction)
├── skills/             # 51 golem-powers skills with AI-agnostic adapter layer
├── rules-library/      # Exportable rules for any Claude Code project
├── docs/architecture/  # Architecture decisions (BrainLayer-indexed)
├── launchd/            # macOS service plists
└── Dockerfile          # Railway deployment

Tech Stack

Layer Tech
Runtime Bun + TypeScript
LLM Claude Code (Opus/Sonnet/Haiku), Gemini CLI, Cursor CLI
Database Supabase (Postgres + RLS)
Memory sqlite-vec + bge-large-en-v1.5 embeddings (284K+ chunks, knowledge graph, entity contracts)
Cloud Railway (Docker)
Local macOS launchd services
Bot grammY (Telegram)
Testing Bun test
CI/CD GitHub Actions + CodeRabbit + DeepSource

Deployment

Environment What Runs
Mac (brain) Telegram bot, Night Shift, BrainLayer, VoiceBar, notification server
Railway (body) Cloud worker, briefings
Supabase Database, auth, storage 
  Claude Code ──┐
    Telegram ───┤
     Cowork ────┼──→  Golem Plugins  ──→  Skills + MCP + Rules
      CLI ──────┤
  Any agent ────┘
                     ┌─────────┐┌─────────┐┌─────────┐┌─────────┐
                     │Recruiter││ Teller  ││  Coach  ││ Content │
                     │  Golem  ││  Golem  ││  Golem  ││  Golem  │
                     └────┬────┘└────┬────┘└────┬────┘└────┬────┘
                          └─────┬────┴─────┬────┘          │
                                ▼          ▼               │
                     ┌──────────┐┌──────────┐┌──────────┐  │
                     │  Email + ││ Services ││BrainLayer│◄─┘
                     │   Jobs   ││ (Railway)││ (memory) │
                     └──────────┘└──────────┘└──────────┘

Telegram

Two topics in the group:

  • General — interactive ClaudeGolem chat
  • Alerts — all one-way notifications (jobs, email, nightshift, health)

Commands: /status /trigger /tonight /morning /jobs /admin

CLI

golems status          # Service overview
golems doctor          # Health checks
golems wizard          # Guided setup
golems skills          # List all skills
golems rules check     # Audit rules for a project
golems scrape          # Trigger job search
golems logs telegram   # View service logs

Use as a Plugin

Each golem is a Claude Code plugin. Install one into any session:

# Use RecruiterGolem for interview practice
claude --plugin-dir ~/Gits/golems/packages/recruiter

# Use TellerGolem for tax categorization
claude --plugin-dir ~/Gits/golems/packages/teller

# Use the whole ecosystem
claude --plugin-dir ~/Gits/golems

The plugin brings its CLAUDE.md, skills, MCP tools, and rules automatically.

AI-Agnostic Skills

Skills aren't locked to Claude Code. The 3-layer adapter architecture lets any AI CLI (Claude, Codex, Cursor, Gemini, Kiro) use the same skills:

skills/golem-powers/cmux-agents/
├── SKILL.md                    # Layer 1: Universal best practices (any AI reads this)
├── adapters/
│   ├── capabilities.yaml       # Layer 2: Capability matrix + routing rules
│   ├── claude.md               # Layer 3: Claude-specific syntax, flags, models
│   ├── codex.md                #           Codex-specific (GPT-5.4, output contracts)
│   ├── cursor.md               #           Cursor-specific (@codebase, bugbot)
│   ├── gemini.md               #           Gemini-specific (1M tokens, free tier)
│   └── kiro.md                 #           Kiro-specific (--no-interactive)
└── evals/
    └── evals.json              # Cross-AI eval assertions

Cross-AI eval results (same 8 prompts, tested on 3 CLIs):

CLI Score Key Strength
Codex (GPT-5.4) 8/10 Fast structured output, full-auto mode
Gemini (2.5 Pro) 10/10 1M context, perfect portability
Kiro 9.5/10 Lightweight, free tier

Skills adapted so far: cmux-agents, pr-loop, commit, coach, context-check, large-plan, and more.

Agent Profiles

10 named agents via /agents — each with specialized system prompts and tool access:

Agent Domain
recruiter Interview practice, outreach, contacts
coach Calendar, daily plans, priorities
jobs Job scraping, matching, quality
content LinkedIn, Soltome, ghostwriting
services Night Shift, Briefing, Doctor, Wizard
orchestrator Telegram routing, ecosystem coordination
tax-helper Bank transactions, deductions, Schedule C
discovery-voice Voice-powered client discovery calls
qa-voice Voice-powered QA with Playwright
migration-worker Database migrations, schema changes

MCP Servers

Server What it does
brainlayer 12 MCP tools — search 284K+ chunks, knowledge graph, entity contracts, health scoring, enrichment, BrainBar daemon
voicelayer 2 MCP tools — voice_speak (TTS) and voice_ask (STT Q&A), VoiceBar daemon
cmuxlayer 21 MCP tools — terminal multiplexer control, agent lifecycle, surface management
supabase Database access — tables, SQL, migrations
exa Web search — code context, company research

Links

Built by @EtanHey with Claude Code. Golems write code at 4am so you don't have to.