Introduction to Aether

Active Development

Aether is under rapid, active development. This documentation reflects the current state of the codebase. Features and APIs may change without notice between releases.

Aether is a webhook processing and AI agent orchestration platform. It sits between your development tools (GitHub, GitLab, Jira, Plane) and AI agents, automatically routing events, calling LLMs, and posting responses back — without you writing any glue code.

What Aether Does

When a developer opens a pull request on GitHub, Aether can:

1. Receive the webhook from GitHub
2. Normalize it to a canonical event (pr.opened)
3. Look up which tasks run for that trigger
4. Call each task's assigned agent (PM, TA, QA) via LLM
5. Post the AI responses back as comments on the PR

All of this happens automatically, without any manual intervention.

Key Concepts

Webhooks

External services send HTTP callbacks to Aether when events occur. Aether verifies the signature, normalizes the event, and routes it for processing. All webhooks are received at a single unified endpoint:

POST /webhook/:slug

Where :slug identifies the source (e.g., github, jira, or a custom slug for dynamic integrations).

Canonical Triggers

Rather than writing source-specific handling code, Aether maps every incoming event to a canonical trigger — a normalized event name like issue.created or pr.merged. This means your agents work the same way regardless of whether the event came from GitHub or Jira.

Tasks

A task is a unit of work triggered by a canonical event. Tasks define:

• Which agent (or fallback prompt) handles the work
• A description of what the agent should do

Multiple tasks can be mapped to a single trigger. For example, issue.created might trigger both a PM analysis task and a TA feasibility review task.

Agents

Agents are AI personas with specific roles, system prompts, and capabilities. Built-in roles:

• PM — Requirements analysis, scope clarification, project management
• Technical Analyst (TA) — Architecture, feasibility, estimates, code review
• QA — Testing strategy, deployment verification, UAT
• Developer (Dev) — Code implementation and guidance
• Hub — System orchestration

Agents can also connect externally via the gRPC Agent Gateway (see Agent Runtime Protocol).

Projects

Projects group your configuration together. Each project maps to an external source repository or project (e.g., a GitHub repo or Jira project) and determines which webhooks are accepted and how they are processed.

Memory

Agents have access to a tiered memory system:

• Short-term (Redis) — Session context, cleared automatically
• Long-term (PostgreSQL) — Persistent memories across sessions
• Semantic search (pgvector) — Find relevant memories by meaning, not just keywords

Memory is automatically injected into LLM context when relevant.

Event Flow

External Service (GitHub / GitLab / Jira / Plane)
         │
         │ POST /webhook/:slug
         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Aether Backend                               │
│                                                                     │
│  1. Verify signature / token                                        │
│  2. Persist webhook event                                           │
│  3. Normalize: source event → canonical trigger (DB lookup)         │
│  4. Resolve tasks for trigger (DB lookup)                           │
│  5. For each task:                                                  │
│     a. Retrieve assigned agent + prompt                             │
│     b. Inject relevant memories                                     │
│     c. Call LLM via LiteLLM                                        │
│     d. Handle tool calls (add_comment, update_issue, etc.)         │
│     e. Post response back to issue tracker                         │
└─────────────────────────────────────────────────────────────────────┘

With External Agents (gRPC)

If an agent is registered as an external agent via the gRPC Gateway, Aether publishes the task to the agent's stream. The external agent processes it using its own logic and reports completion or failure via gRPC.

System Architecture

┌────────────────────────────────────────────────────────────────────┐
│                     External Services                               │
│            GitHub  ·  GitLab  ·  Jira  ·  Plane                   │
└───────────────────────────┬────────────────────────────────────────┘
                            │ Webhooks
                            ▼
┌────────────────────────────────────────────────────────────────────┐
│                    Aether Go Backend (Fiber)                        │
│                                                                    │
│  ┌──────────────┐   ┌──────────────┐   ┌───────────────────────┐  │
│  │   Webhook    │──▶│ Task/Event   │──▶│     LLM Service       │  │
│  │   Handler    │   │   Resolver   │   │  (tool calling, mem)  │  │
│  └──────────────┘   └──────────────┘   └──────────┬────────────┘  │
│                                                    │               │
│  ┌──────────────────────────────────────────────── │ ──────────┐   │
│  │              gRPC Agent Gateway (port 9090)      │          │   │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ │          │   │
│  │  │  LLM Hub │ │Tool Hub  │ │Mem Hub │ │ Msg  │ │          │   │
│  │  └──────────┘ └──────────┘ └────────┘ └──────┘ │          │   │
│  └─────────────────────────────────────────────────│──────────┘   │
└────────────────────────────────────────────────────│───────────────┘
                        │                            │
       ┌────────────────┼───────────────┐            │
       ▼                ▼               ▼            ▼
┌────────────┐  ┌──────────────┐  ┌─────────┐  ┌─────────┐
│ PostgreSQL │  │    Redis     │  │  NATS   │  │LiteLLM  │
│ +pgvector  │  │(mem/ratelimit│  │(JetStre)│  │  Proxy  │
└────────────┘  └──────────────┘  └─────────┘  └─────────┘
       ▲
┌──────┴──────┐
│  External   │
│   Agents    │  (Python / Go / TypeScript via gRPC)
└─────────────┘

Key Components

Component	Port	Description
Go Backend (HTTP)	8000	REST API, webhook handling
gRPC Agent Gateway	9090	External agent connection point
React Frontend	3000 (docker) / 5173 (dev)	Configuration and monitoring UI
LiteLLM Proxy	4000	Unified LLM interface
PostgreSQL	5432	Primary data store with pgvector
Redis	6379	Short-term memory and rate limiting
NATS	4222	Async task queue and inter-agent messaging

Database-Backed Configuration

All configuration lives in PostgreSQL, not in files. This enables:

• Runtime changes via the API or frontend — no restarts required
• YAML-based seeding to version-control your configuration
• Idempotent seeding (re-run at any time without duplication)
• Easy backup, restore, and environment promotion

The key tables:

• agents — Agent definitions with prompts
• tasks — Task definitions with actor assignments
• source_event_mappings — Maps source events to canonical triggers
• trigger_task_mappings — Maps canonical triggers to tasks
• projects — Project workspaces
• webhook_mappings — Advanced routing rules

Next Steps

1. Install Aether — Get running with Docker Compose
2. Configure Integrations — Connect to GitHub, Jira, and your LLM
3. Set Up Webhooks — Configure GitHub, Jira, and Plane to send events
4. Create an Agent — Define your first AI agent
5. Set Up a Project — Configure your first project
6. Understand Routing — Learn the event routing system