Ella Claude Code Ai Agent

Ella — Claude Code AI Agent for Any Business

An autonomous, single-tenant AI chief-of-staff agent built on Claude Code. Talks via Telegram. Runs on a $20/mo VPS. Replicable for any business in under one hour.

[](LICENSE) [](https://claude.com/claude-code) [](CONTRIBUTING.md)

> Designed and built by Daniel Gonell — brand, UX & AI systems consultant.

> 📐 This is a template repository — the canonical source of truth. Click Use this template (or clone it) to start a deployment. Deployed agents are consumers: they pull updates into their own deployment and never push back here. See [AGENTS.md](AGENTS.md) for the rules agents follow.

---

What this is

This repo is a production-grade, idempotent installer + multi-tenant template for standing up an autonomous Claude Code AI agent for any business. The reference implementation runs a personal-brand consulting agent on Telegram. The same stack works for a fractional CMO, an agency owner, a SaaS founder, or a solo law firm by changing one config file.

What you get when you deploy this:

• An always-on chief-of-staff agent that triages every message you send via Telegram, delegates specialist work to 21 sub-agents (5 hand-built patterns + 16 cherry-picked from the agency-agents MIT collection), and never forgets a commitment via a persistent task ledger.
• A brand-voice + brand-visual single source of truth ([voice playbook](examples/voice-playbook.example.md) + [DESIGN.md](examples/DESIGN.md)) that voice-aware sub-agents read before drafting any human-facing copy or visual artifact. Banned phrases never ship.
• A knowledge graph (Graphify) the agent queries instead of grepping, plus Firecrawl MCP for web scraping, search, and structured extraction. Weekly auto-rebuild keeps the graph current with zero LLM cost.
• A morning-brief / proposed-moves system: every morning the agent posts 2–3 strategic proposals to Telegram with Run/Skip buttons. You tap. It executes via the right sub-agent.
• A proactive notification pipeline — 7 watchers that ping you when something needs attention without you having to ask. Task deadlines, goal pace, stalled deals, disk space, hot leads in inbox, calendar conflicts, brand drift. All event-driven, all dedup-logged, all dirt cheap (no LLM-per-check on 4 of them).
• Agent self-service ops — 5 sudoers-gated wrapper scripts let the agent update its own Claude Code binary, deploy the website, restart services, reload nginx, install systemd units WITHOUT your password. The wrappers are the audit boundary — raw sudo is still locked down.
• An autonomous deploy command: edit a YAML spec, send /deploy v1.2.3 from your phone, get one approval prompt after smoke tests pass, tap Ship. Code commits, pushes, and rolls out.
• A public-facing dashboard behind basic-auth ([Mission Control](docs/architecture.md#mission-control-dashboard)) showing real-time agent activity, task ledger, telemetry, goals, and per-task cost. Opens inline as a Telegram Mini App via /dashboard — no browser switch.
• Voice round-trip — Telegram voice notes get transcribed by local Whisper (auto-detects English vs Spanish), processed, and replied to via edge-tts audio. Three modes (off/reply/always) persisted via /voice.
• Channels-plugin patches (5 passes) — local TS patches to the upstream Telegram bot plugin add Ship/Hold/Revise on drafts, Run/Skip on proposals, Reply/Archive/Snooze on emails, forward-detection metadata, and the deploy callback flow. All idempotent + sentinel-checked.
• End-to-end smoke test — bash {agent_home}/scripts/smoke-test.sh runs 60+ checks across 12 sections (services, timers, scripts, plugin patches, bot identity, watchdog state, voice stack, knowledge graph). Re-runnable any time. Useful as a cron health check or after any system change.

What this is NOT:

• ❌ A wrapper around the Claude API. This runs on Claude Code with an Anthropic Max/Pro/Team subscription. ToS-clean. No API keys.
• ❌ A prompt-engineering project. Claude Code is the brain — this is infrastructure + governance + business-tier integrations around it.
• ❌ A SaaS. There's no hosted version. You deploy on your own VPS. You own everything.

---

Quick links

| If you want to... | Read | |---|---| | See the architecture end-to-end | [docs/architecture.md](docs/architecture.md) | | Install the agent on your laptop (local dev) | [docs/install-local.md](docs/install-local.md) | | Install the agent on a VPS (production) | [docs/install-vps.md](docs/install-vps.md) | | Customize for a new business / client / tenant | [docs/tenant-customization.md](docs/tenant-customization.md) — also [vps-setup/PORTING.md](vps-setup/PORTING.md) | | Understand how the agent decides which tool to use | [docs/tool-leverage-heuristics.md](docs/tool-leverage-heuristics.md) | | Lock down brand voice + visual identity | [docs/voice-and-visual-ssot.md](docs/voice-and-visual-ssot.md) | | See every external dependency and why | [docs/upstream-dependencies.md](docs/upstream-dependencies.md) | | Add the agent stack to an existing project (just the rituals layer) | [agent-stack/README.md](agent-stack/README.md) |

---

Architecture in one diagram

                 Phone (Telegram)
                        │
                        ▼
            ┌─────────────────────────┐
            │  Telegram Bot Channel   │   ← claude-code-plugins official + local patches
            │  (your @YourAgentBot)   │       (callback_data, voice notes, mini-apps)
            └────────────┬────────────┘
                         │
                         ▼
        ┌────────────────────────────────────┐
        │  Chief-of-Staff Agent              │   ← Claude Code in tmux, systemd-managed
        │  /opt/{tenant}/agents/             │      (CLAUDE.md = behavioral spec,
        │                                    │       rendered from agent-template)
        │  ┌──────────────────────────────┐  │
        │  │ Triage rules                 │  │   ← trivial / specialized / conversational / ambiguous
        │  │ Tool-leverage heuristics     │  │   ← when to fire firecrawl, graphify, sub-agents
        │  │ Task ledger                  │  │   ← state machine: proposed→committed→done
        │  │ Memory recall                │  │   ← knowledge-graph MCP across sessions
        │  └──────────────────────────────┘  │
        └────────────┬───────────────────────┘
                     │
       ┌─────────────┼─────────────────────────────────────────┐
       ▼             ▼                  ▼                      ▼
   Sub-agents   MCP tools         Brand canon            Public dashboard
   ─────────    ─────────         ───────────            ────────────────
   • 16 from    • GHL/HubSpot     • Voice playbook       • blueprint.{your-tld}
     agency-      (your CRM)      • DESIGN.md              (Cloudflare + nginx +
     agents     • Firecrawl       • Messaging              basic-auth + 60s pull)
   • Hand-      • Graphify          framework            • {your-tld}/dashboard
     built      • Memory MCP                                (Mission Control,
     domain     • Filesystem                                 telemetry, tasks,
     experts    • Playwright                                 goals, proposals)
                • Chroma RAG

The agent reads its behavioral spec (CLAUDE.md), looks at incoming messages, decides which tools and sub-agents to fire, executes work, narrates progress to the task ledger (which pings the user via Telegram), and emits proposals to act on tomorrow's moves.

---

What's in this repo

ella-claude-code-ai-agent/
├── README.md                          ← you are here
├── LICENSE                            ← MIT
├── agent-stack/                       ← Portable installer (works for any project, not just VPS)
│   ├── scripts/                         00-prereqs → 09-install-graphify, install-all, verify-all
│   ├── config/                          client.example.env, CLAUDE.md.template (engineering rituals)
│   ├── agency-agents-installer/         install.py + manifest + voice-paths.example.json
│   └── docs/per-server/                 chroma, fetch, filesystem, memory, playwright, superpowers
├── vps-setup/                         ← Multi-tenant agent template (production)
│   ├── PORTING.md                       end-to-end "spin up this stack for a new business"
│   ├── agent-template/                  CLAUDE.md.tmpl + scripts + dashboard + nginx + systemd + tasks
│   ├── tenants/EXAMPLE_TENANT.yml       comprehensive example tenant config (~150 lines, fully documented)
│   ├── scripts/                         render-tenant.sh, bootstrap-tenant.sh, health.sh, smoke.sh, preflight.sh
│   ├── runbooks/                        operating-principles.md (the 7 commitments)
│   └── mcp-patches/                     idempotent patch-applier for vendored MCP servers
├── docs/                              ← Deep-dive documentation
│   ├── architecture.md                  system architecture, file flow, service health
│   ├── install-local.md                 laptop install (Mac/Linux dev) — 15 min
│   ├── install-vps.md                   VPS install (production) — 60 min from blank Ubuntu
│   ├── tenant-customization.md          per-business customization
│   ├── tool-leverage-heuristics.md      when to fire which tool (the autonomy playbook)
│   ├── voice-and-visual-ssot.md         brand voice + DESIGN.md pattern
│   └── upstream-dependencies.md         every git repo / npm package / pypi package this depends on, with why
├── examples/                          ← Drop-in templates for any new tenant
│   ├── DESIGN.md                        blank Stitch 9-section visual SSOT template
│   ├── AGENTS.md                        blank brand-context template
│   └── voice-playbook.example.md        blank voice-DNA + banned-phrases template
└── CONTRIBUTING.md

---

Quick start (60-second TL;DR)

Local install (laptop)

# 1. Make sure Claude Code is installed and authenticated
claude --version
claude auth status

# 2. Clone this repo
git clone https://github.com/newmindsgroup/ella-claude-code-ai-agent.git ~/ella
cd ~/ella

# 3. Configure
cp agent-stack/config/client.example.env agent-stack/config/client.env
$EDITOR agent-stack/config/client.env

# 4. Install
bash agent-stack/scripts/install-all.sh

# 5. Drop the brand-voice + visual templates into your project repo
cp examples/AGENTS.md examples/DESIGN.md examples/voice-playbook.example.md /path/to/your/project/

That gives you the rituals + sub-agents + MCPs + brand-voice infrastructure in any Claude Code session.

VPS install (production always-on agent)

See [docs/install-vps.md](docs/install-vps.md) — the short version is:

# On a clean Ubuntu 22.04+ VPS, as root (from the cloned repo):
git clone https://github.com/newmindsgroup/ella-claude-code-ai-agent.git /tmp/ella
cd /tmp/ella

cp vps-setup/tenants/EXAMPLE_TENANT.yml vps-setup/tenants/.yml
$EDITOR vps-setup/tenants/.yml

# ONE command: render, create user, install Node/Claude, copy files, activate
# ops, install systemd units, AND (step 7d) install every capability —
# Graphify, MCP servers, agency-agents, Firecrawl, the memory-v2 embedding
# daemon, the Obsidian crontab, Mission Control, and all 31 timers.
sudo bash vps-setup/scripts/bootstrap-tenant.sh vps-setup/tenants/.yml

# Authenticate the subscription, then re-run the capability installer ONCE so the
# auth-dependent pieces (Superpowers, MCP servers, Graphify skill) finish:
sudo -u  -H claude login
sudo bash vps-setup/scripts/install-capabilities.sh vps-setup/tenants/.yml

install-capabilities.sh is idempotent and re-runnable — it's the one to run if a deploy ever looks incomplete (no Graphify, no Obsidian, missing timers). Verify with vps-setup/scripts/post-deploy-verify.sh (now includes a capability-coverage section).

Then point your domain's DNS at the VPS and you have a fully autonomous always-on agent reachable via your Telegram bot in ~60 minutes from blank Ubuntu.

Fresh-client deploy (v0.4+) — local Claude orchestrates the whole thing

For deploying a new client agent on a fresh VPS, the recommended flow is local-Claude orchestrated. You open Claude Code in a workspace folder, give it the client's credentials + brand context, and Claude SSH's to the VPS and walks through every step (DNS, TLS, Telegram, systemd, smoke test). About 30 minutes from "I have credentials" to "first morning brief fires."

mkdir -p ~/code/-workspace && cd ~/code/-workspace

# Get the latest templates
git clone --depth=1 https://github.com/newmindsgroup/ella-claude-code-ai-agent /tmp/ella-tmp
cp /tmp/ella-tmp/examples/client-credentials.template.md client-credentials.md
cp /tmp/ella-tmp/NEW-CLIENT-CLAUDE.md NEW-CLIENT-CLAUDE.md

# Fill in credentials + write a client-context.md
$EDITOR client-credentials.md     # tick every checkbox at the bottom
$EDITOR client-context.md         # paragraphs about the brand, voice, business

# Open Claude Code in the workspace and say:
#  "Deploy a fresh agent for this client following NEW-CLIENT-CLAUDE.md"
claude

Full runbook (12 phases, dependency-ordered): [vps-setup/DEPLOY-NEW-CLIENT.md](vps-setup/DEPLOY-NEW-CLIENT.md). Pre-flight check that validates every credential before mutating state: [vps-setup/scripts/preflight-new-client.sh](vps-setup/scripts/preflight-new-client.sh).

---

What makes this different

| Feature | Why it matters | |---|---| | Single-tenant, owned by you | Your VPS, your data, your Anthropic subscription. No SaaS vendor between you and your agent. | | ToS-clean | Built on Claude Code with a normal Anthropic Max/Pro/Team subscription. No API keys. No third-party brain wrappers. No grey-zone token reselling. | | Multi-tenant template | One config file (tenant.yml) drives every business-specific value. The engine is identical across tenants. Stand up a new client in under an hour. | | Brand voice as code | The voice playbook is a markdown file the agent reads before every draft. Banned phrases are absolute. No more catching "thrilled to" in copy review. | | Visual SSOT (DESIGN.md) | Companion to AGENTS.md. AI tools (Cursor, v0, Lovable, Claude Code) read it before generating UI. Same aesthetic across every project. Reusable as a client deliverable. | | Strategic tool autonomy | The chief-of-staff has explicit Tool-Leverage Heuristics in its CLAUDE.md mapping common situations to tool combos. It reaches for incident-response-commander when production breaks. It runs /graphify proactively before answering big-picture codebase questions. You don't memorize tool names. | | Real engineering discipline | [operating-principles.md](vps-setup/runbooks/operating-principles.md) is non-negotiable: idempotent installs, dry-runs before production changes, append-only audit logs, no force-push to main. The kind of discipline a real ops shop runs on. | | Mobile-first UX | Designed to be operated entirely from your phone via Telegram. Voice notes work. Inline approval buttons. Mini-apps for the dashboard. Voice round-trip in English/Spanish (extensible). |

---

The 21-strong sub-agent roster

The agent has a curated set of specialists it auto-routes to via "Use PROACTIVELY when..." description triggers — you don't memorize names, you describe what's needed.

Hand-built patterns (project-scoped — the examples live in [vps-setup/agent-template/CLAUDE.md.tmpl](vps-setup/agent-template/CLAUDE.md.tmpl); replace with your own):

• comms-agent — client-facing emails, Telegram replies, short social posts
• pipeline-agent — read-only CRM analysis, deal status, stalled-deal flagging
• `conte

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: newmindsgroup
• Source: newmindsgroup/ella-claude-code-ai-agent
• License: MIT
• Homepage: https://danielgonell.com

Install and usage instructions live in the source repository linked above.