Skip to content

nicodlz/hermes

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

61 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Hermes ⚑

Modern CRM for AI-powered Sales Development Representatives (SDR)

Hermes is a lightweight, self-hosted CRM designed for solo developers and small teams who want to automate their outreach workflow using AI agents.

TypeScript Hono React License

Features

  • πŸ“Š Lead Pipeline β€” Track leads from scrape to close with customizable stages
  • πŸ€– AI-First API β€” Endpoints designed for agent automation (OpenClaw, LangChain, etc.)
  • πŸ“§ Template System β€” Reusable outreach templates with variable substitution
  • πŸ“ˆ Analytics β€” Conversion funnel, response rates, and daily stats
  • βœ… Task Management β€” Follow-ups, calls, and action items with due dates
  • πŸ”Œ SQLite β€” Zero-config database, portable, easy backups

Tech Stack

Layer Technology
API Hono + Zod
Database Prisma + SQLite
Frontend React 19 + TanStack Query
Styling Tailwind CSS v4
Build Turborepo + pnpm

Quick Start

# Clone
git clone https://github.com/nicodlz/hermes.git
cd hermes

# Install
pnpm install

# Setup database
pnpm db:generate
pnpm db:push
pnpm db:seed

# Start development
pnpm dev

API Reference

AI Agent Endpoints

Endpoint Method Description
/api/ai/digest GET Daily summary with action items
/api/ai/next-actions GET Pending tasks and leads needing attention
/api/ai/qualify/:id POST Score a lead with AI analysis
/api/ai/outreach/:id POST Generate outreach from template

Lead Management

Endpoint Method Description
/api/leads GET List with filters (status, score, search)
/api/leads/:id GET Full details with notes and messages
/api/leads POST Create lead
/api/leads/:id PATCH Update status, contact info
/api/leads/bulk POST Batch create from scraper

Other Resources

  • /api/tasks β€” Task management
  • /api/templates β€” Message templates
  • /api/stats β€” Analytics and metrics
  • /api/sources β€” Scraping source config

See full documentation in skills/hermes/SKILL.md.

Lead Pipeline

NEW β†’ QUALIFIED β†’ CONTACTED β†’ RESPONDED β†’ CALL β†’ PROPOSAL β†’ WON
 ↓        ↓           ↓
ARCHIVED  ARCHIVED   FOLLOWUP_1 β†’ FOLLOWUP_2 β†’ LOST

Scoring System

Default Ideal Customer Profile (ICP):

  • Budget: $1k-10k
  • Stack: React, TypeScript, Node.js, Next.js, Web3
  • Timeline: 2-6 weeks
  • Work style: Remote, async

Scoring rules:

  • +10 Has [Hiring] tag
  • +10 Budget mentioned
  • +5 Remote position
  • +5 Per matching technology
  • -20 Red flag (equity only, unpaid test, etc.)

Qualify threshold: 15+

Authentication

Hermes uses Magic Link authentication β€” no passwords required!

Flow

  1. User enters email β†’ receives magic link
  2. Click link β†’ session created (30-day cookie)
  3. API keys for agents/integrations

API Key Authentication

For agents like Atlas/OpenClaw, use API keys:

# Create via UI (Settings β†’ API Keys) or admin endpoint
curl -X POST https://hermes.ndlz.net/api/admin/api-keys \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"Atlas Agent"}'

# Use the key
curl https://hermes.ndlz.net/api/leads \
  -H "X-API-Key: hms_xxxxxxxxxxxx"

Environment Variables

Variable Required Description
DATABASE_URL Yes SQLite path: file:/app/data/hermes.db
PORT No API port (default: 3001)
RESEND_API_KEY Yes Resend API key for emails
FROM_EMAIL No Sender email (default: hermes@ndlz.net)
APP_URL No App URL for magic links (default: https://hermes.ndlz.net)
ADMIN_SECRET No Secret for admin API (generate with openssl rand -hex 32)

Deployment

Docker

docker build -t hermes .
docker run -p 3001:3001 -v hermes-data:/app/data hermes

Docker Compose

docker-compose up -d

Coolify / Self-hosted

  1. Connect repository
  2. Build: pnpm install && pnpm db:generate && pnpm build
  3. Start: node apps/api/dist/server.js
  4. Add volume for /app/data (SQLite persistence)

AI Agent Integration

OpenClaw

Add the Hermes skill to your workspace:

cp -r skills/hermes ~/.openclaw/workspace/skills/

Example cron job for daily digest:

schedule:
  kind: cron
  expr: "0 9 * * *"
  tz: "Europe/Lisbon"
payload:
  kind: agentTurn
  message: "Check Hermes daily digest: GET /api/ai/digest"
sessionTarget: isolated

Other Agents

Any agent that can make HTTP requests works. Example with curl:

# Get what needs attention
curl http://localhost:3001/api/ai/next-actions

# Qualify a lead
curl -X POST http://localhost:3001/api/ai/qualify/abc123 \
  -H "Content-Type: application/json" \
  -d '{"score": 35, "reasons": ["+budget", "+remote"]}'

Project Structure

hermes/
β”œβ”€β”€ apps/
β”‚   β”œβ”€β”€ api/          # Hono API server
β”‚   └── web/          # React frontend
β”œβ”€β”€ packages/
β”‚   └── db/           # Prisma schema & client
β”œβ”€β”€ skills/
β”‚   └── hermes/       # OpenClaw skill
└── docker-compose.yml

License

MIT Β© Nicolas Timon

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors