Aetheris

A terminal AI assistant that works on your machine: it reads and writes files, runs commands and answers their prompts, searches the web, and can undo what it did. It is built for small local models first (Ollama), and talks to Anthropic, OpenAI, Gemini and Attacca with the same tools and the same approval prompts.

 you ──► prompt box / aetheris -p ──► model (Ollama · Anthropic · OpenAI · Gemini)
                                          │ tool call (native, or <tool_call> text + JSON repair)
                                          ▼
              permissions ─► approval ─► tool ─► git commit per edit ─► auto-verify
                                          │                                 │
                                          └──────── result back to the model ◄┘

Quickstart

# 1. Install
pip install aetheris
# 2. Pull a local model
ollama pull gemma4:e4b
# 3. Start it in the directory you want it to work in
aetheris

Inside, these six cover most sessions - /help shows them, /help all shows the rest:

Important: it runs commands and edits files as you, asking first unless you allow it.

Installation / Usage

Option A - from PyPI

pip install aetheris                 # the `aetheris` command
pip install "aetheris[ast]"          # + Tree-sitter, for get_code_skeleton / query_ast_node
pip install "aetheris[attacca]"      # + the packages /connect attacca needs
pip install "aetheris[keyring]"      # + keep API keys in the OS keyring

Option B - from a checkout

# 1. Clone the project
git clone https://github.com/minjun1177/aetheris && cd aetheris
# 2. Install it editable, so a change takes effect without reinstalling
pip install -e .
pip install -r requirements.txt   # ...or only the dependencies; then run: python -m aetheris

Carrying on, and running without the prompt box

aetheris -c                                    # the newest session worked on in this directory
aetheris --resume <id or title>                # a particular one
aetheris -p "summarise CHANGELOG.md"           # one answer on stdout, then exit
git diff | aetheris -p "review this" --json    # piped input + JSON: text, tool calls, tokens
aetheris -p "fix the test" --auto-allow        # tools run without asking: scripts and CI

Using the parts

It is also a typed library: aetheris.MCPServer (MCP without an SDK) and aetheris.start_shell (a command you can answer while it runs). Only aetheris.__all__ is promised - docs/library.md.

Documentation

Configuration / Environment Variables

/set changes a setting and saves it to ~/.aetheris/settings.json; all of them: docs/configuration.md.

Project Structure

aetheris/
├── aetheris/            # the package: app.py, llm_client.py, tools.py, toolspec.py, ...
├── bench/               # run.py - measure a model on the documented tasks
├── docs/                # the user documentation
├── skills/              # bundled SKILL.md packs
├── tests/               # one script per area; each prints [ok]/[FAIL]
├── ARCHITECTURE.md      # for changing the code: how it fits, what not to break
├── CHANGELOG.md         # what changed, and why
└── pyproject.toml

Compatibility / License