best-practice-search

• One runtime, three entrypoints (CLI/TUI, server, dashboard) backed by the same DI container.
• OpenAI chat + Responses API, Anthropic Claude API, and OpenAI-compatible gateways (OpenRouter/DeepSeek/Antigravity).
• llm_provider: auto (or cli) picks the best available subscription from CLI auth + env keys (Codex/Antigravity/Claude/OpenAI).
• Typed, artifact-aware events render identically in terminals and the web UI.
• Built-in observability: structured logs, OpenTelemetry traces, Prometheus metrics, and per-session cost accounting.
• Retrieval layers for memory, skills, docs, and external context plus approvals for risky actions.
• Evaluation harnesses (including SWE-Bench) live in-repo for parity between manual and automated runs.

---

```

Delivery (CLI, Server, Web) → Agent Application Layer → Domain Ports → Infrastructure Adapters

```

• Delivery: shared DI wiring for cmd/alex, cmd/alex-server, and web/ keeps sessions consistent.
• Agent core: internal/agent/{app,domain,ports} implements the Think → Act → Observe loop, approvals, and typed events.
• Infrastructure: internal/di, internal/tools, internal/toolregistry, internal/llm, internal/mcp, internal/session, internal/storage, internal/observability, and internal/context provide adapters, context, telemetry, and persistence.
• Frontend: web/ streams SSE events, artifacts, approvals, and cost details in real time.

---

Prerequisites: Go 1.24+, Node.js 20+ (web UI), Docker (optional).

Quickstart

```bash

# Configure your LLM provider (examples)

export OPENAI_API_KEY="sk-..."

# export ANTHROPIC_API_KEY="sk-ant-..." # Claude

# export CLAUDE_CODE_OAUTH_TOKEN="..." # Claude Code OAuth

# export CODEX_API_KEY="sk-..." # OpenAI Responses / Codex

# export ANTIGRAVITY_API_KEY="..." # Antigravity (OpenAI-compatible)

cp examples/config/runtime-config.yaml ~/.alex/config.yaml

# Run backend + web together

./dev.sh

# Optional: build and run the CLI/TUI

make build

./alex

./alex "print the repo layout"

```

Configuration is shared across every surface. Use examples/config/runtime-config.yaml and docs/reference/CONFIG.md for the canonical schema.

Helpful dev.sh commands

```bash

# Check status/logs

./dev.sh status

./dev.sh logs server

./dev.sh logs web

# Stop services

./dev.sh down

```

---


```bash

# With services running from the quickstart

./alex "Map the runtime layers, explain the event stream, and produce a short summary."

```

Expected:

• CLI shows a typed event stream (plan/tool/output).
• Web UI at http://localhost:3000 renders the same events and artifacts.
• Cost + trace metadata update as the run progresses.

---

• Quality gates (Go + web): ./dev.sh lint, ./dev.sh test, and npm --prefix web run e2e.
• Evaluation harnesses + reproducible results: evaluation/ and evaluation_results/.
• Observability stac