Myaaw is a cat who becomes your personal AI assistant.

• Multimodal Input: Supports Text, Voice (Transcribed), and Image input.
• Smart Responses: Supports both Basic and Streamed responses for real-time interaction.
• Conversation Memory: Remembers your chat history for natural flow.
• Agent Skills: Dynamically extensible capabilities via SKILL.md definitions.
• Powerful Tools: Native integration with Filesystem, Bash, and Python execution.
• Heartbeat (Autonomous Check): Scheduled background checks for health and tasks via HEARTBEAT.md.
• CLI Voice Chat: Native support for Real-time Voice (Gemini Live) and Classic STT/TTS pipeline with screen/camera sharing via CLI.

Myaaw currently focuses on delivering the best experience with Google Gemini API.

Myaaw can be integrated with various platforms:

• 📨 Telegram: Integration via Bot API (Polling or Webhook).
• 👾 Discord: Integration via Discord Bot.
• 💻 Terminal: Interactive TUI chat and CLI management.

• ✨ Key Features
• 🤖 Supported Providers
• 📡 Supported Channels
• 🏗 Architecture
• 🚀 Quick Start (Non-Technical)
• 🛠 Development
  • Prerequisites
  • Getting Started
  • Start Development
  • Generate Swagger Documentation
  • Build from Source
• 💻 Myaaw CLI Reference

Myaaw follows a modular, service-oriented architecture designed to seamlessly handle multiple communication channels, queue-based background processing, and a robust AI Agentic loop.

graph TD
    %% Users
    User([User])

    %% Entry Points
    subgraph "Channels & Entry Points"
        TG[Telegram Bot]
        DC[Discord Bot]
        CLI_Term[Terminal CLI]
        CLI_Voice[Voice CLI / Gemini Live]
        CLI_Classic[Voice Classic CLI]
        API[REST API]
    end

    User <--> TG
    User <--> DC
    User <--> CLI_Term
    User <--> CLI_Voice
    User <--> CLI_Classic
    User <--> API

    %% Async processing
    subgraph "Message Queue Layer"
        MQ[(RabbitMQ)]
    end

    TG --> MQ
    DC --> MQ

    %% Core Services
    subgraph "Core System"
        Router[Fiber Server]
        BotSvc[Bot Service]
        ChReg[Channel Registry]
        DB[(MongoDB)]
        Cache[(Redis)]
    end

    API --> Router

    %% Consumer & Background Tasks
    subgraph "Consumer Daemon"
        Consumer[Myaaw Consumer]
        Cron[Cron Scheduler]
        Heartbeat[Heartbeat Monitor]
    end

    MQ --> Consumer
    
    Cron -- "Webhook forwarding" --> Router
    Heartbeat -- "Webhook forwarding" --> Router
    Consumer -- "Webhook forwarding" --> Router

    Router --> BotSvc
    CLI_Term --> BotSvc

    BotSvc <--> ChReg
    BotSvc <--> DB
    BotSvc <--> Cache

    %% Agentic Layer
    subgraph "Agentic Layer"
        Agent[ReAct Agent Loop]
        Tools[Tools: Bash, FS, Python]
        Prov[Providers: Gemini]
    end

    %% Agent Local Workspace
    subgraph "Local Workspace"
        direction TB
        Skills[~/.myaaw/skills/ <br> Additional Agent Skills]
        Home[~/.myaaw/home/ <br> AGENTS.md, BOOTSTRAP.md, HEARTBEAT.md, <br> MEMORY.md, SOUL.md, TOOLS.md, USER.md, <br> memory/]
    end

    BotSvc <--> Agent
    CLI_Classic <--> Agent
    CLI_Voice <--> Prov
    Agent <--> Tools
    Agent <--> Prov
    
    Agent -. "Loads definitions" .-> Skills
    Agent -. "Reads/Writes" .-> Home

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px,color:#000;
    classDef storage fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#000;
    classDef core fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000;
    classDef agent fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#000;
    classDef auto fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#000;
    classDef wksp fill:#e0f7fa,stroke:#00acc1,stroke-width:2px,color:#000;
    
    class MQ,DB,Cache storage;
    class BotSvc,Router,ChReg core;
    class Agent,Tools,Prov agent;
    class Consumer,Cron,Heartbeat auto;
    class Skills,Home wksp;

1. Channels (internal/channel): The entry point for interactions. It provides an Adapter interface to normalize messages from Telegram, Discord, REST APIs, or Terminal CLI into a standard format.
2. Gateway & Daemons (cmd/myaaw): Uses Cobra CLI to manage the application. It runs the Fiber v3 Web Server and the RabbitMQ Consumer as independent background daemons. It also provides pure CLI modalities like myaaw chat and myaaw voice.
3. Bot Service (internal/services/bot): The core brain of the application. It processes normalized messages from external channels and Terminal CLI, retrieves chat history from MongoDB, and invokes the AI Agent. Voice CLIs (myaaw voice/voice-classic) bypass this to connect directly to the Agent/Providers for lower latency.
4. Agentic Layer (internal/agent): Implements the ReAct (Reasoning and Action) loop. It intelligently decides when to interact with the LLM or when to execute tools (Bash, Python, FileSystem) to accomplish the user's objective.
5. Providers (internal/provider): A factory-based abstraction layer for various LLMs (Gemini, OpenAI, Groq, Ollama), Transcribers (STT), and Synthesizers (TTS). Currently, Gemini is the main provider for Myaaw's intelligence and live-voice functionality.
6. Message Queue (internal/services/queue): Handles asynchronous webhook messaging. Webhook payloads are pushed to RabbitMQ and processed by the Consumer daemon to reliably deliver messages.
7. Automation (internal/cron, internal/heartbeat): Background schedulers residing inside the Consumer Daemon. The cron handles scheduled messages, while the heartbeat autonomously wakes up the agent at intervals to check HEARTBEAT.md for pending background duties.
8. Local Workspace (~/.myaaw): The operational directory for the Agent.
   • skills/: Dynamically parsed text definitions of new tools that Myaaw can learn and execute.
   • home/: Long-term file storage containing Myaaw's core definitions:
     • AGENTS.md / SOUL.md: Persona and behavior instructions.
     • BOOTSTRAP.md / TOOLS.md: Initialization steps and tool usage rules.
     • USER.md: Facts and details learned about the user.
     • HEARTBEAT.md: Ongoing active background jobs and tasks.
     • MEMORY.md & memory/: Historical conversation summarizations and logs.

If you just want to use Myaaw without worrying about code:

1. Download Myaaw: Go to Releases and download the binary for your OS (e.g., myaaw-windows-amd64.exe or myaaw-macos-arm64).
2. Onboard: Open your terminal/command prompt in the folder where you downloaded it and run:

   ./myaaw onboard

   This will guide you through setting up your API keys and configuration.
3. Start Databases: If you have Docker installed, run:

   myaaw docker setup

4. Launch:

   myaaw gateway start

5. Check Status:

   myaaw status

Before you start, ensure you have:

• Go 1.26.0 or later installed.
• Docker installed (for services).

The myaaw voice feature relies on native system libraries for audio (PortAudio) and screen/camera capture. If you are building from source, you must install these dependencies:

macOS

brew install pkg-config portaudio

Note: macOS will prompt for Microphone, Screen Recording, and Camera permissions upon first use.

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y portaudio19-dev libasound2-dev pkg-config
# For screen/camera capture:
sudo apt install -y libx11-dev libxext-dev

Windows Building with CGo on Windows requires a C compiler environment like MSYS2/MinGW:

1. Install MSYS2.
2. Open MSYS2 MinGW 64-bit terminal and run:

   pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-portaudio

Myaaw requires Redis, MongoDB, and RabbitMQ. You can start all of them with a single command:

docker compose up -d

Alternative (CLI): If you prefer using the built-in CLI for setup and monitoring:

go run ./cmd/myaaw docker setup
go run ./cmd/myaaw status

1. Clone the Repository

   git clone https://github.com/Shiyinq/myaaw.git
   cd myaaw

2. Install Dependencies Like npm install for package.json, you should download the Go modules:

   go mod tidy

3. Onboard (Dev Mode) Since you have the source code, you can run the onboarding flow directly:

   go run ./cmd/myaaw onboard

Once everything is set up, you can start the gateway using one of the following methods:

go run ./cmd/myaaw gateway start

If you want the server to restart automatically when you change the code, use Air.

1. Install it globally (first time only):

   go install github.com/air-verse/air@latest

2. Run it in the root directory:

   air

Monitor Status & Logs: In a separate terminal, you can monitor the gateway:

go run ./cmd/myaaw status
go run ./cmd/myaaw logs

Swagger documentation is automatically updated every time you run make build or make install.

1. Manual Update If you only want to update the documentation without building:

   make swagger

2. Accessing the UI Once the server is running, the interactive documentation is available at: http://localhost:8080/docs/index.html

If you want to build the Myaaw binaries yourself (e.g., for distribution or custom versions), you can use the provided Makefile:

1. Build for current platform:

   make build

2. Cross-compile for all platforms:

   make build-all

   This will generate binaries for macOS (Intel/M1), Linux, and Windows in the bin/ directory.

The myaaw CLI is your control center for managing the AI assistant, infrastructure, and services. You can run these commands via go run ./cmd/myaaw (Development) or simply myaaw (if installed globally).

Myaaw runs as two components: a Server (Gateway/API) and a Consumer (Task processing).

Myaaw includes a built-in scheduler to automate tasks (like sending recurring messages or reminders).

Examples:

# Every morning at 7 AM
myaaw cron add --name "Morning Greeting" --cron "0 7 * * *" --message "Selamat Pagi!" --channel telegram --to 123456789

# Every 2 hours
myaaw cron add --name "Hydration Check" --every "2h" --message "Drink water!" --channel telegram --to 123456789

# One-time reminder in 30 minutes
myaaw cron add --name "Meeting Remind" --at "30m" --message "Meeting in 30 mins" --channel telegram --to 123456789