<div align="center"> <img src="References/Moxielabs.png" alt="Logo Moxielabs" width="200" />

Moxie Labs

AI Agent for Creative Agency

</div>

ℹ️ Note: This is Version 1.0.0. While fully functional, it is still in its early stages. Expect rapid updates, potential bugs, and breaking changes as we refine the architecture.

---

📖 Overview

Moxie Labs is an autonomous, multi-agent system designed to function as a full-fledged Creative Agency. Built on top of CrewAI and orchestrated via Telegram, it eliminates generic, templated outputs by simulating a real agency workflow—comprising a Trend Researcher, Art Director, Copywriter, QA Specialist, and a Creative Director.

Instead of chatting with a single AI, you are directing a team. Send a brief, and Moxie Labs will research trends, draft visual specifications, write copy, audit for WCAG accessibility, and deliver a final package containing Markdown reports, YAML tokens, and raw HTML/React code.

---

🧠 Architecture Diagram

graph TD
    User[👤 User via Telegram] -->|Brief / Prompt| Director[🎤 Creative Director]

    Director -->|Delegates Tasks| Researcher[🔍 Trend Researcher]

    Researcher -->|Trends & Moodboards| ArtDirector[🎨 Art Director]
    Researcher -->|Context & Tone| Copywriter[✍️ Copywriter]

    ArtDirector -->|Visual Specs| QA[🔎 QA & Critique]
    Copywriter -->|Copy Drafts| QA

    QA -->|Approved Assets| Director
    Director -->|Final Report + Code + Handoff| User

---

✨ Core Capabilities

Multi-Agent Production

Trigger full agency workflows:

• /create
• /ui
• /ux
• /brand
• /design_system
• /audit

The system parses its own output to deliver a clean .zip archive containing:

• Agency_Report.md — Creative rationale
• Project_Data.yaml — Design tokens, fonts, colors
• Component.jsx or Mockup.html — Raw frontend code
• Engineering_Handoff.md — Technical brief for developers

Vision & UI Audit

Send a screenshot, and the system will critique alignment, contrast, and visual hierarchy.

Image to Code

Send a screenshot with the caption /code to automatically generate HTML/Tailwind or React/JSX code matching the design.

Quick Commands

Fast, single-LLM responses for rapid prototyping.

Examples:

• /palette
• /fonts
• /abtest
• /rewrite
• /component

Local Moodboard Analyzer

Read and analyze local reference images to extract visual vibes, palettes, and layouts.

Auto-Pilot Scheduler

Schedule daily automated creative tasks directly from Telegram.

Smart Formatting

Automatically formats AI Markdown responses into clean Telegram HTML, with smart chunking to prevent message cutoffs.

---

🛠 Tech Stack

| Component | Technology | |-----------|------------| | Agent Framework | CrewAI | | Interface | python-telegram-bot | | LLM Routing | OpenAI-compatible API | | Scheduling | APScheduler | | Containerization | Docker (using uv for lightning-fast dependency installation) |

---

🚀 Quick Start

Prerequisites

• Docker installed on your machine.
• A Telegram Bot Token (from @BotFather).
• An OpenAI-compatible API endpoint (OpenAI, Groq, OpenRouter, or a local gateway).

---

1. Clone the Repository

git clone https://github.com/Maventlabs/Moxielabs.git
cd Moxielabs

---

2. Setup Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_ALLOWED_USER_ID=your_telegram_user_id

ROUTER_BASE_URL=http://host.docker.internal:20128/v1
ROUTER_API_KEY=your_api_key

MODEL_NAME=your_model_name
EMBEDDING_MODEL_NAME=your_embedding_model_name

Example:

• MODEL_NAME=gpt-4o
• EMBEDDING_MODEL_NAME=text-embedding-3-small

---

3. Configure Your Team

Edit:

• agents_config.yaml to define your sub-agents' roles.
• SOUL.md to define the Creative Director's personality and communication style.

---

4. Build and Run with Docker

docker build -t moxie-labs .

docker run -d `
  --name moxie-labs `
  --restart unless-stopped `
  -v ${PWD}:/app `
  -p 18791:18791 `
  moxie-labs

---

🧩 Personal Recommended Skills

Moxie Labs supports external skills to enhance the Creative Director's knowledge base.

You can install these skills locally and load them in Telegram using @skill_name.

Here are some highly recommended skills from the community (compatible with the skills.sh ecosystem):

| Category | Command | |----------|---------| | Design Taste | npx skills add Leonxlnx/taste-skill | | UI/UX Patterns | npx skills add shadcn/ui-component-creator | | Frontend Development | npx skills add vercel/nextjs-developer | | Styling | npx skills add tailwindlabs/tailwind-designer | | Accessibility | npx skills add dequelabs/axe-accessibility |

Place the downloaded .md skill files in your mounted skills directory.

Type /skills in Telegram to verify they are loaded.

---

📝 Usage Commands

| Command | Description | |---------|-------------| | /start | Wake the system and view the main menu. | | /create [brief] | Start a full agency production. Output: .zip archive. | | /ui [brief] | Production focused on Visual UI & Components. | | /brand [brief] | Production focused on Brand Identity & Guidelines. | | /palette [theme] | Generate 5 HEX color palettes with psychology. | | /component [desc] | Generate HTML/Tailwind or React snippet. | | /abtest [feature] | Generate A/B test copywriting variants. | | /sched_add HH:MM [type] [brief] | Schedule a daily automated creative task. |

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create.

Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch

git checkout -b feature/AmazingFeature

1. Commit your Changes

git commit -m "Add some AmazingFeature"

1. Push to the Branch

git push origin feature/AmazingFeature

1. Open a Pull Request

Please read the CONTRIBUTING.md file (coming soon) for more details on our code of conduct and development guidelines.

---

📜 License

Distributed under the MIT License.

See LICENSE for more information.

---

<div align="center">

_{Built by by <a href="https://github.com/Maventlabs">Mavent Labs</a>}

</div>