Getting Started

Prerequisites

• Bun v1.0+ — JavaScript runtime and package manager
• One or more LLM API keys — Google Gemini, Anthropic Claude, OpenAI, or Ollama running locally

Installation

From npm

# Install with Bun (recommended)
bun add @ahmedtaha/aether

# Or with npm
npm install @ahmedtaha/aetherbash

From source

git clone https://github.com/SufficientDaikon/aether.git
cd aether
bun installbash

Quick Start

1 Initialize your workspace

bun run bin/aether.ts initbash

This command:

• Scans your project and detects the tech stack
• Detects available LLM providers from environment variables
• Creates the .aether/ directory with config.json and settings.json
• Discovers any .agent.md files in your workspace

2 Set up API keys

Set environment variables for your LLM providers:

# Google Gemini (recommended — free tier available)
export GOOGLE_AI_KEY="your-key-here"

# Anthropic Claude
export ANTHROPIC_API_KEY="your-key-here"

# OpenAI
export OPENAI_API_KEY="your-key-here"

# Ollama (no key needed — runs locally)
# Just install and run: ollama servebash

3 Run your first task

bun run bin/aether.ts run "explain the project structure"bash

AETHER routes your task through the agent hierarchy — cortex-0 decomposes it, managers coordinate, and workers execute. You'll see the result streamed back to your terminal.

4 Start the WebSocket server

bun run bin/aether.ts linkbash

Starts Aether-Link on port 9999 with the BAP-02 binary protocol. Use this for real-time integration with editors and external tools.

5 View registered agents

bun run bin/aether.ts registrybash

Prints an ASCII table of all 34 registered agents with their tier, section, and status.

Configuration

After aether init, two config files live in .aether/:

.aether/config.json auto-generated

{
  "version": "0.2.0",
  "providers": {
    "master":  { "provider": "gemini", "model": "gemini-pro" },
    "manager": { "provider": "gemini", "model": "gemini-pro" },
    "worker":  { "provider": "gemini", "model": "gemini-flash" }
  },
  "server": { "port": 9999, "host": "localhost" }
}json

.aether/settings.json user-editable

{
  "methodology": { "mode": "tdd", "testCommand": "bun test" },
  "agents": { "maxConcurrent": 10 },
  "execution": { "maxDepth": 3, "temperature": 0.7 },
  "escalation": { "threshold": 3, "windowMs": 300000 },
  "routing": { "confidenceThreshold": 0.6 }
}json

Manage settings from the CLI:

# Read a value
aether config get execution.maxDepth

# Update a value
aether config set execution.maxDepth 5bash

Creating Your First Agent

Create a file at agents/workers/my-agent.agent.md:

Then run aether init to discover it, or restart the runtime. Your agent will appear in the registry and participate in task routing.

Provider Setup

What's Next?