# Ella Claude Code Ai Agent > Autonomous AI chief-of-staff agent built on Claude Code. Multi-tenant template β€” blank Ubuntu VPS to a Telegram-reachable agent in under an hour. Memory, sub-agent swarms, observability, voice. - **Type:** MCP server - **Install:** `agentstack add mcp-newmindsgroup-ella-claude-code-ai-agent` - **Verified:** Pending review - **Seller:** [newmindsgroup](https://agentstack.voostack.com/s/newmindsgroup) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [newmindsgroup](https://github.com/newmindsgroup) - **Source:** https://github.com/newmindsgroup/ella-claude-code-ai-agent - **Website:** https://danielgonell.com ## Install ```sh agentstack add mcp-newmindsgroup-ella-claude-code-ai-agent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://danielgonell.com)** β€” 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](https://github.com/msitarzewski/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](https://github.com/safishamsi/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](https://github.com/rany2/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) ```bash # 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: ```bash # 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." ```bash 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](https://github.com/newmindsgroup) - **Source:** [newmindsgroup/ella-claude-code-ai-agent](https://github.com/newmindsgroup/ella-claude-code-ai-agent) - **License:** MIT - **Homepage:** https://danielgonell.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: flagged β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-newmindsgroup-ella-claude-code-ai-agent - Seller: https://agentstack.voostack.com/s/newmindsgroup - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.