LOKI Chaos

Autonomous AI Testing & Synthetic Chaos Agent

📘 Full Documentation • Installation • CLI Reference • Releases

⚡ Overview

LOKI Chaos (loki / loki-chaos) is a standalone CLI testing agent that breaks, explores, and verifies web applications before your users do. Instead of only testing "happy paths", LOKI unleashes synthetic chaos personas, in-flight API mutations, client state corruption, and multi-tab race probes—then packages every failure into a deterministic Playwright reproduction script (repro_test.py), video replay, sanitized .har trace, and standalone HTML report.

🌟 Highlights

• 🐝 Chaos Personas & Swarm Mode (--swarm): RageClicker, NoviceChaotic, NetworkTormentor, and Adversary across Chromium, Firefox, WebKit, and mobile viewports (--device).
• ⚡ Ghost in the Wire (--api-chaos): In-flight HTTP 500/502/503/429 injection, JSON schema stripping, and 401 auth token invalidation.
• 🧪 Poisoned Well (--state-chaos): localStorage / sessionStorage JSON rot, QuotaExceededError simulation, temporal clock drift (Date.now), and poisoned reload survival checks.
• 🔀 Concurrency & Infra Chaos: Synchronized multi-tab race condition probes (--concurrency) and local process/container fault injection (loki infra).
• 🧠 AI Rules & Autonomous Self-Healing: Evaluates plain-English business rules (.loki/rules.md) via any LiteLLM provider (Gemini, OpenAI, Anthropic, Ollama, etc.) and synthesizes verified surgical patches (loki fix --apply, --auto-heal).
• 💬 Interactive QA Terminal (loki / loki chat): Built-in REPL to inspect runs, switch AI models (/model), and dispatch /run, /fix, and /report.

🚀 Quickstart

1. Install

• Precompiled Binaries & Windows Installer (no Python required): Download loki-setup-windows-amd64.exe or standalone binaries for Windows, Linux, and macOS from GitHub Releases.
• Via uv (recommended for Python users):

  uv tool install loki-chaos-agent
  # Or run without installing:
  uvx --from loki-chaos-agent loki run http://localhost:8000 --swarm
  

• Via pipx:

  pipx install loki-chaos-agent
  

2. Run

# 1. Initialize workspace (.loki/config.yaml & .loki/rules.md)
loki init

# 2. Launch a multi-persona chaos assault and open the HTML dashboard
loki run http://localhost:8000 --swarm --open

# 3. Replay the failure deterministically or synthesize a verified code fix
loki replay
loki fix --apply

# 4. Open the interactive QA terminal assistant
loki

📘 Documentation

Full guides, configuration references, and examples live at loki-agent.pages.dev (available in English & Spanish):

• Getting Started & Installation — Binaries, uv, AI provider setup (.loki/config.yaml), and first run.
• Core Concepts — Chaos personas, Swarm mode, journey recording (loki record), and mobile emulation.
• CLI Reference — Complete flag reference for run, fix, replay, report, chat, infra, and auth.
• AI Brain & Self-Healing — LiteLLM providers, rules.md assertions, and closed-loop code healing.
• Advanced Chaos — API chaos (Ghost in the Wire), state chaos (Poisoned Well), concurrency lanes, and infrastructure faults.
• Security & CI/CD — Authorization gate, HAR token scrubbing, and GitHub Actions quality gates (--ci).

🛡️ Security & Authorization Guardrail

Targeting localhost works out of the box. Against any remote host, LOKI blocks until you explicitly confirm ownership or written authorization (stored locally in .loki/authorized_targets.json, managed via loki auth). All captured network traces and recorded journeys automatically scrub credentials, cookies, and tokens. See SECURITY.md for details.

🤝 Contributing

Contributions and Pull Requests are welcome! You do not need an open issue to submit a PR.

• Read CONTRIBUTING.md for development setup and testing (pytest, ruff).
• Check AGENTS.md if working with AI coding agents.
• Browse open good first issue tasks.

📄 License

Licensed under the MIT License.