Aether

Building tools that break assumptions.

A personal, cross-platform terminal AI coding agent. Chat with LLMs, call tools, and write code straight from your terminal — with a free, no-key default provider.

Built by Aetherdz. Website: aetherdz.github.io/aether-site.

Features

• Works instantly, zero setup - ships with the free OpenCode Zen provider (OpenAI-compatible, no API key required). Run aether and start chatting.
• 19 providers - zen, openai, anthropic, google, deepseek, openrouter, ollama, groq, mistral, xai, cerebras, togetherai, fireworks, perplexity, moonshot, minimax, huggingface, lmstudio, github, plus any custom OpenAI-compatible endpoint.
• Cross-platform - Windows, macOS, and Linux, from the start. An interactive Ink-based TUI (OLED-styled) is the default; --no-tui falls back to a lightweight node:readline REPL for dumb terminals and pipes.
• Low RAM - lightweight streaming with ANSI colors and ASCII box-drawing; the classic --no-tui readline REPL keeps memory minimal on dumb terminals and pipes.
• Token-by-token streaming - with a subtle status indicator and a token usage summary at the end of each turn.
• Agent tools - read_file, write_file, list_dir, grep_files, run_bash (explicit confirmation required), and web_fetch.
• Swarm mode - decompose a task into parallel subagents and get a boxed summary per subtask (analysis-only by default; opt-in git worktrees).
• Session persistence - every conversation is saved as JSONL under ~/.config/aether/sessions/.
• OAuth device login - sign in with GitHub or Google the opencode way: a one-time code, your browser, zero API keys. aether login-device github / aether login-device google.
• Token-efficiency cache - the exact same prompt in the exact same conversation context hits the disk cache and costs 0 tokens, so your free-tier quota lasts far longer.
• Smart fallback - when the free provider is rate-limited, aether transparently falls back to local ollama, then any provider you have a key for. No dead stops.
• No emojis, ever - a hard brand requirement. Plain ASCII and Unicode box-drawing only.

Install

Requires Node.js 18+.

npm install -g aethercode-cli

If the global npm install fails (EACCES, read-only prefix), use the fallback one-liner:

curl -fsSL https://raw.githubusercontent.com/Aetherdz/aethercode/main/install.sh | bash

Or run from source:

git clone https://github.com/Aetherdz/aethercode.git
cd aethercode
npm install
npm run build
npm install -g .   # makes the `aether` command available globally
aether --help

The package is published on the npm registry as aethercode-cli — aether upgrade will keep you on the latest version. The marketing website lives in a separate repository: Aetherdz/aether-site.

Free tier - how aether stretches it

The default zen provider is free but rate-limited (it can take hours to recover after heavy use). Aether stretches the free quota in three honest ways - no account rotation, no ToS games:

1. Disk cache - the exact same prompt in the exact same conversation context is answered from ~/.config/aether/cache/ at 0 tokens. The key includes the full conversation history, so a repeated question in a changed context is never served a stale answer. Content-addressed, TTL 7 days, capped at 500 entries / 64 MB. aether cache stats, aether cache clear.
2. Smart fallback chain - on a rate-limit error aether automatically tries, in order: local ollama (free, unlimited, on your machine), Gemini free tier, then any provider you have a key for. You see a yellow notice for each hop. aether never just dies.
3. Transparent status - aether status shows cache size; aether cost tracks usage. You always know where you stand.

Run a local model for effectively unlimited free use:

# install ollama once, then point aether at it
ollama pull llama3.2
aether use ollama

Security

• API keys never leave your machine. Keys come from environment variables or the aether login command, which writes them to ~/.config/aether/.env with 0600 permissions. The website only generates terminal commands - it never sees, stores, or transmits your keys.
• No hardcoded secrets - nothing is committed to the repo.
• run_bash always requires explicit y/n confirmation; non-interactive contexts deny by default.
• write_file refuses paths outside the working directory.
• Swarm analysis mode performs no file writes by default.

Quickstart

The interactive REPL works immediately with the free zen provider and no API key:

aether

┌──────────────────────────────────────────────────────────────────────────┐
│ Aether  v0.1.0                                       terminal coding agent │
│ zen/deepseek-v4-flash-free                cwd /path/to/your/project       │
└──────────────────────────────────────────────────────────────────────────┘

aether > explain tail recursion

One-shot questions:

aether ask "what is the difference between let and const in JavaScript?"

Switch providers/models:

aether use zen/claude-sonnet-5
aether use openrouter

Commands

| Command | Description | | --- | --- | | aether | Interactive REPL chat with streaming, tools, and persisted history. | | aether ask "<question>" | One-shot non-interactive streamed answer. | | aether use <provider>[/<model>] | Set the default provider and model in config. | | aether models [provider] | List models. zen fetches the live list from https://opencode.ai/zen/v1/models. | | aether providers | List all providers with key status and the default marker. | | aether swarm "<task>" | Orchestrate parallel subagents for a task. | | aether doctor | Run environment diagnostics (config, keys, sessions). | | aether status | Show current configuration summary. | | aether cost | Show approximate usage totals from saved sessions. | | aether keys | Show which API keys are configured and where. | | aether connect | Interactive provider setup (opencode /connect style): pick a provider, paste a key, or start a device login — no manual config editing. | | aether login <provider> | Save an API key for a provider (stored in ~/.config/aether/.env, 0600). | | aether logout <provider> | Remove the saved API key for a provider. | | aether login-device github \| google | OAuth device-flow sign-in (opencode pattern): one-time code, no API key. | | aether login-device list | Show which device accounts are signed in. | | aether logout-device <provider> | Remove a device-flow sign-in. | | aether cache stats \| clear | Inspect or clear the token-efficiency cache. | | aether config [path\|get <k> \| set <k> <v> \| providers] | View or edit the config file. | | aether alias [set\|list\|remove] | Manage command aliases. | | aether completions <bash\|zsh\|fish> | Print shell completion script. | | aether sessions list \| show <id> \| delete <id> | Manage saved sessions. | | aether --version / aether --help | Version and help. |

REPL commands

| Command | Description | | --- | --- | | /quit, /exit | Leave the session. | | /clear | Clear the screen. | | /reset | Forget conversation history. | | /use <provider>[/<model>] | Switch provider/model mid-session. | | /help | Show in-session help. |

Providers

Keys are read from environment variables only. The zen provider needs no key and is the default, so the tool works with zero setup.

| id | name | env var | key | pricing | | --- | --- | --- | --- | --- | | zen | OpenCode Zen | - | none needed | free | | openai | OpenAI | OPENAI_API_KEY | required | paid | | anthropic | Anthropic | ANTHROPIC_API_KEY | required | paid | | google | Google Gemini | GOOGLE_GENERATIVE_AI_API_KEY | required | free/paid | | deepseek | DeepSeek | DEEPSEEK_API_KEY | required | paid | | openrouter | OpenRouter | OPENROUTER_API_KEY | required | free/paid | | groq | Groq | GROQ_API_KEY | required | free/paid | | mistral | Mistral | MISTRAL_API_KEY | required | paid | | xai | xAI (Grok) | XAI_API_KEY | required | paid | | cerebras | Cerebras | CEREBRAS_API_KEY | required | paid | | togetherai | Together AI | TOGETHER_API_KEY | required | paid | | fireworks | Fireworks AI | FIREWORKS_API_KEY | required | paid | | perplexity | Perplexity | PERPLEXITY_API_KEY | required | paid | | moonshot | Moonshot AI (Kimi) | MOONSHOT_API_KEY | required | paid | | minimax | MiniMax | MINIMAX_API_KEY | required | paid | | huggingface | Hugging Face | HF_TOKEN | required | free/paid | | lmstudio | LM Studio (local) | - | local server | free | | github | GitHub Models | GITHUB_TOKEN | required | free/paid | | ollama | Ollama (local) | - | local server | free | | custom | any OpenAI-compatible endpoint | user-defined | optional | paid |

Set keys in your shell profile (or a .env file loaded by dotenv). See .env.example — or run aether connect to set them interactively.

If a provider requires a key that is not set, aether automatically falls back to the free zen provider with a notice.

Device login (OAuth)

GitHub and Google also work with no API key at all, using the OAuth 2.0 Device Authorization Grant (the opencode pattern): run aether connect, pick the device option, open the printed URL in any browser, enter the one-time code, and approve. The terminal polls automatically and stores the token in ~/.config/aether/device-tokens.json (0600). aether login-device github | google does the same non-interactively.

Custom providers

Add an OpenAI-compatible endpoint in ~/.config/aether/config.json:

{
  "defaultProvider": "zen",
  "defaultModel": "deepseek-v4-flash-free",
  "providers": {
    "custom": [
      {
        "name": "myendpoint",
        "baseURL": "https://my-gateway.example.com/v1",
        "apiKeyEnv": "MY_ENDPOINT_KEY",
        "models": ["model-a", "model-b"]
      }
    ]
  }
}

Swarm mode

aether swarm decomposes a task into 2-4 focused subtasks, runs them as parallel in-process subagents on the same provider/model (up to 4 concurrent), and prints a clean boxed summary per subtask.

aether swarm "design a REST API for a todo app: endpoints, auth, and data model"

aether swarm decomposing task...
planned 3 subtasks on zen/deepseek-v4-flash-free
[swarm] running 1/3: Define endpoints
[swarm] running 2/3: Design auth flow
[swarm] running 3/3: Model the data

swarm results
┌────────────────────────── subtask 1 Define endpoints ──────────────────────────┐
│  REST API for a todo app:  ...                                                 │
└────────────────────────────────────────────────────────────────────────────────┘

The default swarm path is analysis/summary only - it writes no files. The opt-in --worktree flag wires git-worktree isolation (git worktree add under the system temp dir, confirmation required, must be inside a git repository) for subagents that need isolated file operations. This is v1-experimental.

Sessions

Every REPL conversation is appended, message by message, to ~/.config/aether/sessions/<ISO-timestamp>.jsonl.

aether sessions list
aether sessions show 2026-08-07T06-11-57-107Z
aether sessions delete 2026-08-07T06-11-57-107Z

Configuration

• Config file: ~/.config/aether/config.json (override the directory with AETHER_CONFIG_DIR).
• Created automatically on first run with defaultProvider: zen and defaultModel: deepseek-v4-flash-free.
• Missing or corrupt config is recreated gracefully.

Security notes

• API keys are never hardcoded and never committed. Keys come from environment variables only.
• run_bash always requires an explicit y/n confirmation; non-interactive contexts deny by default.
• write_file refuses paths outside the working directory.
• Tool output and file access are scoped to the current working directory.
• Swarm analysis mode performs no file writes by default.

Development

npm run build      # tsc -> dist/
npm run typecheck  # tsc --noEmit
npm run dev        # run from source via tsx

License

MIT - Copyright (c) 2026 Aether-DZ. See LICENSE.