Core Concepts

This page covers the fundamental building blocks of alice. Understanding these concepts will help you create effective skills, set up useful automations, and get the most from the platform. Each concept links to detailed guides for deeper exploration.

Sources

Sources are the external data systems that alice connects to. They provide the raw data that skills query against. Each source is connected via OAuth -- you authorize alice to read from the service, and alice stores encrypted credentials that it uses when executing queries.

Currently supported sources

Coming soon

PostHog (product analytics), Linear (engineering tickets), Crisp (support tickets), HubSpot (CRM and deals), and more. See the source connection screen during onboarding for the latest list.

How sources work

When you connect a source, alice does the following:

1. OAuth authorization -- You grant alice read access to the service. For Stripe, this uses Stripe Connect. For Supabase, this uses Supabase's OAuth flow followed by a project picker where you select which project to query.

2. Schema discovery -- alice reads your data schema. For Supabase, this means table names, column names, column types, and approximate row counts. For Stripe, this means your subscription plans, customer count, and available API endpoints.

3. Credential storage -- Encrypted OAuth tokens are stored in alice's database. Tokens are never exposed to the client or logged. See Security for details on encryption and credential handling.

4. Query execution -- When a skill runs, alice uses the stored credentials to query the source in real time. Supabase skills execute SQL queries (always in read-only mode). Stripe skills call Stripe's API endpoints.

Source limits by plan

See Connect Stripe and Connect Supabase for step-by-step connection guides.

Skills

Skills are the core unit of work in alice. A skill is a saved query with a name, optional parameters, an output format, and optional triggers. Every skill automatically becomes a Slack slash command.

Anatomy of a skill

Query modes

Skills support five different query modes depending on the source type and your preference:

Visual Builder -- Select a Supabase table, pick columns, add filters, set ordering and limits through a point-and-click interface. No SQL required. Good for simple queries like "show me all users who signed up this week."

Raw SQL -- Write a SQL query directly for Supabase sources. Supports parameter placeholders ($1, $2) that bind to skill parameters. All queries are executed in read-only mode. Good for complex joins, aggregations, and window functions.

Stripe API -- Select a Stripe API endpoint (customers, subscriptions, charges, etc.) and configure parameters. alice translates this into the appropriate Stripe API call at execution time.

Stripe Metric -- Choose from pre-built metric blocks (MRR, churn rate, revenue by plan, etc.) that combine multiple Stripe API calls into a single computed result. Includes time period configuration for trend comparisons.

Combined -- Define multiple query steps across different sources and join the results. Each step can use any of the above modes. Steps execute in parallel, and results are joined in memory using a configurable join key (email, customer ID, or any shared field). See Combined Queries for details. Pro

Creating skills

There are three ways to create a skill:

1. Skill builder -- A 6-step wizard that walks you through Setup, Query, Format, Trigger, Schedule, and Review. See Create a Skill.
2. Templates -- Pre-built skills for common use cases (MRR tracking, churn risk, active users, etc.) that you can install and customize. See Skill Templates.
3. AI generation -- Describe what you want in plain English, and alice generates the query, parameters, and output configuration. See AI Skill Generation.

Skill limits by plan

See Plans and Limits for the full comparison.

Triggers

Triggers control when and how a skill executes. Every skill has at least one trigger (command), and you can add additional triggers for automation. Triggers are configured in the skill builder's Trigger and Schedule steps.

Command trigger (always active)

Every skill automatically gets a slash command trigger. When a user types /alice slug in Slack, the skill executes and returns the result. This trigger cannot be disabled -- it is always available.

/alice mrr
/alice churn-risk --days=60
/alice signups --since=monday

Command triggers respect skill permissions. You can restrict who can run a skill to everyone, admins only, owners only, or a specific list of Slack users.

See Slash Commands for the full command reference.

Cron trigger (scheduled reports)

Cron triggers execute a skill on a recurring schedule and post the results to a Slack channel. Common patterns:

Each cron trigger requires three settings:

• Schedule -- A cron expression or preset (daily, weekly, monthly)
• Timezone -- The timezone for the schedule (e.g., "America/New_York")
• Channel -- The Slack channel where results are posted

The Free plan allows 1 scheduled report (weekly only). Pro and Business plans allow unlimited scheduled reports. See Scheduled Reports for details.

Alert trigger (monitors)

Alert triggers check a skill's results on a polling interval and send a Slack notification when a condition is met. This turns a skill into a monitor that watches your data for important changes.

Each alert trigger requires:

• Poll interval -- How often to check (e.g., every 15 minutes)
• Condition -- The rule that triggers the alert. Conditions compare a result field against a threshold using operators like >, <, >=, <=, ==, !=, or changed
• Channel -- The Slack channel or DM for notifications

Examples of alert conditions:

The Free plan allows 3 monitors. Pro allows 25. Business allows unlimited. See Monitors for details.

Actions

Actions are safe, one-click operations that appear as buttons in Slack query results. When a skill returns data with action buttons, users can click a button to execute an operation on a specific result row without leaving Slack.

Available actions

How actions work

1. A skill executes and returns results in Slack with action buttons attached to each row
2. A user clicks an action button (e.g., "Tag in Stripe" next to a customer row)
3. alice executes the action using the credentials for the relevant source
4. The Slack message updates with a confirmation that the action completed

Safety by design

All actions in alice are non-destructive. The following operations are never available, regardless of plan or configuration:

This safety constraint is enforced at the server level and cannot be overridden. See Actions for the full guide and Action Buttons for the Slack UX details.

Action audit trail

Every action execution is logged with full context: who clicked it, which result row, what parameters were used, and the outcome. View action history at Dashboard > Logs or through the Logs section below.

Output types

Output types determine how a skill's query results are formatted when displayed in Slack. You configure the output type in the skill builder's Format step. alice supports four primary output types:

Table

The most common format. Displays results as a formatted table with column headers, aligned values, and optional header/footer templates.

Active Users -- Last 7 Days

| User              | Plan   | Last Login  | Sessions |
|-------------------|--------|-------------|----------|
| jane@acme.com     | Pro    | 2 hours ago | 34       |
| bob@startup.io    | Free   | 1 day ago   | 12       |
| carol@big.co      | Biz    | 3 hours ago | 89       |

Showing 3 of 247 users | Data from Supabase

Table output supports column-level formatting (currency, percentage, relative dates, email, number, truncated text) and configurable visibility per column. See Formatting Output for details.

Summary

Displays key-value pairs as a compact summary card. Best for single-metric queries like MRR tracking where you want to highlight a few key numbers.

MRR Summary -- February 2026

Current MRR:    $34,200  (+8.2%)
Active Subs:    847
Avg Revenue:    $40.38/customer
Churn Rate:     2.1%

Summary output supports an optional show_change flag on each field to display period-over-period changes.

List

Displays results as a list of items, each with a title, subtitle, and detail fields. Best for entity-focused queries like "show me customers at risk" where each row represents a person or account.

Churn Risk -- 3 accounts

1. jane@acme.com
   Pro plan | Last login: 18 days ago | Payment: Failed
   [Tag in Stripe] [Send DM]

2. bob@startup.io
   Free plan | Last login: 7 days ago | Card: Expiring
   [Tag in Stripe] [Send reminder]

3. carol@big.co
   Business plan | Last login: 30 days ago | Payment: Failed
   [Tag in Stripe] [Create ticket]

Text

A freeform text template with {{field}} interpolation. Best for simple, single-value outputs or custom message formats.

There are currently {{active_count}} active users on the {{plan_name}} plan,
generating {{mrr}} in monthly recurring revenue.

Choosing the right output type

See Formatting Output for detailed configuration of each output type, including column formats, templates, and empty-state messages.

Logs

Every skill execution and action execution is recorded in the audit log. Logs capture a complete record of what ran, who triggered it, what parameters were used, the full result, and how long it took.

What is logged

Viewing logs

Navigate to Dashboard > Logs to see all recent executions. You can filter by skill, user, status, trigger type, and date range.

Log retention by plan

Log data (stored in the skill_runs and action_runs tables) has a retention period based on your plan:

Expired logs are automatically cleaned up by a daily background job. See Plans and Limits for more on retention policies and Limits for the detailed limits reference.

How everything fits together

flowchart LR
    A["/alice mrr"] --> B[Slack API]
    B --> C[alice Server]
    C --> D{Query Source}
    D -->|Stripe| E[Stripe API]
    D -->|Supabase| F[Postgres DB]
    D -->|Combined| G[Both Sources]
    E --> H[Format Result]
    F --> H
    G --> H
    H --> I[Slack Message]
    I --> J["Action Buttons"]

Here is how the concepts relate to each other in a typical workflow:

1. You connect a source (Stripe) to alice during onboarding
2. You create a skill ("MRR Tracker") using the skill builder with a Stripe Metric query
3. You configure the output type as Summary with currency formatting
4. You add a cron trigger to run daily at 9am and post to #ops
5. You also add an alert trigger to notify #revenue if MRR drops below $40,000
6. Every morning, the cron trigger fires, the skill executes against Stripe, the result is formatted as a Summary, and posted to #ops. Each execution creates a log entry.
7. If MRR dips, the alert trigger catches it and sends a notification with action buttons to tag at-risk customers in Stripe.

Next steps

• Quickstart -- Set up alice and run your first query
• Onboarding Walkthrough -- Step through the full setup flow
• Create a Skill -- Build your first custom skill
• Slash Commands -- Full command reference
• Plans and Limits -- Compare what is available on each tier
• Query Syntax -- SQL and API query reference