Insights Agent

Autonomous AI agent that monitors data sources and sends actionable insights to Slack.

Overview

Insights Agent is a fully autonomous background agent that continuously monitors multiple data sources (SQL databases, analytics platforms), discovers meaningful patterns and anomalies, and sends actionable insights to Slack.

Key Features

• 🤖 Fully Autonomous: No manual rules or queries needed
• 📊 Multi-Source: Supports PostgreSQL, MySQL, SQLite, Google Analytics, MS Clarity
• 💡 Actionable: Every insight includes specific recommended actions
• 🔄 Self-Learning: Adapts based on user feedback
• 🔥 Hot Reload: Update config without restart

Quick Start

Prerequisites

• Bun v1.0+ (required)
• A Slack workspace
• At least one database to monitor
• LLM API key (Anthropic, OpenAI, or Google)

Installation & Setup

# Run the interactive setup wizard
bunx insights-agent setup

# Start the agent
bunx insights-agent start

The setup wizard will guide you through:

1. Creating a Slack App (one-click with pre-configured manifest)
2. Entering Slack credentials
3. Configuring database connection
4. Setting up LLM provider

Manual Configuration

For advanced users, you can manually configure:

# Clone the repository
git clone https://github.com/wordbricks/insights-agent.git
cd insights-agent

# Install dependencies
bun install

# Copy and edit config
cp config.example.yaml config.yaml
$EDITOR config.yaml

# Start the agent
bun run start

See config.example.yaml for all available options.

CLI Commands

# Interactive setup wizard (creates config.yaml)
insights-agent setup

# Start the agent
insights-agent start [--config <path>]

# Stop the agent
insights-agent stop

# Check status
insights-agent status

Web Dashboard

Access the dashboard at http://localhost:3847/dashboard:

• /dashboard - Overview with agent status and recent insights
• /dashboard/stats - Detailed statistics and charts
• /dashboard/history - Complete insight history with filters

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/health | Health check | | POST | /api/pause | Pause notifications | | POST | /api/resume | Resume notifications |

Development

# Run in development mode (with hot reload)
bun run dev

# Type check
bun run typecheck

# Lint
bun run lint

# Run tests
bun run test

# Run all checks
bun run check

Architecture

Main Orchestrator Agent
├── Business Context Sub-Agent
├── Schema Explorer Sub-Agent
├── Analytics Analyzer Sub-Agent
└── Insight Generator Sub-Agent

The agent uses Vercel AI SDK v6 with a tool-based architecture. Each sub-agent is implemented as a tool that the main orchestrator can call.

Documentation

• SPEC.en.md - Full technical specification (English)
• SPEC.ko.md - Full technical specification (Korean)
• CLAUDE.md - AI coding guidelines
• Agent.md - Agent system prompt

License

MIT License - see LICENSE for details.