Overlay testing session management for bazzite-ai development. Enables live editing of justfiles via symlinks to /usr on immutable OS (OSTree) or traditional Linux systems. Use when users need to test ujust changes, enable overlay mode, troubleshoot testing sessions, or run VM/install tests.
/plugin marketplace add atrawog/bazzite-ai-plugins/plugin install atrawog-bazzite-ai-dev-bazzite-ai-dev@atrawog/bazzite-ai-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/overlay-architecture.mdscripts/check-overlay-status.shThe test command manages overlay testing sessions for bazzite-ai development. It creates symlinks from the repository to /usr/share/bazzite-ai/just/, allowing live editing of justfiles without rebuilding the OS image.
Key Concept: On immutable OSTree systems (Bazzite-AI, Silverblue), /usr is read-only. Overlay mode temporarily unlocks it. On traditional systems (Fedora, CentOS), symlinks provide the same live-editing capability.
| Action | Command | Description |
|---|---|---|
| Enable overlay | ujust test overlay enable | Bootstrap overlay testing session |
| Check status | ujust test overlay check | Show current overlay/symlink status |
| Refresh | ujust test overlay refresh | Regenerate 60-custom.just after changes |
| VM testing | ujust test vm | VM testing submenu |
| Install testing | ujust test install | Test install commands |
| Install all | ujust test install all | Test all install commands |
| System info | ujust test info | Show detailed system info |
| Help | ujust test help | Show usage help |
ujust test ACTION="" SUBACTION="" ARGS...
| Parameter | Values | Description |
|---|---|---|
ACTION | overlay, vm, install, info, help | Primary action |
SUBACTION | enable, check, refresh (for overlay) | Subaction |
ARGS | varies | Additional arguments for vm/install |
When ACTION is provided, the command runs non-interactively. Without it, an interactive menu appears.
ujust test overlay enable
/usr/share/bazzite-ai/just/60-custom.just import fileujust test overlay check
Shows current status:
Immutable OS: Whether overlay mode is active
Traditional OS: Whether symlinks are configured
Target repository path
ujust test overlay refresh
Use after:
Adding new .just files
Removing .just files
Modifying the generator script
Regenerates 60-custom.just without full restart.
ujust test vm # Interactive VM test menu
ujust test vm list # List available VM tests
ujust test vm <name> # Run specific VM test
Delegates to the VM testing harness for testing in virtual machines.
ujust test install # Interactive install test menu
ujust test install all # Test all install commands
ujust test install <name> # Test specific install command
Tests install commands for validation.
# 1. Clone repository
git clone <repo-url> && cd bazzite-ai
# 2. Enable overlay testing (one-time)
just test overlay enable
# 3. Make changes to justfiles
vim just/bazzite-ai/my-feature.just
# 4. Test immediately with ujust
ujust my-feature
# 5. If adding new files, refresh
just test overlay refresh
# Overlay resets on reboot - re-enable
just test overlay enable
# Your git commits persist, overlay changes don't
# 1. Create/edit the justfile
vim just/bazzite-ai/new-command.just
# 2. Refresh to pick up new file
just test overlay refresh
# 3. Test the command
ujust new-command
| OS Type | Detection | Overlay Method |
|---|---|---|
| Immutable (OSTree) | /run/ostree-booted exists | rpm-ostree overlay |
| Traditional | No OSTree marker | Symlinks only |
Symptom: ujust test overlay check shows "Normal immutable mode"
Cause: Overlay activation failed or needs reboot
Fix:
# Check if rpm-ostree unlock succeeded
sudo rpm-ostree status | grep -i unlock
# If not, try manual unlock
sudo rpm-ostree usroverlay
Symptom: Changes to justfiles not reflected in ujust output
Cause: Symlinks not properly created or 60-custom.just not regenerated
Fix:
# Check symlink status
ls -la /usr/share/bazzite-ai/just/
# Re-enable overlay
just test overlay enable
# Refresh imports
just test overlay refresh
Symptom: New recipe not available in ujust --list
Cause: 60-custom.just needs regeneration
Fix:
just test overlay refresh
Symptom: sudo: a terminal is required
Cause: Running in non-interactive mode without passwordless sudo
Fix:
# Enable passwordless sudo first
ujust configure passwordless-sudo enable
# Then retry
just test overlay enable
Related Skills: install (for testing install commands), vm (for VM testing)
Configuration: ujust configure passwordless-sudo enable for sudo access
Documentation: Overlay Testing Architecture
Use when the user asks about:
"enable overlay", "start testing session", "development mode"
"test my changes", "live reload justfiles"
"overlay not working", "symlinks not configured"
"refresh overlay", "pick up new files"
"VM testing", "test in VM"
"test install commands"
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.