madOS

AI-Orchestrated Arch Linux System

madOS is a custom Arch Linux distribution optimized for low-RAM systems (1.9GB), featuring integrated OpenCode AI assistance for intelligent system management and orchestration. Includes open source drivers for Intel, AMD, and NVIDIA GPUs.

Overview

OpenCode Integration - AI-powered system orchestration and assistance
Low-RAM Optimized - Designed for 1.9GB+ RAM systems with any x86_64 processor
Lightweight Desktop - Sway Wayland compositor (~67MB RAM footprint)
Developer Ready - Node.js, npm, Git, VS Code pre-installed
Performance Tuned - ZRAM compression, EarlyOOM, kernel optimizations
Dual Installers - GTK graphical and TUI text-based installers
Multi-GPU Support - Open source drivers for Intel, AMD, and NVIDIA

Hardware Requirements

Component	Minimum	Recommended
CPU	Intel Atom or equivalent	Any x86_64
RAM	1.9GB	2GB+
Storage	32GB	64GB+
GPU	Intel/AMD/NVIDIA (open drivers)	Any x86_64 compatible
Boot	UEFI or BIOS	UEFI

Features

Desktop Environment

Sway - i3-compatible Wayland compositor with Nord theme
Waybar - Customizable status bar
Wofi - Application launcher
Foot - Fast terminal emulator
Mako - Notification daemon

Applications

Chromium - Web browser
VS Code - Code editor
PCManFM - File manager
LXAppearance - Theme configuration

madOS Native Apps

madOS Equalizer (mados-equalizer) - 8-band audio equalizer with PipeWire/PulseAudio
madOS PDF Viewer (mados-pdf-viewer) - PDF viewer with annotations and digital signatures
madOS Photo Viewer (mados-photo-viewer) - Photo viewer/editor with video playback
madOS WiFi - Native tray applet via nm-applet (NetworkManager)
madOS Bluetooth - Native tray applet via blueman-applet

Audio Quality

Auto-Detection - Automatically detects and applies maximum audio quality (up to 192kHz/32-bit)
High-Quality Resampling - PipeWire configured with quality level 10 (maximum)
Hardware Optimization - Optimal buffer sizes and sample rates for your audio hardware
See Audio Quality Documentation for details

Developer Tools

OpenCode - AI assistant (opencode command)
Node.js 24.x & npm
Git - Version control
fastfetch - System information tool
htop - System monitor
Vim & Nano - Text editors

📊 fastfetch example output

   /\      mados@mados
  /  \     -----------
 /\   \    OS → madOS (Arch Linux)
/  ..  \   Host → Intel NUC / Custom PC
/  '  '\  Kernel → 6.12.8-arch1-1
/ ..'   \  Uptime → 2 hours, 15 mins
/..'  ..'\ Packages → 324 (pacman)
 `..'..'`  Shell → zsh 5.9
            WM → sway
            Terminal → foot
            CPU → Intel Atom x5-Z8350 (4) @ 1.92GHz
            GPU → Intel HD Graphics 400
            Memory → 487MiB / 1872MiB
            Swap → 128MiB / 936MiB
            Disk (/) → 8.2GiB / 32.0GiB (26%)
            Local IP (wlan0) → 192.168.1.42/24

            🟦🟦🟦🟦🟦🟦🟦🟦

Note: fastfetch reads /etc/os-release to display madOS (Arch Linux) as the distro name. The output above is an example — actual values depend on your hardware.

System Optimizations

ZRAM - Compressed swap using 50% RAM with zstd
EarlyOOM - Out-of-memory killer to prevent freezes
Kernel tuning - vm.swappiness=5, vm.vfs_cache_pressure=200
Network stack - Optimized TCP buffers for low memory

GPU Drivers (Open Source)

Intel - intel-media-driver, vulkan-intel, libva-intel-driver
AMD - xf86-video-amdgpu, vulkan-radeon
NVIDIA - xf86-video-nouveau (open source driver)
Mesa - OpenGL/Vulkan implementation for all GPUs

Adaptive Rendering

madOS automatically detects hardware capabilities and optimizes rendering:

Modern hardware - Hardware-accelerated OpenGL/Vulkan rendering
Legacy hardware - Software rendering (pixman) for:
- Old CPUs (Intel Atom, Celeron N, Pentium N, pre-Sandy Bridge)
- Legacy Intel GPUs (Gen 1-6, GMA series, Atom integrated graphics)
- Systems with <2GB RAM
- Virtual machines
- Safe graphics mode (nomodeset kernel parameter)

The system automatically switches to software rendering when legacy hardware is detected, ensuring compatibility and stability on older systems while maximizing performance on modern hardware.

Quick Start

Installation

Create bootable USB:

sudo dd if=madOS-*.iso of=/dev/sdX bs=4M status=progress oflag=sync

Boot from USB - Sway will auto-start in the live environment
Run the installer:
```
sudo install-mados
```
The smart launcher automatically selects:
- GTK Installer - If running under Wayland/X11
- TUI Installer - Text-based fallback
Follow the installer (~10 minutes):
- Select installation disk
- Create user account
- Configure timezone and locale
- Review and confirm settings
Reboot into your new madOS system

Installer Options

Installer	Command	Description	Size
Smart (Auto)	`sudo install-mados`	Auto-detects best option	-
GTK	`sudo install-mados-gtk.py`	Graphical interface	+15MB
TUI	`sudo install-mados.sh`	Text-based, keyboard only	+200KB
CLI	`sudo install-arch-optimized.sh`	Legacy minimal installer	Base

Building the ISO

Requirements

Arch Linux or Arch-based system
archiso package
~10GB free disk space
Root access

Local Build

# Install archiso
sudo pacman -S archiso

# Build the ISO
sudo mkarchiso -v -w work/ -o out/ .

# Output location
ls -lh out/madOS-*.iso

Build time: ~10-20 minutes

GitHub Actions

ISO builds automatically on push to main:

Push to main branch
Monitor build in GitHub Actions tab (~15 minutes)
Download ISO from Artifacts

Customization

Add/Remove Packages

Edit packages.x86_64 (one package per line):

# Add package
echo "firefox" >> packages.x86_64

# Remove package
sed -i '/chromium/d' packages.x86_64

Desktop Configuration

Default user configurations:

Component	Location
Sway	`airootfs/etc/skel/.config/sway/config`
Waybar	`airootfs/etc/skel/.config/waybar/`
Terminal	`airootfs/etc/skel/.config/foot/foot.ini`

Modify Installer

Edit airootfs/usr/local/bin/install-mados.sh to customize:

Partition layout and sizes
Default packages
Installation flow

Using OpenCode

After installation, OpenCode is available globally:

# Start interactive session
opencode

# Send direct message
opencode --message "optimize system performance"

# Get help with commands
opencode --message "how to check disk usage?"

Capabilities

Code assistance - Write, debug, and review code
System management - Configure services, troubleshoot issues
Documentation - Explain commands and concepts
Automation - Create scripts and workflows
Problem solving - Intelligent system orchestration

System Architecture

madOS Architecture
├── Hardware (1.9GB RAM, Intel/AMD/NVIDIA GPU)
├── Kernel (Linux latest + ZRAM + sysctl tuning)
├── Services (systemd, EarlyOOM, iwd, PipeWire)
├── Display (Wayland via Sway)
├── Desktop (Sway, Waybar, Wofi, Nord theme)
├── Applications (Chromium, VS Code, dev tools)
└── AI Layer (OpenCode system orchestration)

Post-Installation

First Boot

System auto-logs into TTY1 and starts Sway
Waybar displays system status
Press Super+Enter to open terminal
Run opencode to start AI assistant

Key Bindings

Shortcut	Action
`Super+Enter`	Open terminal
`Super+D`	Application launcher
`Super+Shift+Q`	Close window
`Super+1-9`	Switch workspace
`Super+Shift+E`	Exit Sway

Package Management

# Install software
sudo pacman -S <package>

# Update system
sudo pacman -Syu

# Update OpenCode
npm update -g opencode-ai

Performance Monitoring

# Monitor RAM usage
htop
free -h

# Check ZRAM status
zramctl

# View system services
systemctl list-units --type=service

# Remove orphaned packages
sudo pacman -Rns $(pacman -Qtdq)

Troubleshooting

Installation

Issue	Solution
No disks detected	Check connections, run `lsblk`
Pacstrap fails	Verify internet connection
GRUB install error	Check UEFI/BIOS boot mode

Boot

Issue	Solution
Won't boot	Verify BIOS boot order
Kernel panic	Boot with `systemd.unit=rescue.target`
No display	Try different TTY (Ctrl+Alt+F2-F6), check GPU drivers
Black screen with NVIDIA	Nouveau may need `nomodeset` kernel parameter
AMD screen flicker	Update kernel or try `amdgpu.dc=0` parameter

Performance

Issue	Solution
High RAM usage	Check `htop`, disable unused services
Slow compositor	Consider i3 or dwm instead of Sway
ZRAM issues	`systemctl status systemd-zram-setup@zram0`
Graphical glitches	Force software rendering: `WLR_RENDERER=pixman sway`
Sway crashes on start	Check if legacy hardware detected: `/usr/local/bin/detect-legacy-hardware`
Poor performance on old GPU	Software rendering is auto-enabled, verify with `echo $WLR_RENDERER`

Resources

Website: https://madkoding.github.io/mad-os/
Documentation: /usr/share/doc/madOS/ (after install)
Arch Wiki: https://wiki.archlinux.org/
Issues: GitHub Issues

Contributing

Contributions are welcome. Areas for contribution:

Themes and visual improvements
Package optimization
System tuning
Documentation
Bug fixes

License

Custom configurations and scripts: MIT License
Based on Arch Linux and archiso

Credits

Core System

Project	Description	Repository
Arch Linux	Base distribution	archlinux.org
archiso	ISO building framework	gitlab.archlinux.org/archlinux/archiso
Linux Kernel	Operating system kernel	kernel.org

Desktop Environment

Project	Description	Repository
Hyprland	Dynamic tiling Wayland compositor	github.com/hyprwm/Hyprland
Sway	i3-compatible Wayland compositor	github.com/swaywm/sway
swww	Animated wallpaper daemon for Wayland	github.com/LGFae/swww
swaybg	Wallpaper tool for Wayland	github.com/swaywm/swaybg
Waybar	Highly customizable Wayland bar	github.com/Alexays/Waybar
Wofi	Application launcher for Wayland	hg.sr.ht/~scoopta/wofi
Mako	Lightweight Wayland notification daemon	github.com/emersion/mako
Foot	Fast, lightweight Wayland terminal	codeberg.org/dnkl/foot
greetd	Minimal and flexible login manager	git.sr.ht/~kennylevinsen/greetd
ReGreet	GTK-based greeter for greetd	github.com/rharber/ReGreet
Cage	Kiosk compositor for Wayland	github.com/cage-kiosk/cage

Themes & Appearance

Project	Description	Repository
Nordic GTK Theme	Dark GTK theme based on Nord palette	github.com/EliverLara/Nordic
Nordzy Icons	Nord-themed icon pack	github.com/MolassesLover/Nordzy-icon
Nord Color Scheme	Arctic, north-bluish color palette	nordtheme.com
JetBrains Mono Nerd Font	Developer font with icon glyphs	github.com/ryanoasis/nerd-fonts
Noto Emoji	Color emoji font by Google	github.com/googlefonts/noto-emoji

Applications

Project	Description	Repository
Chromium	Open-source web browser	chromium.org
VS Code	Code editor	github.com/microsoft/vscode
mpv	Versatile media player	github.com/mpv-player/mpv
PCManFM	Lightweight file manager	github.com/lxde/pcmanfm
pavucontrol	PulseAudio volume control	freedesktop.org/software/pulseaudio/pavucontrol

AI & Development Tools

Project	Description	Repository
OpenCode	AI coding assistant	opencode.ai
Ollama	Local LLM runner	github.com/ollama/ollama
Node.js	JavaScript runtime	nodejs.org
Git	Version control system	git-scm.com
Oh My Zsh	Zsh configuration framework	github.com/ohmyzsh/ohmyzsh

Audio & Multimedia

Project	Description	Repository
PipeWire	Multimedia processing engine	github.com/PipeWire/pipewire
WirePlumber	PipeWire session manager	github.com/PipeWire/wireplumber
GStreamer	Multimedia framework	gstreamer.freedesktop.org
CAVA	Console-based audio visualizer	github.com/karlstav/cava
chafa	Terminal image/graphics viewer	github.com/hpjansson/chafa

System Utilities

Project	Description	Repository
EarlyOOM	Early OOM daemon	github.com/rfjakob/earlyoom
systemd-zram-generator	ZRAM swap configuration	github.com/systemd/zram-generator
NetworkManager	Network management daemon	networkmanager.dev
Plymouth	Boot splash screen	gitlab.freedesktop.org/plymouth/plymouth
fastfetch	System information tool	github.com/fastfetch-cli/fastfetch
Blueman	Bluetooth manager	github.com/blueman-project/blueman

GTK/Python Stack

Project	Description	Repository
GTK 3	GUI toolkit	gtk.org
PyGObject	Python bindings for GObject	pygobject.gnome.org
Poppler	PDF rendering library	poppler.freedesktop.org
Pillow	Python imaging library	github.com/python-pillow/Pillow
gtk-layer-shell	Wayland layer shell for GTK	github.com/wmww/gtk-layer-shell

Media Content

Content	Author	Links
Touching The Sky (music)	LukHash	lukhash.com · Bandcamp

Built for the Arch Linux community

Última actualización: 2026-02-24 13:24:17 -03

Name		Name	Last commit message	Last commit date
Latest commit History 903 Commits
.github		.github
airootfs		airootfs
docs		docs
efiboot/loader		efiboot/loader
grub		grub
syslinux		syslinux
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
packages.x86_64		packages.x86_64
pacman.conf		pacman.conf
profiledef.sh		profiledef.sh
sonar-project.properties		sonar-project.properties

License

madkoding/mad-os

Folders and files

Latest commit

History

Repository files navigation

madOS

Overview

Hardware Requirements

Features

Desktop Environment

Applications

madOS Native Apps

Audio Quality

Developer Tools

System Optimizations

GPU Drivers (Open Source)

Adaptive Rendering

Quick Start

Installation

Installer Options

Building the ISO

Requirements

Local Build

GitHub Actions

Customization

Add/Remove Packages

Desktop Configuration

Modify Installer

Using OpenCode

Capabilities

System Architecture

Post-Installation

First Boot

Key Bindings

Package Management

Performance Monitoring

Troubleshooting

Installation

Boot

Performance

Resources

Contributing

License

Credits

Core System

Desktop Environment

Themes & Appearance

Applications

AI & Development Tools

Audio & Multimedia

System Utilities

GTK/Python Stack

Media Content

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Contributors 5

Uh oh!

Languages

Packages