zellij-layout-preservation

name	zellij-layout-preservation
description	Automatic Zellij session layout preservation with BSD immutable flag protection. Use when working with Zellij layouts, encountering "Operation not permitted" on layout files, need to save/restore session configurations, or manage protected configuration files on macOS. Covers auto-save mechanism, uchg flag protection, LaunchAgent setup, and AI agent interaction patterns.
allowed-tools	Read, Bash, Grep, Edit

Zellij Layout Preservation System

Auto-save system protecting Zellij session layouts from accidental deletion by AI agents using BSD immutable flags.

Key Features:

• Auto-save every 5 minutes via LaunchAgent
• Immutable flag (uchg) protection prevents deletion
• Session-aware updates
• Reboot-persistent configuration

---

Quick Reference

When to use this skill:

• Working with Zellij session layouts (tabs, panes, windows)
• Encountering "Operation not permitted" when trying to modify/delete layout files
• Need to automatically save current Zellij session configuration
• Want to protect configuration files from accidental deletion
• AI agent needs to update protected files safely
• Understanding BSD file flags on macOS

Protected File: ~/.config/zellij/layouts/default-terrylica.kdl

Session Name: default-terrylica

---

System Architecture

Zellij Session (active)
    ↓ every 5 minutes
LaunchAgent (com.terryli.zellij-save-layout.plist)
    ↓ triggers
Update Script (~/.local/bin/zellij-save-layout)
    ↓ performs
1. chflags nouchg (unlock)
2. zellij action dump-layout (save)
3. chflags uchg (lock)
    ↓ updates
Protected Layout File (uchg flag prevents deletion)

Components:

1. Active session: default-terrylica
2. LaunchAgent: Runs every 300 seconds
3. Update script: Handles lock/update/lock cycle
4. Protected file: ~/.config/zellij/layouts/default-terrylica.kdl

---

The Immutable Flag Mechanism (uchg)

Not Oxymoronic - It's a Removable Lock

The uchg (user changeable) flag is a BSD filesystem feature that prevents file deletion/modification until removed by file owner.

Analogy: Child-safety medicine bottle

• Child tries to open → Blocked (doesn't know the push-and-twist trick)
• Adult pushes + twists → Opens (knows the trick)

In filesystem terms:

• Random script tries rm file → Blocked (doesn't know about uchg)
• Authorized script runs chflags nouchg → Unlocks → Updates → Locks again

How It Works

# File is LOCKED
ls -lO file.kdl
# -rw-r--r-- 1 user staff uchg 9K file.kdl
#                          ^^^^

# Try to delete → BLOCKED
rm file.kdl
# Error: Operation not permitted ❌

# File owner UNLOCKS first
chflags nouchg file.kdl

# NOW it's unlocked (note missing 'uchg')
ls -lO file.kdl
# -rw-r--r-- 1 user staff - 9K file.kdl

# Now deletion works
rm file.kdl  # ✅ Success

Protection Hierarchy

Who	Can Remove Flag?	Can Delete?
File owner	✅ Yes	✅ Yes (after removing flag)
Root/sudo	✅ Yes	✅ Yes (after removing flag)
Other users	❌ No	❌ No
AI agents	❌ No (unless told)	❌ No
Scripts	❌ No	❌ No

---

Commands Reference

Status Checks

# Check if auto-save is running
launchctl list | grep zellij-save-layout
# Output: -  0  com.terryli.zellij-save-layout

# Verify file protection
ls -lhO ~/.config/zellij/layouts/default-terrylica.kdl
# Look for 'uchg' flag in output

# View recent saves
tail -20 /tmp/zellij-save-layout.log

# Check file timestamp (last save time)
ls -lh ~/.config/zellij/layouts/default-terrylica.kdl

Manual Operations

# Immediate manual save
save-zellij-layout

# Force auto-save (don't wait 5 minutes)
launchctl kickstart -k gui/$(id -u)/com.terryli.zellij-save-layout

# Rename current Zellij session
zellij action rename-session default-terrylica

# Dump layout to custom file
zellij action dump-layout > /tmp/my-layout.kdl

# Restore layout on restart
zellij --layout default-terrylica

LaunchAgent Management

# Start auto-save (already running)
launchctl load ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

# Stop auto-save
launchctl unload ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

# Check status
launchctl list | grep zellij-save-layout

Protection Management

# Enable protection
chflags uchg <file>

# Disable protection (for manual edit)
chflags nouchg <file>

# Check protection status
ls -lO <file>
# Look for 'uchg' in flags column

# Test protection (should fail)
rm ~/.config/zellij/layouts/default-terrylica.kdl
# Error: Operation not permitted ✅

---

AI Agent Interaction Guidelines

⚠️ CRITICAL: Do NOT Attempt to Delete

Protected file: ~/.config/zellij/layouts/default-terrylica.kdl

Why deletion will fail:

1. File has uchg immutable flag
2. Standard rm command returns: "Operation not permitted"
3. This is INTENTIONAL protection, not an error

If Agent Needs to Update Layout

❌ DO NOT:

# This will fail
rm ~/.config/zellij/layouts/default-terrylica.kdl
echo "new layout" > ~/.config/zellij/layouts/default-terrylica.kdl

✅ DO THIS INSTEAD:

Option 1 - Use dedicated script (recommended):

save-zellij-layout

Option 2 - Manual flag handling:

chflags nouchg ~/.config/zellij/layouts/default-terrylica.kdl
zellij action dump-layout > ~/.config/zellij/layouts/default-terrylica.kdl
chflags uchg ~/.config/zellij/layouts/default-terrylica.kdl

Detection Pattern

When encountering "Operation not permitted" on a file:

# Check for immutable flags
ls -lO <file_path>

# If output contains 'uchg' or 'schg':
# → This is a protected file
# → Look for dedicated update script
# → Do NOT force removal
# → Report to user: "File is immutable-protected"
# → Suggest proper update method

# Example detection
if ls -lO "$file" | grep -q "uchg"; then
    echo "File is protected with immutable flag"
    echo "Use save-zellij-layout or chflags to modify"
fi

Respect Patterns

Files with uchg flag are INTENTIONALLY protected. Agent should:

1. Detect flag via ls -lO
2. Report: "File is immutable-protected"
3. Suggest: "Use save-zellij-layout command"
4. Do NOT attempt sudo or force removal
5. Do NOT suggest workarounds that bypass protection

---

File Locations

Primary Files

Layout file (protected):

• Path: ~/.config/zellij/layouts/default-terrylica.kdl
• Size: ~9KB
• Protection: uchg immutable flag
• Updated: Every 5 minutes or on-demand

Update script:

• Path: ~/.local/bin/zellij-save-layout
• Purpose: Safely update protected layout
• Execution: Manual or via LaunchAgent

LaunchAgent:

• Path: ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist
• Interval: 300 seconds (5 minutes)
• Status: Active and running

Log Files

Success log: /tmp/zellij-save-layout.log

Layout saved and protected: ~/.config/zellij/layouts/default-terrylica.kdl

Error log: /tmp/zellij-save-layout.error.log

Zellij Session Cache

Zellij auto-saves to cache every 60 seconds:

~/Library/Caches/org.Zellij-Contributors.Zellij/0.43.1/session_info/default-terrylica/
├── session-layout.kdl
└── session-metadata.kdl

Our system copies from cache → persistent protected location.

---

Operational Workflows

Daily Use

1. Start Zellij with saved layout

   zellij --layout default-terrylica
   

2. Work normally (add tabs, panes, etc.)

   • Layout auto-saves every 5 minutes

3. Make critical changes

   save-zellij-layout  # Immediate save
   

4. Exit Zellij

   • Session preserved in cache
   • Layout protected from deletion

5. Next day: Restart

   zellij --layout default-terrylica
   # All tabs/panes restored
   

Recovery Scenarios

Scenario 1: Accidental session exit

zellij --layout default-terrylica
# Restores to last save (max 5 min old)

Scenario 2: System crash/reboot

# LaunchAgent auto-starts on login
# Layout file protected by uchg
zellij --layout default-terrylica

Scenario 3: Need to manually edit layout

# Unlock file
chflags nouchg ~/.config/zellij/layouts/default-terrylica.kdl

# Edit
hx ~/.config/zellij/layouts/default-terrylica.kdl

# Re-lock
chflags uchg ~/.config/zellij/layouts/default-terrylica.kdl

---

Troubleshooting

Auto-Save Not Running

Check status:

launchctl list | grep zellij-save-layout
# Should show: -  0  com.terryli.zellij-save-layout

If not listed:

launchctl load ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

Check logs:

tail -50 /tmp/zellij-save-layout.error.log

Layout Not Updating

Verify session name:

zellij list-sessions
# Ensure active session is named "default-terrylica"

Manual trigger:

save-zellij-layout
# Output: Layout saved and protected: ...

Check timestamp:

ls -lh ~/.config/zellij/layouts/default-terrylica.kdl
# Should be recent (within 5 min)

Cannot Delete File (Expected Behavior)

This is CORRECT - file is protected:

rm ~/.config/zellij/layouts/default-terrylica.kdl
# Error: Operation not permitted ✅

# If deletion is truly needed:
chflags nouchg ~/.config/zellij/layouts/default-terrylica.kdl
rm ~/.config/zellij/layouts/default-terrylica.kdl

---

Configuration Tuning

Change Auto-Save Interval

Current: 5 minutes (300 seconds)

# Edit LaunchAgent
vim ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

# Change interval (in seconds):
<key>StartInterval</key>
<integer>300</integer>  <!-- Change this -->

# Reload
launchctl unload ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist
launchctl load ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

Recommended intervals:

• 60 = 1 minute (frequent)
• 300 = 5 minutes (current, balanced)
• 600 = 10 minutes
• 1800 = 30 minutes

Stronger Protection (System Immutable)

For maximum protection (requires sudo to modify):

# Remove user flag
chflags nouchg ~/.config/zellij/layouts/default-terrylica.kdl

# Set system immutable
sudo chflags schg ~/.config/zellij/layouts/default-terrylica.kdl

# Now even root can't delete without removing flag

Note: Requires updating script to use sudo for updates.

---

Technical Details

Zellij Config Settings

From ~/.config/zellij/config.kdl:

session_serialization true           // Enable auto-save
serialize_pane_viewport true         // Save pane viewports
scrollback_lines_to_serialize 10000  // Save scrollback
serialization_interval 60            // Cache update interval

BSD File Flags

macOS inherits BSD filesystem flags:

Flag	Name	Protection	Who Can Remove
uchg	User immutable	Delete/modify blocked	File owner
schg	System immutable	Delete/modify blocked	Root only
uappnd	User append-only	Only append allowed	File owner
sappnd	System append-only	Only append allowed	Root only

We use uchg because:

• Blocks AI agents and scripts
• Owner can update without sudo
• Standard across BSD/macOS

Layout File Format (KDL)

Sample structure:

layout {
    cwd "/Users/terryli"
    tab name=".claude" focus=true {
        pane split_direction="vertical" {
            pane command="claude" size="65%"
            pane size="35%"
        }
    }
}

---

Security Notes

Protection Level

uchg flag protects against: ✅ Accidental rm commands ✅ AI agents (unless they know about uchg) ✅ Text editors overwriting ✅ > redirection overwrites ✅ Scripts without flag knowledge

uchg flag does NOT protect against: ❌ Intentional removal by file owner ❌ Root/sudo operations ❌ Agents explicitly coded to handle BSD flags

Why This Is Standard Practice

BSD file flags are 45+ years old (from 4.4BSD):

• Used in macOS system protection
• Standard across FreeBSD, OpenBSD, NetBSD
• Not a "trick" - it's documented filesystem feature
• Linux equivalent: chattr +i (ext2/3/4 immutable attribute)

---

Examples

Example 1: Check Auto-Save Status

# Full status check
launchctl list | grep zellij-save-layout && \
ls -lhO ~/.config/zellij/layouts/default-terrylica.kdl && \
tail -5 /tmp/zellij-save-layout.log

# Expected output:
# -  0  com.terryli.zellij-save-layout
# -rw-r--r-- 1 user staff uchg 9.3K Oct 30 21:16 default-terrylica.kdl
# Layout saved and protected: ~/.config/zellij/layouts/default-terrylica.kdl

Example 2: Manual Save After Changes

# Make changes in Zellij (add tab, split panes, etc.)

# Save immediately (don't wait 5 minutes)
save-zellij-layout

# Verify
ls -lh ~/.config/zellij/layouts/default-terrylica.kdl
# Timestamp should be current

Example 3: Test Protection

# Try to delete (should fail)
rm ~/.config/zellij/layouts/default-terrylica.kdl
# Error: Operation not permitted ✅

# Verify flag is set
ls -lO ~/.config/zellij/layouts/default-terrylica.kdl | grep uchg
# Output: -rw-r--r-- 1 user staff uchg ...

---

Quick Reference Card

# STATUS
launchctl list | grep zellij-save-layout    # Auto-save running?
ls -lhO ~/.config/zellij/layouts/default-terrylica.kdl  # Protected?
tail /tmp/zellij-save-layout.log            # Recent saves?

# MANUAL SAVE
save-zellij-layout                          # Save now

# RESTORE
zellij --layout default-terrylica           # Restore layout

# PROTECTION
chflags uchg <file>                         # Enable
chflags nouchg <file>                       # Disable
ls -lO <file>                               # Check status

# LAUNCHAGENT
launchctl load ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist
launchctl unload ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

---

See Also

• Zellij config: ~/.config/zellij/config.kdl
• Session storage: ~/Library/Caches/org.Zellij-Contributors.Zellij/
• Update script: ~/.local/bin/zellij-save-layout
• LaunchAgent: ~/Library/LaunchAgents/com.terryli.zellij-save-layout.plist

Official documentation:

• Zellij Session Resurrection: https://zellij.dev/documentation/session-resurrection.html
• Zellij Layouts: https://zellij.dev/documentation/layouts
• macOS chflags: man chflags
• launchd: man launchd.plist