# Noctalia

> This skill should be used when the user asks to "configure noctalia", "change noctalia settings", "debug noctalia", "restart noctalia", or mentions noctalia shell, quickshell, or noctalia IPC. Provides common patterns for working with noctalia shell in this NixOS config. Use when this capability is needed.

- Skill: `tomevault-io/noctalia` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/noctalia`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/noctalia/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/noctalia

---


# Noctalia Shell Configuration

This skill provides common patterns for configuring and debugging the noctalia desktop shell.

## Configuration Location

```
home/desktop/shell/noctalia/default.nix
```

The nix config generates `~/.config/noctalia/settings.json` (symlinked to nix store).

## Key Concepts

### Settings Format
Noctalia settings are JSON. The nix home-module accepts freeform attributes that get serialized to JSON. Key gotcha: nested objects must match noctalia's expected structure exactly.

### Runtime State vs Config
- **settings.json** - What nix generates (read-only symlink)
- **Runtime state** - What noctalia is actually using (can differ if UI changes were made)
- Always verify runtime state via IPC after changes

## IPC Commands

Query and control noctalia via IPC:

```bash
# Get full runtime state
noctalia-shell ipc call state all

# List available IPC targets
noctalia-shell ipc show

# Common targets
noctalia-shell ipc call launcher toggle
noctalia-shell ipc call controlCenter toggle
noctalia-shell ipc call settings toggle
noctalia-shell ipc call wallpaper random
```

## Debugging & Verification

### Check runtime state
```bash
noctalia-shell ipc call state all | jq '.settings'
```

### Check generated config
```bash
cat ~/.config/noctalia/settings.json | jq .
```

### Restart noctalia (apply changes without logout)
```bash
systemctl --user restart noctalia-shell
```

### VM workflow (rebuild + restart + verify)
```bash
./scripts/dev-sync rebuild && \
sshpass -p 'test' ssh altan@192.168.122.3 \
  'systemctl --user restart noctalia-shell && sleep 2 && noctalia-shell ipc call state all' | jq '.settings'
```

## Common Issues

### Changes not applying
1. Verify settings.json has correct content: `cat ~/.config/noctalia/settings.json`
2. Restart noctalia: `systemctl --user restart noctalia-shell`
3. Check runtime state matches: `noctalia-shell ipc call state all | jq`

### Wrong JSON structure
Noctalia expects specific nested structures. Example for bar widgets:
- **Wrong:** `bar.widgetsLeft = [...]`
- **Correct:** `bar.widgets.left = [...]`

### Widgets not appearing
All widgets must be objects with `id` field:
- **Wrong:** `"Clock"`
- **Correct:** `{ id = "Clock"; }`

## Related Skills

- **noctalia-bar** - Bar widget layout and settings

## External Resources

- Docs: https://docs.noctalia.dev/
- IPC docs: https://docs.noctalia.dev/development/plugins/ipc/
- GitHub: https://github.com/noctalia-dev/noctalia-shell

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/altans) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->