⚙️ Axium¶

Axium: structure for your terminal.

Axium is a context-aware DevOps assistant built to make your shell environments cohesive and intelligent. It provides a lightweight daemon, intuitive CLI, dynamic HUD, and extensible plugin system ("Spokes") — all designed for engineers who live in tmux and terminals.

🧭 Features¶

Component	Description
Daemon (axiumd)	Async background process maintaining session state, env context, and plugin registry
CLI (axium)	Typer-based command interface with structured sub-commands and fast completions
HUD	Prints a one-line status segment ideal for tmux/shell prompts
Palette	Curses-based quick launcher; triggers common commands or plugin actions interactively
Spokes	Lightweight plugin system for commands and event handlers
Gears	Privileged automation extensions with tmux integration and enhanced permissions

🧱 Architecture Overview¶

Shell → CLI → Daemon → State

Each layer communicates via JSON over a UNIX socket:

Shell (bash/zsh/tmux)
    ↓
Axium CLI (Typer)
    ↓
Axium Daemon (asyncio)
    ↓
State / Config / Spokes

🧩 Directory Structure¶

axium/core/
    cli.py        → Typer CLI entrypoint
    daemon.py     → Async background service
    ipc.py        → JSON IPC utilities
    hud.py        → Status line generator
    palette.py    → Interactive TUI launcher
    spokes.py     → Spoke discovery/loader
bash/init.sh      → Shell alias + integration
tests/            → Pytest suite

🪩 Design Principles¶

Async-first — everything that can await, does
Minimal dependencies — stdlib + Typer + YAML
Predictable UX — axium <noun> <verb> pattern
Invisible until needed — helps, never interrupts
Composable — Daemon, HUD, and Spokes work independently

Quick Links¶

Getting Started - Installation and quickstart
Core Concepts - Understanding Axium's architecture
Writing Spokes - Lightweight plugin development
Writing Gears - Privileged automation extensions
Contributing - Join the development

"Structure for your terminal."