Kubuntu + Claude Code Setup Guide

By the end of this guide you’ll have:

Kubuntu — a Linux desktop (running KDE Plasma). Looks and feels like Windows but faster, no ads, no telemetry.
Brave — web browser. Chrome-compatible but blocks ads and trackers by default.
Obsidian — note-taking app that stores everything as plain text files on your disk.
Claude Code — AI assistant in the terminal that reads and writes your Obsidian notes directly. This is the core of the OpenCairn system.
1Password — password manager.
Automated updates so you never think about maintenance.

Time estimate: ~4 hours.

OS: Kubuntu 26.04 LTS (long-term support — security updates until April 2029).

Phase 0: Backup (duration varies)
What You’ll Need
Phase 1: Create the USB Installer (~20 min)
Phase 2: Install Kubuntu (~35 min)
Phase 3: Set Up the Software Stack (~35 min)
Phase 4: Claude Code + Obsidian Setup (~45 min)
Phase 5: Backup Setup (~10 min)
Phase 6: Auto-Maintenance (~10 min)
Phase 7: Verify Everything (~5 min)
Daily Usage
If Something Goes Wrong
Hardware Notes

Phase 0: Backup

Back up anything you care about on the laptop. This process permanently erases everything on it. Copy files to a USB drive, cloud storage, or another computer before starting. This takes the longest — start here.

What You’ll Need

Before starting Phase 1, have these ready:

A supported Claude Code account — for most individuals, a Claude Pro or Max subscription
A USB drive (8GB+) — it will be wiped
WiFi password written down (the installer asks for it before your password manager is set up)
A 1Password account (or be ready to create one during setup) — have your email and master password accessible on another device
A second device (phone/tablet) to read these instructions on while the laptop is being set up

Phase 1: Create the USB Installer

Do this on a different computer (not the one you’re setting up).

Download Kubuntu

Open the official Kubuntu download page and choose Kubuntu 26.04 LTS

Create Bootable USB

Download balenaEtcher (free, works on Windows and Mac)
Open balenaEtcher
Select the .iso → select your USB drive (double-check — it will be wiped) → Flash
Wait ~5 minutes

Phase 2: Install Kubuntu

Boot from USB

Plug the USB into the laptop
Restart the laptop
As it boots, repeatedly press the boot menu key:
- Lenovo: F12
- Dell: F12
- HP: F9 or Esc
- ASUS: F8 or Esc
- Acer: F12
- Toshiba: F12 or F2
- If unsure, try F2 or F12 — or search “[your laptop brand] boot from USB”
Select the USB drive from the menu
If the USB doesn’t appear:
- Try another USB port, then restart and enter BIOS/UEFI setup (usually F2 or Del)
- Confirm USB boot is enabled and put the USB drive first in the boot order
- Keep Secure Boot enabled; Kubuntu supports it. Disable it only as a device-specific diagnostic after the ordinary boot settings are correct
- Save and exit

Run the Installer

Select “Install Kubuntu” (not “Try”)
Language: English
Set timezone to your location
Keyboard: English (US)
Customise installation: select “Minimal Installation” (we’ll install what we need ourselves)
Partitioning: select “Erase disk”
Encryption (recommended): Check “Encrypt system”
- Choose a strong passphrase — 3+ random words (e.g. “correct horse battery”)
- Write this down and store it safely. If you forget it, your data is permanently gone. No recovery, by design.
- You’ll type this passphrase every time you turn on the laptop, before the login screen
Create your user account:
- Your name: whatever you like
- Computer name: anything (e.g. my-laptop)
- Username: lowercase, no spaces (e.g. alex)
- Password: something you’ll remember
Review the summary and click “Install”
Wait ~15–20 minutes
Click “Done” to reboot
Remove the USB when told to

First Boot

If you set up encryption, enter your encryption passphrase
Log in with your password
Click through any setup wizard
Connect to WiFi (click the network icon in the system tray, bottom-right)
Open a terminal: click the application launcher (equivalent of the Start menu on Windows — bottom-left corner, or press the Super/Windows key) and type “Konsole”, then press Enter
Run this command to update everything:

sudo apt update && sudo apt full-upgrade -y

It will ask for your password. Nothing appears on screen as you type — that’s normal Linux behaviour. Just type it and press Enter.

If you see linux-image in the list of updates, reboot (application launcher → Power → Restart). This means a new Linux kernel was installed — the kernel loads into memory at boot, so the update won’t take effect until you restart.

Phase 3: Set Up the Software Stack

Open Konsole (press the Super/Windows key, type “Konsole”). You’ll be copy-pasting commands from here — we install a better terminal (WezTerm) as the first step.

Tip: To paste into a terminal, use Ctrl+Shift+V (not Ctrl+V).

Remove Snap

Snap is Ubuntu’s built-in app packaging. It’s slow, auto-updates aggressively, and duplicates functionality. We replace it with Flatpak.

# Remove all snap packages (retries as dependencies resolve)
for attempt in $(seq 1 10); do
    snap list 2>/dev/null | tail -n +2 | awk '{print $1}' | \
        xargs -I {} sudo snap remove --purge {} 2>/dev/null
    snap list 2>/dev/null | grep -v "^Name" | grep -q . || break
done

# Remove snapd itself and prevent it from coming back
sudo apt remove --purge snapd -y
sudo apt-mark hold snapd

# Clean up leftover files
rm -rf ~/snap
sudo rm -rf /var/snap /var/lib/snapd

Install Core Packages and WezTerm

sudo apt install -y git curl wget build-essential htop neovim \
    flatpak plasma-discover-backend-flatpak pipx

# Add Flathub (the main Flatpak app repository)
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install WezTerm (a better terminal) and fonts
curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/wezterm-fury.gpg
echo 'deb [signed-by=/usr/share/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' \
    | sudo tee /etc/apt/sources.list.d/wezterm.list
sudo chmod 644 /usr/share/keyrings/wezterm-fury.gpg
sudo apt update && sudo apt install -y wezterm fonts-jetbrains-mono fonts-noto fonts-noto-color-emoji

If the WezTerm repository fails, download the .deb directly from the WezTerm releases page and install it with sudo apt install ./wezterm-*.deb.

Set WezTerm as default terminal:

sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator /usr/bin/wezterm 50
sudo update-alternatives --set x-terminal-emulator /usr/bin/wezterm

Configure WezTerm:

mkdir -p ~/.config/wezterm
cat > ~/.config/wezterm/wezterm.lua << 'EOF'
local wezterm = require 'wezterm'
local config = {}

config.color_scheme = 'Catppuccin Mocha'
config.font = wezterm.font 'JetBrains Mono'
config.font_size = 12.0
config.scrollback_lines = 10000
config.enable_scroll_bar = false

config.keys = {
    { key = 't', mods = 'CTRL', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
    { key = 'w', mods = 'CTRL', action = wezterm.action.CloseCurrentTab { confirm = true } },
}

for i = 1, 9 do
    table.insert(config.keys, { key = tostring(i), mods = 'CTRL', action = wezterm.action.ActivateTab(i - 1) })
end

return config
EOF

See the full WezTerm setup guide for more configuration options.

Set up Ctrl+Alt+T to open WezTerm (it’s bound to Konsole by default):

System Settings → Keyboard → Shortcuts → search for “Konsole” → clear its shortcut → then search for “WezTerm” → set its shortcut to Ctrl+Alt+T.

Reboot now — the Flatpak integration with KDE Discover needs a fresh session. Click the application launcher → Power → Restart.

Install Apps

Open WezTerm after reboot (Ctrl+Alt+T):

# Brave browser
flatpak install -y flathub com.brave.Browser

# Firefox (backup browser)
flatpak install -y flathub org.mozilla.firefox

# Obsidian (note-taking)
flatpak install -y flathub md.obsidian.Obsidian

# 1Password — NOT on Flathub, uses its own repository
flatpak install -y https://downloads.1password.com/linux/flatpak/1Password.flatpakref

Each will ask you to confirm — just press Enter or type Y.

Set up 1Password: Open 1Password from the application launcher (press the Super/Windows key and type “1Password”). Sign in with your 1Password account (or create one at 1password.com). Then in Brave, install the 1Password browser extension from the Chrome Web Store — this lets you autofill passwords on websites. Store your encryption passphrase from Phase 1 here so you have a backup.

Set up Brave Sync: If you use Brave on other devices, go to Settings → Sync → Start a new Sync Chain. Add each device using the QR code or current Sync code. The word code requires a rotating final word that changes daily, so don’t treat it as a static recovery phrase; keep an existing device connected to the chain. Enable only the data types you want. Brave encrypts Sync data on the client before sending it to its servers.

Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

This installs a standalone binary to ~/.local/bin/claude — no Node.js or other dependencies needed. It auto-updates in the background.

Verify it worked:

claude --version

Phase 4: Claude Code + Obsidian Setup

~/Files becomes both your Obsidian vault and Claude Code’s workspace.

Linux home directories: Every user has a home directory at /home/yourusername — equivalent to C:\Users\yourusername on Windows. The shorthand ~ (tilde) always means your home directory, so ~/Files = /home/yourusername/Files. You’ll see ~ used throughout this guide and in Linux documentation generally.

Clone the Template

git clone https://github.com/OpenCairn/OpenCairn.git ~/Files
cd ~/Files
git remote rename origin template
chmod +x .claude/scripts/*.sh

This creates the NIPARAS folder structure in ~/Files:

~/Files/
├── 01 Now/       ← What you're working on right now
├── 02 Inbox/     ← Unsorted captures (also where browser downloads go)
├── 03 Projects/  ← Things with an end state ("Plan trip to Japan")
├── 04 Areas/     ← Ongoing life domains (Health, Finances, Career...)
├── 05 Resources/ ← Reference material
├── 06 Archive/   ← Completed/inactive stuff
├── 07 System/    ← Configuration and context files
└── CLAUDE.md     ← The file that tells Claude who you are

Verify the slash commands are in place:

ls ~/Files/.claude/commands/
# Should show: park.md, pickup.md, morning.md, goodnight.md, etc.

Configure Environment

The template’s scripts need a VAULT_PATH variable so they know where your vault lives. Add it along with a convenience alias:

cat >> ~/.bashrc << 'BASHEOF'

# OpenCairn: vault path (required by template scripts)
export VAULT_PATH="$HOME/Files"

# OpenCairn: launch Claude Code from vault root
alias cc='cd ~/Files && claude'
BASHEOF
source ~/.bashrc

Now you can type cc from anywhere to launch Claude Code in your vault.

Remap XDG Directories

By default, Linux puts downloads in ~/Downloads. We redirect them into the NIPARAS folders:

# Create target directories (some may not exist yet)
mkdir -p ~/Files/"05 Resources/Pictures" ~/Files/"05 Resources/Videos" ~/Files/"05 Resources/Music"
mkdir -p ~/Files/"05 Resources/Templates" ~/Files/"05 Resources/Public"

cat > ~/.config/user-dirs.dirs << 'EOF'
XDG_DOWNLOAD_DIR="$HOME/Files/02 Inbox"
XDG_DOCUMENTS_DIR="$HOME/Files/04 Areas"
XDG_PICTURES_DIR="$HOME/Files/05 Resources/Pictures"
XDG_VIDEOS_DIR="$HOME/Files/05 Resources/Videos"
XDG_MUSIC_DIR="$HOME/Files/05 Resources/Music"
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_TEMPLATES_DIR="$HOME/Files/05 Resources/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Files/05 Resources/Public"
EOF

xdg-user-dirs-update

# Remove the now-unused default directories (only removes if empty)
rmdir ~/Documents ~/Downloads ~/Music ~/Pictures ~/Public ~/Templates ~/Videos 2>/dev/null

First Claude Code Session

cd ~/Files
claude

Follow the authentication prompts — it will open a browser window for you to sign in to your Anthropic account. Then check claude.ai → Settings → Privacy. Under Anthropic’s current consumer data policy, if “Improve Claude for everyone” is on, Anthropic may use consumer Claude Code sessions for model improvement and retain them for five years. Turning it off means 30-day retention for Claude Code data.

Once you’re in (you’ll see a > prompt), run:

/setup

OpenCairn checks the environment, then interviews you to personalise CLAUDE.md and create the context-file stubs.

When you’re done, type /park to save your session state, then /exit to quit.

Set Up Obsidian

Open Obsidian (find it in the application launcher)
Click “Open folder as vault”
Navigate to /home/yourusername/Files and select it
You should see the NIPARAS folders (01 Now, 02 Inbox, etc.) in the sidebar

Dolphin is Kubuntu’s file manager — the equivalent of File Explorer on Windows. Replace its default sidebar entries with the NIPARAS folders:

# Close Dolphin first if it's open, then write the sidebar config
cat > ~/.local/share/user-places.xbel << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xbel>
<xbel xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks"
      xmlns:kdepriv="http://www.kde.org/kdepriv"
      xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info">
 <info>
  <metadata owner="http://www.kde.org">
   <kde_places_version>4</kde_places_version>
  </metadata>
 </info>
 <bookmark href="file://$HOME">
  <title>Home</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="user-home"/>
   </metadata>
  </info>
 </bookmark>
 <separator/>
 <bookmark href="file://$HOME/Files/01%20Now">
  <title>01 Now</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-red"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/02%20Inbox">
  <title>02 Inbox</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-download"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/03%20Projects">
  <title>03 Projects</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-activities"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/04%20Areas">
  <title>04 Areas</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-favorites"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/05%20Resources">
  <title>05 Resources</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-documents"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/06%20Archive">
  <title>06 Archive</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-tar"/>
   </metadata>
  </info>
 </bookmark>
 <bookmark href="file://$HOME/Files/07%20System">
  <title>07 System</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="folder-system"/>
   </metadata>
  </info>
 </bookmark>
 <separator/>
 <bookmark href="trash:/">
  <title>Trash</title>
  <info>
   <metadata owner="http://freedesktop.org">
    <bookmark:icon name="user-trash"/>
   </metadata>
  </info>
 </bookmark>
</xbel>
EOF

Open Dolphin to verify the sidebar shows the NIPARAS folders.

Phase 5: Backup Setup

Option A: Obsidian Sync (Recommended for Phone Access)

Cost: $4 USD/month billed annually, or $5 month-to-month. Syncs your notes to your phone automatically.

In Obsidian: Settings (gear icon) → Core plugins → Sync → Enable
Settings → Sync → Subscribe
Create a remote vault, set an encryption password (store this in 1Password)
In Sync settings → Selective sync, toggle off Images, Audio, and Video — these eat through your storage quota fast and aren’t needed on every device
Wait for initial sync to complete
On your phone: install Obsidian → connect to the same remote vault

Option B: No Sync

If you skip sync, your notes only exist on this laptop. If the drive dies, they’re gone. You can always add backup later — see Automated Backups for the full guide.

Phase 6: Auto-Maintenance

These timers run daily in the background so you never think about updates.

Flatpak Auto-Updates

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/flatpak-update.service << 'EOF'
[Unit]
Description=Update Flatpak apps

[Service]
Type=oneshot
ExecStart=/usr/bin/flatpak update -y --noninteractive
EOF

cat > ~/.config/systemd/user/flatpak-update.timer << 'EOF'
[Unit]
Description=Daily Flatpak update

[Timer]
OnCalendar=*-*-* 20:00:00
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now flatpak-update.timer

System Package Auto-Updates

sudo tee /etc/systemd/system/apt-full-upgrade.service << 'EOF'
[Unit]
Description=APT full upgrade

[Service]
Type=oneshot
ExecStart=/usr/bin/apt update
ExecStart=/usr/bin/apt full-upgrade -y
EOF

sudo tee /etc/systemd/system/apt-full-upgrade.timer << 'EOF'
[Unit]
Description=Daily APT upgrade

[Timer]
OnCalendar=*-*-* 20:00:00
Persistent=true

[Install]
WantedBy=timers.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now apt-full-upgrade.timer

Auto-Empty Trash

Deletes files in your trash older than 10 days:

pipx ensurepath
export PATH="$PATH:$HOME/.local/bin"
pipx install autotrash
autotrash --install -d 10

Phase 7: Verify Everything

Reboot one final time (application launcher → Power → Restart), then check:

Encryption passphrase works (if enabled)
WiFi reconnects automatically
Shutdown completes normally
Brave opens and can browse
Obsidian opens and shows your vault
Claude Code starts — type cc in terminal
1Password opens and you can log in
Slash commands work — try /morning in Claude Code
Obsidian Sync shows changes on phone (if set up)

Daily Usage

The Core Loop

When	What	Command
Start a session	See what’s active, pick up where you left off	`/pickup`
End a session	Save what you did, capture open loops	`/park`
Start of day	Surface priorities, build a plan	`/morning`
End of day	Inventory loops, queue tomorrow	`/goodnight`

Quick Examples

Ask Claude anything with your full context loaded:

> I'm thinking about switching careers. What do I know about my goals?
> Help me plan a weekend trip to [destination]
> Draft a reply to [person] about [topic]

Manage your notes:

> /start-project Plan a Trip to Japan
> /inbox-processor
> /thinking-partner

Tips

cc from any terminal launches Claude Code in your vault
Claude reads your CLAUDE.md every session — keep it updated as your life changes
/park at the end of every session means you never lose context
Run /update occasionally to pull the latest template improvements
See Claude Code Tips for more

If Something Goes Wrong

Ask Claude Code. Type cc, then describe the problem. It can troubleshoot most Linux issues directly.
WiFi won’t connect after install: Connect your phone via USB cable and enable “USB tethering” in your phone’s settings. Then ask Claude Code to troubleshoot WiFi.
Forgot encryption passphrase: Data is unrecoverable. This is by design. Keep the passphrase in 1Password.
Shutdown hangs for minutes: Install all updates, reboot, reproduce it, then see Hardware Notes below.

Hardware Notes

Older versions of this guide carried a MediaTek MT7925 GRUB and module-blacklist workaround. It is no longer a default recommendation on Kubuntu 26.04: applying it pre-emptively can disable power management or Bluetooth. If shutdown still takes minutes after a full update and reboot, inspect the previous boot’s shutdown logs for that machine before changing GRUB or blacklisting modules.

What’s Next

Read the OpenCairn introduction to understand the design philosophy
Read Park and Pickup to understand how session continuity works
Browse Claude Code Tips for workflow patterns and keyboard shortcuts