aethr 0.1.1

A lightweight CLI for explicit, reproducible AI coding workflows.

Aethr

A tiny CLI for running explicit AI coding workflows from YAML.

Core Idea

Coding with LLMs is not one-shot generation.

Real development is:

plan -> implement -> review -> iterate

Aethr makes those workflows programmable. A run is just:

task + workflow + explicit context + model routing

Aethr is stateless. The only project file it creates is .aethr.yaml.

Install

pip install aethr

For local development:

pip install -e ".[dev]"

Quickstart

aethr init review-existing-diff
aethr run "review my current changes before I commit"

Aethr copies a YAML preset into .aethr.yaml. Edit it like any other project file.

How Aethr Works

• Task: the instruction passed on the command line.
• Workflow: the YAML file that defines ordered steps.
• Steps: sequential units of work. Aethr runs them in order.
• Roles: named responsibilities such as planner, reviewer, or writer.
• Context: explicit repo input declared per step.
• Model routing: each role can point at a different LiteLLM model.

Each step receives the task, prior step outputs, and its declared context. The step result stays in memory, streams to the terminal as it is generated, and is printed in a Rich panel when complete.

Example Workflow Config

workflow: review-existing-diff

roles:
  reviewer: Review the provided task context as if it were an existing diff.

models:
  reviewer: openai:gpt-5.5

steps:
  - id: review
    role: reviewer
    context:
      - git_diff

Built-In Workflows

• plan-implement-review: plan a task, propose an implementation, review it.
• review-existing-diff: review the current working tree diff.
• debug-failing-test: diagnose a failing test, propose a fix, review it.
• add-tests: plan, draft, and review focused test coverage.
• docs-sync: update docs from the current diff and README context.
• custom: a minimal one-step workflow to edit freely.

List presets:

aethr init --list

Initialize another preset:

aethr init docs-sync --force

Examples

The examples/ directory contains small workflow files you can copy from:

• examples/review-existing-diff.yaml
• examples/add-tests.yaml
• examples/docs-sync.yaml

Explicit Context

Aethr uses explicit context instead of automatic retrieval. That keeps runs easy to understand: the YAML shows exactly what each step can see.

Supported context sources:

• git_diff: runs git diff --no-ext-diff.
• file:<path>: reads one UTF-8 file relative to the project root.
• glob:<pattern>: reads matching UTF-8 files relative to the project root, with a small content cap.

Example:

steps:
  - id: review-docs
    role: reviewer
    context:
      - git_diff
      - file:README.md
      - glob:docs/**/*.md

Missing files, empty diffs, non-git directories, and unreadable files appear as clear placeholder notes in the prompt.

Prompt Previewing

Use --show-prompt to see exactly what Aethr would send to each model:

aethr run "review my current changes before I commit" --show-prompt

Aethr does not call models in prompt preview mode. For later steps, it uses a clear placeholder where real previous step output would appear.

Mock Mode

Aethr works without API keys by returning deterministic mock responses.

Aethr also loads a project-level .env automatically before model calls, so credentials can live alongside the workflow file without extra flags.

Use the models configured in .aethr.yaml:

AETHR_LIVE=1 aethr run "review my current changes"

Override every configured model with one LiteLLM model:

AETHR_MODEL=openai:gpt-5.5 aethr run "review my current changes"

Philosophy

Aethr should feel like:

• git
• pytest
• rg
• cargo

It should not feel like:

• an agent framework
• an autonomous coding platform
• an AI operating system

Aethr intentionally avoids persistence, replay systems, caches, plugins, DAGs, async runtimes, vector search, automatic retrieval, memory systems, and agent abstractions.

If a workflow fails, Aethr prints a copyable JSON checkpoint for the completed steps. Pass that back with --resume-checkpoint to continue from the next step without rerunning the earlier ones.

Future Work

One likely future UX is workflow promotion: take a one-off run that worked and turn it into an editable .aethr.yaml workflow. The idea is to help users go from ad hoc sessions to repeatable workflows without introducing session storage, replay systems, or hidden history.

Architecture

aethr/
  cli.py
  config.py
  context.py
  executor.py
  llm.py
  prompts.py
  workflow.py