docs: rebuild KB in OKF v0.1 with live-verified facts
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
This commit is contained in:
Frank
@@ -0,0 +1,77 @@
|
||||
---
|
||||
type: index
|
||||
title: Default Applications
|
||||
description: Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
tags:
|
||||
- applications
|
||||
- cachyos
|
||||
- niri
|
||||
- userspace
|
||||
- index
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
# Default Applications
|
||||
|
||||
Applications that ship with or are configured on CachyOS with Niri on dankware.
|
||||
|
||||
## Core Applications
|
||||
|
||||
| Application | Version | Purpose |
|
||||
|-------------|---------|---------|
|
||||
| ](ghostty/index.md) | 1.3.1 | Terminal emulator |
|
||||
| **Firefox** | 153.0 | Primary browser |
|
||||
| **Chromium** | 150.0 | Secondary browser |
|
||||
| **Nautilus** | 50.2.2 | File manager |
|
||||
| **Neovim** | 0.12.4 | Text editor |
|
||||
| **Steam** | 1.0.0.86 | Gaming platform |
|
||||
|
||||
## System Utilities
|
||||
|
||||
| Application | Version | Purpose |
|
||||
|-------------|---------|---------|
|
||||
| **Noctalia Shell** | 4.7.7 | Desktop shell (launcher, wallpaper, session menu) |
|
||||
| **Shelly Notifications** | — | Notification daemon |
|
||||
| **pavucontrol** | — | Audio mixer |
|
||||
| **wlr-randr** | — | Display management |
|
||||
|
||||
## Screenshot and Recording
|
||||
|
||||
| Application | Purpose |
|
||||
|-------------|---------|
|
||||
| **grim** | Wayland screenshot |
|
||||
| **slurp** | Region selector |
|
||||
| **swappy** | Screenshot annotator |
|
||||
| **wf-recorder** | Screen recording |
|
||||
| **hyprpicker** | Color picker |
|
||||
| **wl-clipboard** | Wayland clipboard |
|
||||
|
||||
## Audio
|
||||
|
||||
| Application | Version | Purpose |
|
||||
|-------------|---------|---------|
|
||||
| **PipeWire** | 1.6.8 | Multimedia router |
|
||||
| **WirePlumber** | 0.5.15 | Session manager |
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Noctalia Shell] --> B[Mod+Return<br/>Ghostty]
|
||||
A --> C[Mod+CTRL+Return<br/>Launcher]
|
||||
A --> D[Mod+B<br/>Firefox]
|
||||
A --> E[Mod+E<br/>Nautilus]
|
||||
A --> F[Mod+ALT+L<br/>Lock]
|
||||
A --> G[Mod+Shift+Q<br/>Session]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [[cachyos|cachyos]] — Operating system documentation
|
||||
- [[noctalia-shell|noctalia-shell]] — Desktop shell
|
||||
- [niri](niri/index.md) — Compositor
|
||||
- ](ghostty/index.md) — Terminal configuration
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
type: reference
|
||||
title: CachyOS
|
||||
description: Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware.
|
||||
tags:
|
||||
- cachyos
|
||||
- arch
|
||||
- linux
|
||||
- kernel
|
||||
- performance
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
# CachyOS
|
||||
|
||||
CachyOS is an Arch Linux-based rolling release distribution focused on performance. It ships with custom kernels featuring the EEVDF scheduler, LTO compilation, AutoFDO profiling, and Propeller scheduling patches.
|
||||
|
||||
---
|
||||
|
||||
## System Information
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **OS** | CachyOS (rolling) |
|
||||
| **Kernel** | `linux-cachyos 7.1.4-1` |
|
||||
| **LTS Kernel** | `linux-cachyos-lts 6.18.38-2` |
|
||||
| **Package Manager** | pacman |
|
||||
| **Init** | systemd |
|
||||
| **Display Manager** | SDDM |
|
||||
|
||||
## Kernel Features
|
||||
|
||||
The CachyOS kernel includes:
|
||||
|
||||
- **EEVDF Scheduler** — Earliest Eligible Virtual Deadline First, successor to CFS
|
||||
- **LTO** — Link-Time Optimization for better code generation
|
||||
- **AutoFDO** — Auto Feedback-Directed Optimization from profiling data
|
||||
- **Propeller Scheduling** — Reduced latency scheduling patches
|
||||
|
||||
## Repositories
|
||||
|
||||
CachyOS uses v3 repositories alongside standard Arch repos:
|
||||
|
||||
| Repository | Purpose |
|
||||
|------------|---------|
|
||||
| `[cachyos-v3]` | CachyOS-specific packages (kernels, tools) |
|
||||
| `[cachyos-extra-v3]` | CachyOS extra packages |
|
||||
| `[cachyos-core-v3]` | CachyOS core packages |
|
||||
| `[cachyos]` | Legacy CachyOS repo |
|
||||
| `[core]` | Arch core |
|
||||
| `[extra]` | Arch extra |
|
||||
| `[multilib]` | 32-bit compatibility |
|
||||
|
||||
## CachyOS-Specific Packages
|
||||
|
||||
| Package | Description |
|
||||
|---------|-------------|
|
||||
| `cachyos-kernel-manager` | Simple kernel manager (1.19.0) |
|
||||
| `cachyos-hello` | Welcome screen (0.26.0) |
|
||||
| `cachyos-gaming-meta` | Gaming dependencies meta-package |
|
||||
| `cachyos-gaming-applications` | Common gaming applications |
|
||||
| `cachyos-ananicy-rules` | Process auto-categorization rules |
|
||||
| `cachyos-fish-config` | Fish shell configuration |
|
||||
| `cachyos-alacritty-config` | Alacritty terminal config |
|
||||
| `cachyos-hooks` | libalpm hooks |
|
||||
| `cachyos-micro-settings` | Micro settings utility |
|
||||
|
||||
## Gaming Stack
|
||||
|
||||
CachyOS ships with a comprehensive gaming stack:
|
||||
|
||||
- **Proton-CachyOS-SLR** — Proton with Same-Level-Root patches
|
||||
- **Wine-CachyOS-Opt** — Optimized Wine build
|
||||
- **UMU Launcher** — Universal Minecraft/Unity launcher
|
||||
- **ProtonTricks / Winetricks** — Wine configuration utilities
|
||||
- **Vulkan Tools** — Vulkan validation and utilities
|
||||
- **32-bit libraries** — Full lib32 support for Steam
|
||||
|
||||
## Default Userspace
|
||||
|
||||
CachyOS with Niri ships with a curated set of applications:
|
||||
|
||||
- **Niri** — Scrollable-tiling Wayland compositor
|
||||
- **Noctalia Shell** — Desktop shell (launcher, wallpaper, session menu, lock screen)
|
||||
- **Shelly Notifications** — Notification daemon
|
||||
- **Ghostty** — Terminal emulator
|
||||
- **Firefox** — Web browser
|
||||
- **Chromium** — Alternative browser
|
||||
- **Nautilus** — File manager
|
||||
- **Neovim** — Text editor
|
||||
- **Steam** — Gaming platform
|
||||
- **PipeWire + WirePlumber** — Audio
|
||||
- **grim/slurp/swappy** — Screenshots
|
||||
- **wf-recorder** — Screen recording
|
||||
- **hyprpicker** — Color picker
|
||||
- **wl-clipboard** — Clipboard management
|
||||
- **wlr-randr** — Display management
|
||||
- **NetworkManager** — Network management
|
||||
- **BlueZ** — Bluetooth
|
||||
- **pavucontrol** — Audio mixer
|
||||
- **gvfs** — Virtual filesystem
|
||||
- **GNOME Keyring** — Credential storage
|
||||
- **xdg-desktop-portal-gnome** — Portal services
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- ](../system/index.md) — dankware overview
|
||||
- [niri](niri/index.md) — Compositor documentation
|
||||
- [[noctalia-shell|noctalia-shell]] — Desktop shell documentation
|
||||
- [[applications|applications]] — Application reference
|
||||
@@ -0,0 +1,87 @@
|
||||
# ComfyUI
|
||||
|
||||
Node-based AI image generation engine running on `dankclaw`. Serves a web UI on port 8188.
|
||||
|
||||
## Access
|
||||
|
||||
Open `http://dankclaw:8188` in a browser. Accessible from any host on the 192.168.0.0/24 LAN.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Host** | dankclaw (192.168.0.143) |
|
||||
| **Version** | v0.30.0 |
|
||||
| **Python** | 3.14.4, venv at `~/ComfyUI/venv` |
|
||||
| **PyTorch** | 2.13.0+cu130 (CPU backend) |
|
||||
| **Backend** | CPU — ROCm unavailable on Strix Halo (GFX13) |
|
||||
| **Model** | FLUX.2 [klein] 4B (7.3 GB, Apache 2.0) |
|
||||
| **Service** | User-level systemd, `~/.config/systemd/user/comfyui.service` |
|
||||
| **Models dir** | `~/models` via `extra_model_paths.yaml` |
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
/home/dank/
|
||||
├── ComfyUI/
|
||||
│ ├── main.py # Entry point
|
||||
│ ├── venv/ # Python virtual environment
|
||||
│ ├── extra_model_paths.yaml # Links ~/models as model source
|
||||
│ └── models/ # ComfyUI-native model subdirs (empty)
|
||||
└── models/
|
||||
└── checkpoints/
|
||||
└── flux-2-klein-4b.safetensors
|
||||
```
|
||||
|
||||
## Service Management
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
ssh dank@dankclaw 'systemctl --user status comfyui --no-pager'
|
||||
|
||||
# Restart
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
|
||||
# Stop
|
||||
ssh dank@dankclaw 'systemctl --user stop comfyui'
|
||||
|
||||
# View logs
|
||||
ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 50'
|
||||
```
|
||||
|
||||
## Add a New Model
|
||||
|
||||
Place the `.safetensors` file in `~/models/checkpoints/`. ComfyUI detects it on restart.
|
||||
|
||||
```bash
|
||||
# Example: download a new model
|
||||
ssh dank@dankclaw 'mkdir -p ~/models/checkpoints'
|
||||
scp new-model.safetensors dank@dankclaw:~/models/checkpoints/
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
The AMD Ryzen AI MAX+ 395 has 16 CPU cores. ROCm does not support the Strix Halo (GFX13) APU in precompiled wheels. ComfyUI runs on CPU only. Expect generation times in the range of minutes per image.
|
||||
|
||||
## ComfyUI-Manager
|
||||
|
||||
Custom node manager installed at `~/ComfyUI/custom_nodes/ComfyUI-Manager`. Provides a UI to browse, install, and update custom nodes and models directly from the ComfyUI web interface.
|
||||
|
||||
### Install a Custom Node
|
||||
|
||||
1. Open the ComfyUI web UI
|
||||
2. Click **Manager** in the sidebar
|
||||
3. Search for the node and click **Install**
|
||||
4. Restart ComfyUI when prompted
|
||||
|
||||
### Update All Nodes
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && python custom_nodes/ComfyUI-Manager/cm-cli.sh update' && systemctl --user restart comfyui
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Troubleshooting](troubleshooting.md) — Common errors and fixes
|
||||
- [Dankclaw](../../system/dankclaw.md) — Host system overview
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
type: reference
|
||||
title: ComfyUI Troubleshooting
|
||||
description: Common errors, diagnostics, and recovery steps for ComfyUI on dankclaw.
|
||||
tags:
|
||||
- image-generation
|
||||
- comfyui
|
||||
- troubleshooting
|
||||
- dankclaw
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# ComfyUI Troubleshooting
|
||||
|
||||
Procedures for diagnosing and fixing ComfyUI on dankclaw.
|
||||
|
||||
## Service Will Not Start
|
||||
|
||||
Check the journal logs first.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 100'
|
||||
```
|
||||
|
||||
### "RuntimeError: No HIP GPUs are available"
|
||||
|
||||
Cause: The container's ROCm PyTorch cannot see the Strix Halo (gfx1151) GPU. This can happen when `/dev/kfd` and `/dev/dri` are not properly passthrough, or when the ROCm PyTorch build doesn't match the GPU architecture.
|
||||
|
||||
Fix: Verify GPU passthrough is configured in `compose.yaml` (should include `/dev/kfd` and `/dev/dri`). The container image is `comfyui-rocm:gfx1151` which should contain the correct ROCm kernels.
|
||||
|
||||
Check that the container image uses the AMD gfx1151 base:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'podman inspect comfyui --format "{{.Config.Image}}"'
|
||||
```
|
||||
|
||||
If the GPU still doesn't work, ensure the host user is in the `render` group:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'id dank'
|
||||
```
|
||||
|
||||
### "HIP error: invalid device function"
|
||||
|
||||
Cause: The ROCm PyTorch kernels don't match the GPU architecture. The ComfyUI container uses the AMD gfx1151 base image (`comfyui-rocm:gfx1151`), but if PyTorch was reinstalled without the ROCm build, this error occurs.
|
||||
|
||||
Fix: Reinstall the gfx1151 ROCm PyTorch. The container image already ships the correct version (torch 2.9.1+rocm). If the venv was rebuilt outside the container, reinstall:
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && \
|
||||
pip uninstall torch torchvision torchaudio pytorch-triton-rocm -y && \
|
||||
pip install torch torchvision torchaudio'
|
||||
```
|
||||
|
||||
### Port 8188 Already in Use
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'ss -tlnp | grep 8188'
|
||||
```
|
||||
|
||||
Kill the conflicting process or change the port in the service file.
|
||||
|
||||
## Model Not Loading
|
||||
|
||||
Check that the model file exists in the correct path.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'ls -lh ~/models/checkpoints/*.safetensors'
|
||||
```
|
||||
|
||||
Verify `extra_model_paths.yaml` points to the correct base path.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'cat ~/ComfyUI/extra_model_paths.yaml'
|
||||
```
|
||||
|
||||
Restart ComfyUI after adding or removing models.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'systemctl --user restart comfyui'
|
||||
```
|
||||
|
||||
## Cannot Reach the Web UI
|
||||
|
||||
Test connectivity from dankware.
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" http://dankclaw:8188
|
||||
```
|
||||
|
||||
Expected response: `200`.
|
||||
|
||||
If the response is empty or times out, verify the service is running.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'systemctl --user status comfyui --no-pager'
|
||||
ssh dank@dankclaw 'ss -tlnp | grep 8188'
|
||||
```
|
||||
|
||||
## Out of Memory
|
||||
|
||||
ComfyUI loads the full model into RAM. FLUX.2 klein 4B requires approximately 13 GB. The system has 119 GB total. Close other memory-intensive applications if OOM occurs.
|
||||
|
||||
Check memory usage.
|
||||
|
||||
```bash
|
||||
ssh dank@dankclaw 'free -h'
|
||||
ssh dank@dankclaw 'systemctl --user show comfyui --property=MemoryCurrent'
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [comfyui](index.md) — Main documentation
|
||||
@@ -0,0 +1,492 @@
|
||||
---
|
||||
type: reference
|
||||
title: Ghostty Configuration Options — Complete Reference
|
||||
description: Every configuration option for Ghostty, organized by category with types, defaults, and usage examples.
|
||||
tags:
|
||||
- terminal
|
||||
- ghostty
|
||||
- configuration
|
||||
- reference
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Ghostty Configuration Reference
|
||||
|
||||
Complete option catalog for [Ghostty](https://ghostty.org). See [Overview](index.md) for setup and quick-start.
|
||||
|
||||
---
|
||||
|
||||
## Font Configuration
|
||||
|
||||
### `font-family`
|
||||
|
||||
**Type**: String (repeatable)
|
||||
|
||||
Primary font family with fallback support.
|
||||
|
||||
```ini
|
||||
font-family = "JetBrains Mono"
|
||||
font-family = "Noto Sans Mono" # fallback
|
||||
```
|
||||
|
||||
Styles (bold, italic, bold-italic) are automatically found. Use `ghostty +list-fonts` to see available fonts.
|
||||
|
||||
### `font-style`, `font-style-bold`, `font-style-italic`, `font-style-bold-italic`
|
||||
|
||||
**Type**: String or `false`
|
||||
|
||||
A named font style from the font's own style string, for example "Heavy" or "Semibold". Set to `false` to completely disable a style.
|
||||
|
||||
### `font-synthetic-style`
|
||||
|
||||
**Type**: String (comma-separated)
|
||||
|
||||
Control whether Ghostty synthesizes missing styles. Values: `true`, `false`, `bold,italic,bold-italic`, `no-bold,no-italic`.
|
||||
|
||||
### `font-feature`
|
||||
|
||||
**Type**: String (repeatable, comma-separated)
|
||||
|
||||
OpenType font features. Enable: `feat`, `+feat`, `feat on`, `feat=1`. Disable: `-feat`, `feat off`, `feat=0`.
|
||||
|
||||
```ini
|
||||
font-feature = -calt # disable programming ligatures
|
||||
font-feature = -liga # disable standard ligatures
|
||||
```
|
||||
|
||||
### `font-size`
|
||||
|
||||
**Type**: Number (can be non-integer, in points)
|
||||
|
||||
```ini
|
||||
font-size = 12
|
||||
font-size = 13.5 # 27px on a 2x DPI display
|
||||
```
|
||||
|
||||
### `font-variation`
|
||||
|
||||
**Type**: String in `id=value` format (repeatable)
|
||||
|
||||
Variable font axis values (4-character IDs).
|
||||
|
||||
```ini
|
||||
font-variation = wght=700
|
||||
font-variation = wdth=100
|
||||
```
|
||||
|
||||
### `font-codepoint-map`
|
||||
|
||||
**Type**: String (repeatable)
|
||||
|
||||
Force Unicode codepoints to map to a specific font.
|
||||
|
||||
```ini
|
||||
font-codepoint-map = U+2500-U+257F=JetBrains Mono
|
||||
```
|
||||
|
||||
### `clipboard-codepoint-map`
|
||||
|
||||
**Type**: String (repeatable)
|
||||
|
||||
Map codepoints to replacement values when copying to clipboard.
|
||||
|
||||
```ini
|
||||
clipboard-codepoint-map = U+2500=U+002D # box drawing → hyphen
|
||||
clipboard-codepoint-map = U+03A3=SUM # Greek sigma → "SUM"
|
||||
```
|
||||
|
||||
### `grapheme-width-method`
|
||||
|
||||
**Type**: String
|
||||
|
||||
Width calculation method: `unicode` (default, correct but can cause cursor-desync) or `legacy` (wcswidth, maximizes compatibility).
|
||||
|
||||
---
|
||||
|
||||
## Alpha Blending & Rendering
|
||||
|
||||
### `alpha-blending`
|
||||
|
||||
**Type**: String
|
||||
|
||||
Color space for alpha blending (available since 1.1.0): `native` (OS-native, macOS default), `linear` (eliminates darkening artifacts), `linear-corrected` (Linux default).
|
||||
|
||||
---
|
||||
|
||||
## Cell Adjustments
|
||||
|
||||
All `adjust-*` options accept integers (1, -1) or percentages (20%, -15%).
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `adjust-cell-width` | Cell width adjustment |
|
||||
| `adjust-cell-height` | Cell height (also centers font vertically, adjusts Powerline glyphs) |
|
||||
| `adjust-font-baseline` | Baseline position |
|
||||
| `adjust-underline-position` | Underline position |
|
||||
| `adjust-underline-thickness` | Underline thickness |
|
||||
| `adjust-strikethrough-position` | Strikethrough position |
|
||||
| `adjust-strikethrough-thickness` | Strikethrough thickness |
|
||||
| `adjust-overline-position` | Overline position |
|
||||
| `adjust-overline-thickness` | Overline thickness |
|
||||
| `adjust-cursor-thickness` | Bar/rect cursor thickness |
|
||||
| `adjust-cursor-height` | Cursor height |
|
||||
| `adjust-box-thickness` | Box drawing character thickness |
|
||||
| `adjust-icon-height` | Nerd font icon height (available since 1.2.0) |
|
||||
|
||||
**Warning**: Invalid values, for example -100%, can make the terminal unusable.
|
||||
|
||||
---
|
||||
|
||||
## Theme & Colors
|
||||
|
||||
### `theme`
|
||||
|
||||
**Type**: String
|
||||
|
||||
Theme name, absolute path, or light/dark pair: `light:Rose Pine Dawn,dark:Rose Pine`.
|
||||
|
||||
### `background` / `foreground`
|
||||
|
||||
**Type**: Color (`#RRGGBB`, `RRGGBB`, or named X11 color)
|
||||
|
||||
### `palette`
|
||||
|
||||
**Type**: `N=COLOR` (repeatable, N = 0–255)
|
||||
|
||||
```ini
|
||||
palette = 0=#1d1f21
|
||||
palette = 0x00=#1d1f21
|
||||
palette-generate = true
|
||||
```
|
||||
|
||||
Only set 0-15 for most themes; 16-255 auto-generated if `palette-generate` is enabled.
|
||||
|
||||
### `bold-color`
|
||||
|
||||
**Type**: Color or `bright` (available since 1.2.0)
|
||||
|
||||
Replaces deprecated `bold-is-bright`.
|
||||
|
||||
### `minimum-contrast`
|
||||
|
||||
**Type**: Number (1-21)
|
||||
|
||||
Minimum contrast ratio (WCAG 2.0). Value of 3+ = avoid hard-to-read text.
|
||||
|
||||
---
|
||||
|
||||
## Appearance
|
||||
|
||||
### `background-image`
|
||||
|
||||
**Type**: Path (PNG or JPEG, available since 1.2.0)
|
||||
|
||||
Per-terminal background image. **Warning**: Currently duplicated in VRAM per-terminal.
|
||||
|
||||
### `background-opacity`
|
||||
|
||||
**Type**: Number (0-1)
|
||||
|
||||
Window transparency. On macOS, disabled in native fullscreen.
|
||||
|
||||
### `background-blur`
|
||||
|
||||
**Type**: Number, `true`, `false`, or macOS special values
|
||||
|
||||
Blur background when opacity < 1. macOS special: `macos-glass-regular`, `macos-glass-clear` (macOS 26.0+).
|
||||
|
||||
---
|
||||
|
||||
## Selection
|
||||
|
||||
### `copy-on-select`
|
||||
|
||||
**Type**: Boolean or `clipboard`
|
||||
|
||||
Automatically copy selected text. `clipboard` copies to both selection and system clipboard.
|
||||
|
||||
### `selection-clear-on-typing`
|
||||
|
||||
**Type**: Boolean (available since 1.2.0)
|
||||
|
||||
Clear selection when typing. Default: `true`.
|
||||
|
||||
---
|
||||
|
||||
## Cursor
|
||||
|
||||
### `cursor-style`
|
||||
|
||||
**Type**: String
|
||||
|
||||
`block`, `bar`, `underline`, `block_hollow`. Programs can override via DECSCUSR.
|
||||
|
||||
### `cursor-click-to-move`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Click to move cursor at prompts (requires shell integration). Default: `true`.
|
||||
|
||||
---
|
||||
|
||||
## Mouse
|
||||
|
||||
### `mouse-hide-while-typing`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Hide mouse when typing.
|
||||
|
||||
### `mouse-reporting`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Allow terminal applications to receive mouse events. Default: `true`. Toggle with `toggle_mouse_reporting` keybind.
|
||||
|
||||
---
|
||||
|
||||
## Scrolling
|
||||
|
||||
### `scroll-to-bottom`
|
||||
|
||||
**Type**: String (comma-separated)
|
||||
|
||||
When to auto-scroll: `keystroke` (default), `output`.
|
||||
|
||||
### `scrollback-limit`
|
||||
|
||||
**Type**: Integer (bytes)
|
||||
|
||||
Scrollback buffer size. Default: `10000000` (10 MB).
|
||||
|
||||
---
|
||||
|
||||
## Split Panes
|
||||
|
||||
### `unfocused-split-opacity`
|
||||
|
||||
**Type**: Number (0.15-1)
|
||||
|
||||
Opacity of unfocused split. Default: `0.7`. Minimum: `0.15`.
|
||||
|
||||
### `split-divider-color`
|
||||
|
||||
**Type**: Color (available since 1.1.0)
|
||||
|
||||
Color of split dividers.
|
||||
|
||||
---
|
||||
|
||||
## Shell Integration
|
||||
|
||||
### `shell-integration`
|
||||
|
||||
**Type**: String
|
||||
|
||||
`none`, `detect` (default), `bash`, `elvish`, `fish`, `nushell`, `zsh`. `detect` auto-detects by filename.
|
||||
|
||||
### `shell-integration-features`
|
||||
|
||||
**Type**: String (comma-separated)
|
||||
|
||||
Features: `cursor`, `sudo`, `title`, `ssh-env`, `ssh-terminfo`, `path`. Negate with `no-`.
|
||||
|
||||
---
|
||||
|
||||
## Environment & Command
|
||||
|
||||
### `command`
|
||||
|
||||
**Type**: String
|
||||
|
||||
Shell/command to run. Uses `/bin/sh -c` for argument expansion unless prefixed with `direct:` or `shell:`.
|
||||
|
||||
### `env`
|
||||
|
||||
**Type**: `KEY=VALUE` (repeatable, available since 1.2.0)
|
||||
|
||||
Extra environment variables. Set `env =` to reset all.
|
||||
|
||||
---
|
||||
|
||||
## Window Settings
|
||||
|
||||
### `maximize`
|
||||
|
||||
**Type**: Boolean (available since 1.1.0)
|
||||
|
||||
Start maximized. Default: `false`.
|
||||
|
||||
### `fullscreen`
|
||||
|
||||
**Type**: String
|
||||
|
||||
`false`, `true` (native), `non-native`, `non-native-visible-menu`, `non-native-padded-notch` (macOS only).
|
||||
|
||||
### `window-decoration`
|
||||
|
||||
**Type**: String or Boolean (available since 1.1.0)
|
||||
|
||||
`none`, `auto` (default), `client`, `server`. Booleans: `true` = `auto`, `false` = `none`.
|
||||
|
||||
### `window-padding-x` / `window-padding-y`
|
||||
|
||||
**Type**: Number or `X,Y`
|
||||
|
||||
Padding in points. Default: `2`.
|
||||
|
||||
---
|
||||
|
||||
## Clipboard
|
||||
|
||||
### `clipboard-read` / `clipboard-write`
|
||||
|
||||
**Type**: String
|
||||
|
||||
`ask`, `allow`, `deny`. Defaults: `ask` / `allow`.
|
||||
|
||||
### `clipboard-paste-protection`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Require confirmation before pasting potentially unsafe text. Default: `true`.
|
||||
|
||||
---
|
||||
|
||||
## Notifications & Bell
|
||||
|
||||
### `bell-features`
|
||||
|
||||
**Type**: String (comma-separated, available since 1.2.0)
|
||||
|
||||
Features: `system`, `audio`, `attention` (default), `title` (default), `border`. Negate with `no-`.
|
||||
|
||||
### `desktop-notifications`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Allow apps to show desktop notifications via escape sequences. Default: `true`.
|
||||
|
||||
---
|
||||
|
||||
## Custom Shaders
|
||||
|
||||
### `custom-shader`
|
||||
|
||||
**Type**: Path (repeatable)
|
||||
|
||||
GLSL shader file path. Compatible with Shadertoy. Receives uniforms: `iChannel0` (screen texture), `iResolution`, `iTime`, `iCursorColor`, `iPalette[256]`, and more.
|
||||
|
||||
### `custom-shader-animation`
|
||||
|
||||
**Type**: Boolean or `always`
|
||||
|
||||
Run animation loop even when unfocused: `always`.
|
||||
|
||||
---
|
||||
|
||||
## Keybindings
|
||||
|
||||
### Format
|
||||
|
||||
```ini
|
||||
keybind = trigger=action
|
||||
keybind = chain=action # chain with previous keybind
|
||||
```
|
||||
|
||||
**Modifiers**: `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command`
|
||||
|
||||
**Prefixes**: `all:`, `global:`, `unconsumed:`, `performable:`, `physical:`
|
||||
|
||||
### Key Tables (available since 1.3.0)
|
||||
|
||||
```ini
|
||||
keybind = foo/ctrl+a=new_window
|
||||
keybind = foo/ # define and clear table
|
||||
```
|
||||
|
||||
### Key Remap
|
||||
|
||||
```ini
|
||||
key-remap = ctrl=super
|
||||
key-remap = left_control=right_alt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VT/Compatibility
|
||||
|
||||
### `term`
|
||||
|
||||
**Type**: String
|
||||
|
||||
TERM environment variable. Default: `xterm-ghostty`.
|
||||
|
||||
### `async-backend`
|
||||
|
||||
**Type**: String (available since 1.2.0, Linux only)
|
||||
|
||||
`auto` (default), `epoll`, `io_uring`. macOS always uses `kqueue`.
|
||||
|
||||
---
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
### `confirm-close-surface`
|
||||
|
||||
**Type**: Boolean or `always`
|
||||
|
||||
Confirm before closing surface. Default: `true`.
|
||||
|
||||
### `focus-follows-mouse`
|
||||
|
||||
**Type**: Boolean
|
||||
|
||||
Auto-focus split under mouse. Default: `false`.
|
||||
|
||||
### `right-click-action`
|
||||
|
||||
**Type**: String
|
||||
|
||||
`context-menu` (default), `paste`, `copy`, `copy-or-paste`, `ignore`.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Default Keybindings
|
||||
|
||||
| Keybind | Action |
|
||||
|---------|--------|
|
||||
| `ctrl+shift+,` | `reload_config` |
|
||||
| `ctrl+,` | `open_config` |
|
||||
| `copy` | `copy_to_clipboard:mixed` |
|
||||
| `paste` | `paste_from_clipboard` |
|
||||
| `ctrl+shift+c` | `copy_to_clipboard:mixed` |
|
||||
| `ctrl+shift+v` | `paste_from_clipboard` |
|
||||
| `ctrl+=` / `ctrl++` | `increase_font_size:1` |
|
||||
| `ctrl+-` | `decrease_font_size:1` |
|
||||
| `ctrl+0` | `reset_font_size` |
|
||||
| `shift+PageUp` | `scroll_page_up` |
|
||||
| `shift+PageDown` | `scroll_page_down` |
|
||||
| `shift+Home` | `scroll_to_top` |
|
||||
| `shift+End` | `scroll_to_bottom` |
|
||||
| `ctrl+shift+Tab` | `previous_tab` |
|
||||
| `ctrl+Tab` | `next_tab` |
|
||||
| `ctrl+shift+n` | `new_window` |
|
||||
| `ctrl+shift+w` | `close_tab:this` |
|
||||
| `ctrl+shift+q` | `quit` |
|
||||
| `ctrl+shift+t` | `new_tab` |
|
||||
| `ctrl+shift+o` | `new_split:right` |
|
||||
| `ctrl+shift+e` | `new_split:down` |
|
||||
| `ctrl+shift+f` | `start_search` |
|
||||
| `Escape` | `end_search` |
|
||||
| `ctrl+shift+a` | `select_all` |
|
||||
| `alt+1`-`alt+9` | `goto_tab:1`-`goto_tab:9` |
|
||||
| `ctrl+Enter` | `toggle_fullscreen` |
|
||||
| `ctrl+shift+P` | `toggle_command_palette` |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Overview](index.md) for CLI actions and quick-start.
|
||||
- The [AGENTS.md Format](/core/agents-md-format.md) governs how agent behavior contracts reference this configuration.
|
||||
@@ -0,0 +1,124 @@
|
||||
# Ghostty Terminal — Overview
|
||||
|
||||
[Ghostty](https://ghostty.org) is a cross-platform, GPU-accelerated terminal emulator with an INI-style configuration system, Shadertoy-compatible custom shaders, and a rich CLI for introspection.
|
||||
|
||||
See [Configuration Reference](configuration.md) for the complete option catalog.
|
||||
|
||||
---
|
||||
|
||||
## CLI Actions
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `+version` / `--version` | Display Ghostty version |
|
||||
| `+list-fonts` | List all available fonts |
|
||||
| `+list-keybinds` | List all current/default keybinds |
|
||||
| `+list-themes` | List all available themes |
|
||||
| `+list-colors` | List all named RGB colors |
|
||||
| `+list-actions` | List all available keybind actions |
|
||||
| `+ssh-cache` | Manage SSH terminfo cache |
|
||||
| `+edit-config` | Open config file in $EDITOR/$VISUAL |
|
||||
| `+show-config` | Show current configuration |
|
||||
| `+show-config --default --docs` | Show all options with docs |
|
||||
| `+validate-config` | Validate a config file |
|
||||
| `+crash-report` | List existing crash reports |
|
||||
| `+new-window` | Open new window in running instance |
|
||||
|
||||
### Useful Flag Combinations
|
||||
|
||||
```bash
|
||||
# Show all config options with their docs as comments
|
||||
ghostty +show-config --default --docs
|
||||
|
||||
# List fonts with bold styles only
|
||||
ghostty +list-fonts --bold
|
||||
|
||||
# Validate your config without starting Ghostty
|
||||
ghostty +validate-config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration File Basics
|
||||
|
||||
Configuration uses INI-style syntax:
|
||||
|
||||
```ini
|
||||
option = value
|
||||
option = "quoted value with spaces"
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
- **Repeatable options**: `font-family`, `font-feature`, `palette`, `env`, `config-file`, `command-palette-entry`, `custom-shader` can all be repeated.
|
||||
- **Empty string resets**: Set `option = ""` to clear previously set values.
|
||||
- **Config includes**: Use `config-file = "path"` to include additional config files.
|
||||
- **Optional includes**: Prepend `?` to suppress errors if file does not exist, for example `config-file = "?optional.conf"`.
|
||||
- **CLI overrides**: CLI arguments automatically clear config file values for the same option.
|
||||
|
||||
### Special Prefixes for Commands
|
||||
|
||||
- `direct:` — Bypass shell expansion (no glob, tilde, or argument parsing)
|
||||
- `shell:` — Force shell wrapping
|
||||
|
||||
---
|
||||
|
||||
## Quick Configuration Examples
|
||||
|
||||
```ini
|
||||
# Font setup with fallback
|
||||
font-family = "JetBrains Mono"
|
||||
font-family = "Noto Sans Mono" # fallback for symbols
|
||||
font-size = 12
|
||||
|
||||
# Disable programming ligatures
|
||||
font-feature = -calt,-liga
|
||||
|
||||
# Cursor
|
||||
cursor-style = block
|
||||
cursor-style-blink = false
|
||||
|
||||
# Window padding
|
||||
window-padding-x = 2
|
||||
window-padding-y = 2
|
||||
|
||||
# Palette
|
||||
palette-generate = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Shaders
|
||||
|
||||
Ghostty supports Shadertoy-compatible GLSL shaders:
|
||||
|
||||
```ini
|
||||
custom-shader = ~/.config/ghostty/shaders/vignette.glsl
|
||||
custom-shader-animation = true
|
||||
```
|
||||
|
||||
Shaders receive uniforms for the terminal screen texture (`iChannel0`), cursor position, palette colors, and focus state.
|
||||
|
||||
---
|
||||
|
||||
## Default Keybindings
|
||||
|
||||
| Keybind | Action |
|
||||
|---------|--------|
|
||||
| `ctrl+shift+,` | `reload_config` |
|
||||
| `ctrl+` / `ctrl+=` | `increase_font_size:1` |
|
||||
| `ctrl+-` | `decrease_font_size:1` |
|
||||
| `ctrl+0` | `reset_font_size` |
|
||||
| `ctrl+shift+f` | `start_search` |
|
||||
| `ctrl+shift+a` | `select_all` |
|
||||
| `ctrl+Enter` | `toggle_fullscreen` |
|
||||
| `ctrl+shift+P` | `toggle_command_palette` |
|
||||
|
||||
See [Configuration Reference](configuration.md#appendix-default-keybindings) for the full table.
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Configuration Reference](configuration.md) for every option, organized by category.
|
||||
- The [AGENTS.md Format](../../core/agents-md-format.md) governs how agent behavior contracts reference this configuration.
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
type: reference
|
||||
title: Gitea Architecture
|
||||
description: Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw.
|
||||
tags:
|
||||
- gitea
|
||||
- architecture
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Gitea Architecture
|
||||
|
||||
Three quadlet-managed containers on a shared private Podman network (rootless, user `dank`). Gitea connects to PostgreSQL via network DNS. Caddy proxies HTTP/S to Gitea.
|
||||
|
||||
## Network Topology
|
||||
|
||||
```
|
||||
Client (HTTPS)
|
||||
↓
|
||||
caddy :80/:443 (auto-TLS via Let's Encrypt DNS-01/Porkbun)
|
||||
↓ reverse_proxy 192.168.0.143:3000 (published quadlet port)
|
||||
gitea-server :3000 (web UI, API)
|
||||
↓ PostgreSQL protocol
|
||||
gitea-postgres :5432 (internal only)
|
||||
```
|
||||
|
||||
## Network
|
||||
|
||||
The containers share the quadlet network `systemd-gitea` (file `gitea.network`, DNS enabled by default). Container names resolve via network DNS.
|
||||
|
||||
The automatic rootless `podman` default network has `dns_enabled: false`. Container names do not resolve there. Keep the Gitea stack on `systemd-gitea`.
|
||||
|
||||
## Container and Unit Names
|
||||
|
||||
| Container | Unit | Depends on |
|
||||
|---|---|---|
|
||||
| `gitea-postgres` | `gitea-postgres.service` | `gitea-network.service` |
|
||||
| `gitea-server` | `gitea-server.service` | `gitea-postgres.service` |
|
||||
|
||||
Podman 5.x names quadlet units after the file (`gitea-server.service`), with no `container-` prefix.
|
||||
|
||||
## Caddy Configuration
|
||||
|
||||
Caddy is a separate quadlet-managed service (`caddy.container`) on the shared `dankclaw_default` network. The live Caddyfile at `/home/dank/Containers/caddy/Caddyfile` proxies Gitea via the published quadlet port:
|
||||
|
||||
```
|
||||
gitea.franksdank.cloud {
|
||||
reverse_proxy 192.168.0.143:3000
|
||||
}
|
||||
```
|
||||
|
||||
- Caddy issues Let's Encrypt certs via DNS-01 (Porkbun module) — no inbound HTTP port needed.
|
||||
- Pi-hole quadlet resolves `gitea.franksdank.cloud` to `192.168.0.143` via `addn-hosts`.
|
||||
- Serves HTTP on port 80 and HTTPS on port 443, both bound to `0.0.0.0`.
|
||||
|
||||
## Gitea Configuration
|
||||
|
||||
Quadlet file: `~/.config/containers/systemd/gitea-server.container` (repo copy: `serverAppConfigs/dankclaw/gitea/quadlet/gitea-server.container`)
|
||||
|
||||
Key environment variables:
|
||||
- `DATABASE_TYPE=postgres`
|
||||
- `DATABASE_HOST=gitea-postgres` (network DNS)
|
||||
- `DATABASE_NAME=gitea`
|
||||
- `DATABASE_USER=gitea`
|
||||
- `DATABASE_PASSWD` from `/opt/gitea/.env` (mode 0600)
|
||||
- `USER_UID=1000`, `USER_GID=1000`
|
||||
|
||||
Gitea writes `/data/gitea/conf/app.ini` on first start (host: `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`). The `[database] HOST` and `PASSWD` lines in app.ini override the env vars. When you rename the database container, edit the `HOST` line in app.ini as well.
|
||||
|
||||
## Ports
|
||||
|
||||
| Service | Host Binding | Container Port | Access |
|
||||
|---|---|---|---|
|
||||
| Gitea HTTP | `0.0.0.0:3000` | 3000 | Web UI, API |
|
||||
| Gitea SSH | `0.0.0.0:2222` | 22 | Git clone/push via SSH |
|
||||
| PostgreSQL | `5432` (internal) | 5432 | Container-to-container only |
|
||||
|
||||
Note: the full-stack repo compose (`dankclaw/compose.yaml`) maps Gitea HTTP to host port 3001. The live stack uses 3000. Align before the full-stack deploy.
|
||||
|
||||
|
||||
`gitea.franksdank.cloud` resolves to `192.168.0.143` via the Pi-hole quadlet's `addn-hosts`. Caddy obtains Let's Encrypt certs via DNS-01 (Porkbun module), which requires no inbound port reachability. LAN clients reach Gitea via `http://dankclaw:3000` (published quadlet port).
|
||||
|
||||
## See Also
|
||||
|
||||
- ](index.md) — index with management commands
|
||||
- [[management|management]] — operations, boot persistence, incident
|
||||
- [[data-persistence|data-persistence]] — volumes and backups
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
type: reference
|
||||
title: Gitea Data Persistence
|
||||
description: Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw.
|
||||
tags:
|
||||
- gitea
|
||||
- data
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Gitea Data Persistence
|
||||
|
||||
All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Quadlet stops remove the container (`podman run --rm --replace`). The next start recreates it. Data survives.
|
||||
|
||||
## Volume Layout
|
||||
|
||||
| Host Path | Container Mount | Contents |
|
||||
|---|---|---|
|
||||
| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, avatars, attachments, LFS objects, `app.ini` |
|
||||
| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL WAL, tables, indexes |
|
||||
|
||||
## Ownership
|
||||
|
||||
The bind-mount directories are owned by host user `dank` (UID 1000). Files that the containers create are owned by host UID/GID **100999** — the rootless ID mapping of container uid/gid 1000 (dank subuid range 100000-165535). User `dank` cannot write those files directly from the host.
|
||||
|
||||
Edit container-owned files inside the container:
|
||||
|
||||
```
|
||||
podman exec --user 1000 gitea-server sed -i 's/old/new/' /data/gitea/conf/app.ini
|
||||
```
|
||||
|
||||
## Backup Strategy
|
||||
|
||||
### Full backup (recommended)
|
||||
|
||||
Tar the entire data directory. This captures Gitea repos and PostgreSQL data in one archive.
|
||||
|
||||
```
|
||||
tar czf gitea-backup-$(date +%F).tar.gz -C /opt/gitea data/
|
||||
```
|
||||
|
||||
### PostgreSQL-only backup
|
||||
|
||||
Use `pg_dump` for a portable SQL dump. Useful for restoring to a different PostgreSQL version.
|
||||
|
||||
```
|
||||
podman exec -e PGPASSWORD="$GITEA_DB_PASSWORD" gitea-postgres pg_dump -U gitea gitea > gitea-db-$(date +%F).sql
|
||||
```
|
||||
|
||||
Set `PGPASSWORD` from `/opt/gitea/.env` (mode 0600).
|
||||
|
||||
### Restore procedure
|
||||
|
||||
1. Stop the stack: `systemctl --user stop gitea-server gitea-postgres`
|
||||
2. Restore data: `tar xzf backup.tar.gz -C /opt/gitea/`
|
||||
3. Start the stack: `systemctl --user start gitea-postgres gitea-server`
|
||||
|
||||
## Data Growth
|
||||
|
||||
- Git repositories grow with each commit and push. Monitor with `du -sh /opt/gitea/data/gitea-gitea/git/repositories/`.
|
||||
- PostgreSQL WAL files accumulate. VACUUM via `podman exec gitea-postgres psql -U gitea -c "VACUUM;"`.
|
||||
- Gitea's log files grow with usage.
|
||||
|
||||
## See Also
|
||||
|
||||
- ](index.md) — index with management commands
|
||||
- [[management|management]] — operations and boot persistence
|
||||
- [[architecture|architecture]] — network and ports
|
||||
@@ -0,0 +1,65 @@
|
||||
# Gitea on dankclaw
|
||||
|
||||
Private Git hosting on dankclaw. Three quadlet-managed containers in the rootless podman session of user `dank`: Gitea, PostgreSQL, Caddy.
|
||||
|
||||
**Host:** dankclaw (71.227.227.172)
|
||||
**Config:** `~/.config/containers/systemd/gitea-{postgres,server,caddy}.container` + `gitea.network`
|
||||
**Local access:** `http://dankclaw:3000`
|
||||
**Domain:** `https://gitea.franksdank.cloud` (DNS pending)
|
||||
|
||||
## Architecture
|
||||
|
||||
| Container | Unit | Port | Purpose |
|
||||
|---|---|---|---|
|
||||
| `gitea-server` | `gitea-server.service` | 3000 (HTTP), 2222 (SSH) | Git web UI, API, SSH daemon |
|
||||
| `gitea-postgres` | `gitea-postgres.service` | 5432 (internal) | Database |
|
||||
| `gitea-caddy` | `gitea-caddy.service` | 80, 443 | Reverse proxy, auto-TLS |
|
||||
|
||||
The containers share the private network `systemd-gitea` (quadlet `gitea.network`, DNS enabled). The automatic `podman` default network has DNS disabled; do not run the stack on it.
|
||||
|
||||
## Management
|
||||
|
||||
All commands run as `dank` on dankclaw.
|
||||
|
||||
| Action | Command |
|
||||
|---|---|
|
||||
| Start all | `systemctl --user start gitea-postgres gitea-server gitea-caddy` |
|
||||
| Stop all | `systemctl --user stop gitea-caddy gitea-server gitea-postgres` |
|
||||
| Restart Gitea only | `systemctl --user restart gitea-server` |
|
||||
| Follow logs | `podman logs -f gitea-server` or `journalctl --user -u gitea-server -f` |
|
||||
| Check status | `systemctl --user status gitea-postgres gitea-server gitea-caddy` |
|
||||
|
||||
## Data Persistence
|
||||
|
||||
All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Stopping a quadlet unit removes its container; the next start recreates it. Volumes survive.
|
||||
|
||||
| Volume Path | Container Mount | Contents |
|
||||
|---|---|---|
|
||||
| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, app.ini, attachments |
|
||||
| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL data files |
|
||||
| `/opt/gitea/data/caddy/data/` | `/root/.local/share/caddy` | Caddy configuration, TLS certs |
|
||||
|
||||
See [[data-persistence|data-persistence]] for backup and restore.
|
||||
|
||||
## Boot Persistence
|
||||
|
||||
User-level linger is enabled for `dank`. The units start at host boot without a login. Each unit carries `[Install] WantedBy=default.target`; the podman generator applies it. The legacy podman-compose stack had no units and did not survive reboots (incident 2026-08-16).
|
||||
|
||||
See [[management|management]] for boot persistence details and troubleshooting.
|
||||
|
||||
## Repo Copies
|
||||
|
||||
The quadlet files, Caddyfile, and `.env.example` are tracked in the `serverAppConfigs` repo under `dankclaw/gitea/`. The live password lives only in `/opt/gitea/.env` on the host (mode 0600).
|
||||
|
||||
## See Also
|
||||
|
||||
- [[architecture|architecture]] — network topology and ports
|
||||
- [[management|management]] — operations, upgrades, backups, incident log
|
||||
- [[data-persistence|data-persistence]] — volumes and backup strategy
|
||||
- [[containers|containers]] — quadlet reference
|
||||
|
||||
* [Gitea Architecture](architecture.md) — Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw.
|
||||
|
||||
* [Gitea Data Persistence](data-persistence.md) — Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw.
|
||||
|
||||
* [Gitea Management](management.md) — Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
type: reference
|
||||
title: Gitea Management
|
||||
description: Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
|
||||
tags:
|
||||
- gitea
|
||||
- management
|
||||
- quadlet
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Gitea Management
|
||||
|
||||
All commands run as `dank` on dankclaw. The stack is quadlet-managed (since 2026-08-16). The legacy podman-compose file is retired to `/opt/gitea/.deprecated/`.
|
||||
|
||||
## Daily Operations
|
||||
|
||||
| Task | Command |
|
||||
|---|---|
|
||||
| Start all services | `systemctl --user start gitea-postgres gitea-server` |
|
||||
| Stop all services | `systemctl --user stop gitea-server gitea-postgres` |
|
||||
| Restart Gitea only | `systemctl --user restart gitea-server` |
|
||||
| Follow container logs | `podman logs -f gitea-server` |
|
||||
| Follow unit logs | `journalctl --user -u gitea-server -f` |
|
||||
| Check status | `systemctl --user status gitea-postgres gitea-server` |
|
||||
| Check health | `curl -s http://127.0.0.1:3000/api/v1/version` |
|
||||
|
||||
Start the stack in order (postgres, server). The unit dependencies enforce the order when you start a single unit, but starting all three explicitly avoids surprises.
|
||||
|
||||
## Boot Persistence
|
||||
|
||||
| Setting | Value | Check |
|
||||
|---|---|---|
|
||||
| Quadlet units | `~/.config/containers/systemd/gitea-{postgres,server}.container`, `gitea.network` | `systemctl --user list-units 'gitea*'` |
|
||||
| Boot enablement | `[Install] WantedBy=default.target` in each file | `systemctl --user is-enabled gitea-server` (reports `generated`) |
|
||||
| User linger | enabled for `dank` | `loginctl show-user dank \| grep Linger` |
|
||||
|
||||
At boot, systemd starts the user manager (linger), then `gitea-network.service`, then the containers in dependency order. No login session is required.
|
||||
|
||||
After editing a quadlet file: run `systemctl --user daemon-reload`, then restart the affected units.
|
||||
|
||||
## Config Files
|
||||
|
||||
| File | Path |
|
||||
|---|---|
|
||||
| Quadlet units | `~/.config/containers/systemd/gitea-*.container`, `gitea.network` |
|
||||
| Secrets | `/opt/gitea/.env` (mode 0600, `GITEA_DB_PASSWORD`) |
|
||||
| Gitea app config | `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini` (container-owned, UID 100999) |
|
||||
|
||||
Repo copies: `serverAppConfigs/dankclaw/gitea/` (quadlet files, `.env.example`). Copy edits to the target, then `daemon-reload` + restart.
|
||||
|
||||
## Upgrades
|
||||
|
||||
1. Pull latest images: `podman pull docker.io/gitea/gitea:latest` (repeat per image)
|
||||
2. Restart the stack: `systemctl --user stop gitea-server gitea-postgres && systemctl --user start gitea-postgres gitea-server`
|
||||
3. Verify startup: `podman logs -f gitea-server`
|
||||
|
||||
Gitea handles database migrations automatically on startup. PostgreSQL version bumps require editing the image tag in `gitea-postgres.container`, then a dump/restore of the data (a fresh PostgreSQL does not read the old data directory format blindly).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Gitea cannot reach the database
|
||||
|
||||
Check the `[database] HOST` line in `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`. It must be `gitea-postgres:5432`. app.ini overrides the `DATABASE_HOST` env var.
|
||||
|
||||
Then check name resolution from the container:
|
||||
|
||||
```
|
||||
podman exec gitea-server getent hosts gitea-postgres
|
||||
```
|
||||
|
||||
If it fails, the containers are not on the `systemd-gitea` network. Check `podman inspect gitea-server --format '{{.NetworkSettings.Networks}}'`.
|
||||
|
||||
### Files in the data directory are not writable
|
||||
|
||||
Container-created files are owned by host UID 100999 (rootless ID mapping of container uid 1000). Edit them inside the container:
|
||||
|
||||
```
|
||||
podman exec --user 1000 gitea-server vi /data/gitea/conf/app.ini
|
||||
```
|
||||
|
||||
### Caddy 502s
|
||||
|
||||
The upstream `gitea-server:3000` is down or unresolvable. Start `gitea-server`, check its logs, and verify `/home/dank/Containers/caddy/Caddyfile` references `192.168.0.143:3000`.
|
||||
|
||||
### Container names do not resolve
|
||||
|
||||
The automatic rootless `podman` network has DNS disabled. Run the stack on `systemd-gitea` (see `gitea.network`). If the network state goes stale after a reboot, restart the stack; recreate the network only if restarts do not help.
|
||||
|
||||
## Incident Log
|
||||
|
||||
### 2026-08-16: down for ~1 hour after unattended reboot
|
||||
|
||||
`unattended-upgrades` rebooted dankclaw at 15:01. The legacy podman-compose stack had no systemd units. Rootless podman does not auto-start containers at boot without units. Gitea stayed down until a manual start at 16:02.
|
||||
|
||||
Fix: migrated the stack to quadlet units with `[Install] WantedBy=default.target` and enabled user-level linger. Also fixed two latent bugs found during the migration: the live Caddyfile upstream name (`server` → `192.168.0.143:3000`) and the stale `HOST = postgres:5432` line in app.ini (→ `gitea-postgres:5432`).
|
||||
|
||||
Verify the fix on the next host reboot.
|
||||
|
||||
## See Also
|
||||
|
||||
- ](index.md) — index
|
||||
- [[architecture|architecture]] — network topology
|
||||
- [[data-persistence|data-persistence]] — backups
|
||||
- [[containers|containers]] — quadlet reference
|
||||
@@ -0,0 +1,39 @@
|
||||
# Tool Documentation
|
||||
|
||||
Configuration guides and reference material for installed software. Each tool has its own directory with an `index.md` entry point.
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
* [[cachyos|cachyos]] — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware.
|
||||
* [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed.
|
||||
* [[applications|applications]] — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
* ](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
|
||||
* ](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
|
||||
* ](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API.
|
||||
* [[linux-power-management|linux-power-management]] — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
* [[noctalia-shell|noctalia-shell]] — Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls.
|
||||
* [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for dankware.
|
||||
* [npx Skills](npx-skills/index.md) — Distribution and installation tips for pi skill packages on npm, ecosystem overview, and skill specification.
|
||||
* [ornith-llama-cpp-setup](ornith-llama-cpp-setup/index.md) — Setup and reference for running Ornith MoE models with llama.cpp server for local inference.
|
||||
* [[tmux|tmux]] — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
* ](vercel-labs-skills/index.md) — Complete list of 68+ supported coding agents, their --agent flags, installation paths, and the SKILL.md specification.
|
||||
|
||||
## Adding a New Tool
|
||||
|
||||
1. Create a directory: `tools/<tool-name>/`
|
||||
2. Add `index.md` as the entry point (no frontmatter for directory listings)
|
||||
3. Create concept files with frontmatter if content exceeds one file
|
||||
4. Update this index
|
||||
5. Log the change in `log.md`
|
||||
|
||||
* [Default Applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
|
||||
* [CachyOS](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware.
|
||||
|
||||
* [Linux Power Management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
|
||||
* [Noctalia Shell](noctalia-shell.md) — Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls.
|
||||
|
||||
* [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
@@ -0,0 +1,301 @@
|
||||
---
|
||||
type: reference
|
||||
title: Linux Power Management
|
||||
description: Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems.
|
||||
tags:
|
||||
- power-management
|
||||
- sleep
|
||||
- nvidia
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
Comprehensive guide to sleep/wake configuration and diagnostics on Linux systems. Covers systemd sleep, kernel states, NVIDIA GPU power management, and diagnostic tools.
|
||||
|
||||
---
|
||||
|
||||
## Systemd Sleep Configuration
|
||||
|
||||
### logind.conf (`/etc/systemd/logind.conf`)
|
||||
|
||||
Controls login manager behavior around sleep:
|
||||
|
||||
```ini
|
||||
[Login]
|
||||
HandlePowerKey=poweroff
|
||||
HandleSleepKey=suspend
|
||||
HandleHibernateKey=hibernate
|
||||
HandleLidSwitch=suspend
|
||||
HandleLidSwitchDocked=ignore
|
||||
HoldoffTimeoutSec=5s
|
||||
IdleAction=hibernate
|
||||
IdleActionSec=30min
|
||||
```
|
||||
|
||||
**Key setting**: `HoldoffTimeoutSec` — increase if sleep triggers are too aggressive.
|
||||
|
||||
### sleep.conf (`/etc/systemd/sleep.conf`)
|
||||
|
||||
Controls the actual sleep behavior:
|
||||
|
||||
```ini
|
||||
[Sleep]
|
||||
AllowSuspend=yes
|
||||
AllowHibernation=yes
|
||||
AllowHybridSleep=yes
|
||||
HibernateMode=platform+shutdown
|
||||
HibernateDelaySec=1800
|
||||
```
|
||||
|
||||
**HibernateMode options**:
|
||||
- `platform` — ACPI platform sleep (faster, firmware-dependent)
|
||||
- `shutdown` — classic shutdown-to-disk (slower, more compatible)
|
||||
- `shutdown+platform` — try platform first, fall back to shutdown
|
||||
|
||||
### Suspend-Then-Hibernate Flow
|
||||
|
||||
```
|
||||
Suspend (RAM) --timeout--> Hibernate (disk)
|
||||
|
|
||||
+-- wake event --> Resume
|
||||
```
|
||||
|
||||
### Custom Sleep Hooks
|
||||
|
||||
Create `/etc/systemd/system-sleep/` scripts for pre/post sleep actions:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /etc/systemd/system-sleep/hook
|
||||
case "$1" in
|
||||
pre) echo "Suspending..." ;;
|
||||
post) echo "Resumed!" ;;
|
||||
esac
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Kernel Sleep States
|
||||
|
||||
### ACPI Sleep States
|
||||
|
||||
| State | Name | Power | Wake Time | Description |
|
||||
|-------|------|-------|-----------|-------------|
|
||||
| S0 | Working | Full | Instant | System is running |
|
||||
| S1 | Sleep (halted) | ~10-20W | <1s | CPU halted, RAM refresh |
|
||||
| S2 | Sleep | ~5-10W | ~1s | CPU cache flushed |
|
||||
| **S3** | **Sleeping Standby** | **~1-5W** | **~1-2s** | **RAM retained, most power off** |
|
||||
| S4 | Hibernate | 0W | ~10-30s | RAM written to disk |
|
||||
| **S5** | **Soft Off** | **0W** | **~5-10s** | **Powered off but can wake** |
|
||||
|
||||
### Modern ACPI Sleep States (s2idle)
|
||||
|
||||
Modern laptops often **only support s2idle** (S0 idle):
|
||||
|
||||
```bash
|
||||
$ cat /sys/power/mem_sleep
|
||||
[s2idle] deep
|
||||
```
|
||||
|
||||
| Mode | Name | Power | Characteristics |
|
||||
|------|------|-------|----------------|
|
||||
| **s2idle** | "Suspend to Idle" | 3-8W | Shallow, firmware-managed, fast wake, higher drain |
|
||||
| **deep** | S3 | 1-3W | Deeper sleep, slower wake, better battery |
|
||||
|
||||
### Setting Default Sleep State
|
||||
|
||||
Add to kernel command line (GRUB or systemd-boot):
|
||||
|
||||
```
|
||||
mem_sleep_default=deep # Prefer S3 deep sleep
|
||||
mem_sleep_default=s2idle # Force s2idle
|
||||
```
|
||||
|
||||
**For GRUB:** Edit `/etc/default/grub`, add to `GRUB_CMDLINE_LINUX_DEFAULT`:
|
||||
```
|
||||
GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NVIDIA GPU Power Management
|
||||
|
||||
### Enable NVIDIA Suspend Support
|
||||
|
||||
```bash
|
||||
sudo systemctl enable nvidia-suspend.service
|
||||
sudo systemctl enable nvidia-suspend-then-hibernate.service
|
||||
sudo systemctl enable nvidia-hibernate.service
|
||||
```
|
||||
|
||||
### NVIDIA Module Parameters
|
||||
|
||||
Edit `/etc/modprobe.d/nvidia.conf`:
|
||||
|
||||
```
|
||||
options nvidia NVreg_PreserveVideoMemoryAllocations=1
|
||||
options nvidia NVreg_EnableS0ixPowerManagement=1
|
||||
```
|
||||
|
||||
### Check NVIDIA GPU State
|
||||
|
||||
```bash
|
||||
# Is the NVIDIA GPU active?
|
||||
lspci -vnn | grep -A 12 -i "vga"
|
||||
|
||||
# Force NVIDIA GPU to D3hot (fully off) before suspend
|
||||
sudo tee /sys/bus/pci/devices/0000:01:00.0/power/control <<< auto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Tools
|
||||
|
||||
### journalctl
|
||||
|
||||
```bash
|
||||
# All sleep-related events in the last boot
|
||||
journalctl -b -0 | grep -iE 'suspend|resume|sleep|wake|acpi'
|
||||
|
||||
# Real-time monitoring during a suspend attempt
|
||||
journalctl -f &
|
||||
systemctl suspend
|
||||
# Wait for failure, then Ctrl+C
|
||||
```
|
||||
|
||||
### powertop
|
||||
|
||||
```bash
|
||||
sudo powertop # Interactive view
|
||||
sudo powertop --calibrate # One-time setup
|
||||
sudo powertop --auto-tune # Apply recommendations
|
||||
sudo powertop --html=/tmp/report.html --csv=/tmp/report.csv
|
||||
```
|
||||
|
||||
### tlp — Advanced Power Management
|
||||
|
||||
```bash
|
||||
sudo pacman -S tlp tlp-rdw # Arch
|
||||
sudo apt install tlp # Debian/Ubuntu
|
||||
sudo systemctl enable --now tlp
|
||||
sudo tlp-stat
|
||||
```
|
||||
|
||||
### dmesg
|
||||
|
||||
```bash
|
||||
dmesg | grep -iE 'suspend|resume|acpi|pm_'
|
||||
dmesg -wH # Watch mode, human-readable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Wake Source Management
|
||||
|
||||
### Checking Wake Sources
|
||||
|
||||
```bash
|
||||
# What can wake the system?
|
||||
cat /proc/acpi/wakeup | grep enabled
|
||||
|
||||
# What woke the system last time?
|
||||
journalctl -b -1 | grep -iE 'PM: wakeup|wakeup source|acpi: wakeup'
|
||||
```
|
||||
|
||||
### Toggling Wake Sources
|
||||
|
||||
```bash
|
||||
# Toggle a device's wake capability
|
||||
echo XHCI | sudo tee /proc/acpi/wakeup
|
||||
echo RP01 | sudo tee /proc/acpi/wakeup
|
||||
```
|
||||
|
||||
### Persistent Wake Source Configuration
|
||||
|
||||
Create a systemd service:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/config-wake-sources.service
|
||||
[Unit]
|
||||
Description=Configure ACPI wake sources
|
||||
Before=sleep.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/bin/bash -c 'echo XHCI > /proc/acpi/wakeup'
|
||||
RemainAfterExit=yes
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Kernel Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `mem_sleep_default=deep` | Prefer S3 deep sleep |
|
||||
| `pcie_aspm=force` | Force ASPM (aggressive power saving) |
|
||||
| `pcie_aspm.policy=performance` | Disable ASPM (fixes some issues) |
|
||||
| `acpi_osi=!` | Hide OS identity from ACPI |
|
||||
| `usbcore.autosuspend=-1` | Disable USB autosuspend |
|
||||
|
||||
---
|
||||
|
||||
## Testing Sleep Modes
|
||||
|
||||
```bash
|
||||
# Suspend to RAM
|
||||
systemctl suspend
|
||||
|
||||
# Hibernate to disk
|
||||
systemctl hibernate
|
||||
|
||||
# Suspend then hibernate
|
||||
systemctl suspend-then-hibernate
|
||||
|
||||
# Freeze (CPUs idle, RAM on)
|
||||
systemctl freeze
|
||||
```
|
||||
|
||||
### Automated Stress Test
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
for i in $(seq 1 10); do
|
||||
echo "=== Cycle $i ==="
|
||||
date
|
||||
echo mem | sudo tee /sys/power/state 2>/dev/null || systemctl suspend
|
||||
echo "Resume $i: SUCCESS"
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Action Items
|
||||
|
||||
```bash
|
||||
# 1. Enable NVIDIA suspend support
|
||||
sudo systemctl enable nvidia-suspend.service
|
||||
sudo systemctl enable nvidia-suspend-then-hibernate.service
|
||||
|
||||
# 2. Add NVIDIA power management module parameter
|
||||
echo 'options nvidia NVreg_PreserveVideoMemoryAllocations=1' | sudo tee /etc/modprobe.d/nvidia-preserve.conf
|
||||
|
||||
# 3. Reboot
|
||||
sudo reboot
|
||||
|
||||
# 4. Test suspend
|
||||
systemctl suspend
|
||||
|
||||
# 5. After resume, check for errors
|
||||
dmesg | tail -30
|
||||
journalctl -b -0 | grep -iE 'error|fail|nvidia' | tail -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- The [AGENTS.md Format](../core/agents-md-format.md) defines the system-level instruction contract that governs how agent sessions configure these systems.
|
||||
@@ -0,0 +1,155 @@
|
||||
# llama.cpp Server — Overview
|
||||
|
||||
[llama.cpp](https://github.com/ggml-org/llama.cpp) is a pure C/C++ LLM inference library. The `llama-server` binary is a lightweight, OpenAI-compatible HTTP server for serving GGUF models via REST API.
|
||||
|
||||
See [Setup Guide](setup.md) for build instructions (CPU/CUDA/Metal/Vulkan), Docker, and systemd deployment.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
- OpenAI API-compatible chat completions, completions, and embeddings
|
||||
- Anthropic Messages API-compatible chat completions
|
||||
- Parallel decoding with multi-user support and continuous batching
|
||||
- Multimodal (vision/audio) support
|
||||
- Speculative decoding with draft models
|
||||
- Schema-constrained JSON output and function calling
|
||||
- Built-in Web UI
|
||||
- Prometheus metrics
|
||||
- Router mode for multi-model deployment
|
||||
|
||||
---
|
||||
|
||||
## GGUF Model Format
|
||||
|
||||
**GGUF** (GGML Universal File) is the binary model file format used by llama.cpp.
|
||||
|
||||
### Quantization Methods
|
||||
|
||||
| Method | Bits/weight | 8B model size | Quality |
|
||||
|--------|------------|---------------|---------|
|
||||
| Q4_K_M | 4.9 | 4.58 GB | **Good (recommended default)** |
|
||||
| Q5_K_M | 5.7 | 5.33 GB | High |
|
||||
| Q6_K | 6.6 | 6.14 GB | Very High |
|
||||
| Q8_0 | 8.5 | 7.95 GB | Near-lossless |
|
||||
| F16 | 16.0 | 14.96 GB | Full precision |
|
||||
|
||||
**Q4_K_M is the recommended default** — best balance of quality and size.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Serve a local model on default port 8080
|
||||
llama-server -m /path/to/model.gguf
|
||||
|
||||
# From Hugging Face (auto-downloads)
|
||||
llama-server -hf ggml-org/gemma-3-1b-it-GGUF
|
||||
```
|
||||
|
||||
**Defaults**: Listens on `127.0.0.1:8080`. Single slot (one concurrent request).
|
||||
|
||||
> **System note:** On this network the Pi inference hosts do not use the default port. Pi serves `frank-default-small` (dankserver) and `frank-default-large` (dankclaw), each on port `7770`. The local Ornith host runs on port `8080`. See [Pi Models Configuration](../../pi/models.md).
|
||||
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
# 200: {"status": "ok"}
|
||||
# 503: {"error": {"code": 503, "message": "Loading model"}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Chat Completions (OpenAI-compatible)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer no-key" \
|
||||
-d '{
|
||||
"model": "gpt-3.5-turbo",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Write a limerick about Python"}
|
||||
],
|
||||
"max_tokens": 256,
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Other Endpoints
|
||||
|
||||
```bash
|
||||
# Completions
|
||||
curl http://localhost:8080/v1/completions
|
||||
|
||||
# Embeddings
|
||||
curl http://localhost:8080/v1/embeddings
|
||||
|
||||
# Native completion
|
||||
curl -X POST http://localhost:8080/completion -d '{"prompt": "Hello", "n_predict": 64}'
|
||||
|
||||
# Anthropic-compatible
|
||||
curl http://localhost:8080/v1/messages
|
||||
|
||||
# Monitoring
|
||||
curl http://localhost:8080/props
|
||||
curl http://localhost:8080/slots
|
||||
curl http://localhost:8080/metrics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Python Client
|
||||
|
||||
```python
|
||||
import openai
|
||||
client = openai.OpenAI(
|
||||
base_url="http://localhost:8080/v1",
|
||||
api_key="sk-no-key-required"
|
||||
)
|
||||
completion = client.chat.completions.create(
|
||||
model="gpt-3.5-turbo",
|
||||
messages=[{"role": "user", "content": "What is the meaning of life?"}],
|
||||
max_tokens=256
|
||||
)
|
||||
print(completion.choices[0].message.content)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker
|
||||
|
||||
```bash
|
||||
docker run -p 8080:8080 -v /models:/models \
|
||||
ghcr.io/ggml-org/llama.cpp:server \
|
||||
-m /models/model.gguf --host 0.0.0.0 --port 8080
|
||||
|
||||
# CUDA variant
|
||||
docker run -p 8080:8080 --gpus all \
|
||||
ghcr.io/ggml-org/llama.cpp:server-cuda \
|
||||
-m /models/model.gguf --n-gpu-layers 99
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All CLI options can be set via `LLAMA_ARG_` prefix:
|
||||
|
||||
```bash
|
||||
LLAMA_ARG_MODEL=/models/model.gguf LLAMA_ARG_CTX_SIZE=8192 llama-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Setup Guide](setup.md) for build instructions, GPU offloading, and deployment.
|
||||
- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for running Ornith models.
|
||||
@@ -0,0 +1,266 @@
|
||||
---
|
||||
type: howto
|
||||
title: llama.cpp — Build and Deployment Setup
|
||||
description: Build guides for CPU, CUDA, Metal, Vulkan, and other GPU backends, plus Docker Compose and systemd service configuration.
|
||||
tags:
|
||||
- llm
|
||||
- inference
|
||||
- llama-cpp
|
||||
- build
|
||||
- deployment
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# llama.cpp — Build and Deployment Setup
|
||||
|
||||
See [Overview](index.md) for server usage and API reference.
|
||||
|
||||
---
|
||||
|
||||
## Building llama.cpp
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Git
|
||||
- CMake (3.12+)
|
||||
- C++ compiler (GCC 9+, Clang 12+, MSVC 2019+)
|
||||
|
||||
### CPU-only Build
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ggml-org/llama.cpp
|
||||
cd llama.cpp
|
||||
|
||||
cmake -B build
|
||||
cmake --build build --config Release -j 8
|
||||
```
|
||||
|
||||
The `llama-server` binary will be at `./build/bin/llama-server`.
|
||||
|
||||
**Faster compilation:**
|
||||
- Use Ninja: `cmake -B build -G Ninja`
|
||||
- Install `ccache` for incremental builds
|
||||
|
||||
**Debug build:**
|
||||
```bash
|
||||
cmake -B build -DCMAKE_BUILD_TYPE=Debug
|
||||
cmake --build build
|
||||
```
|
||||
|
||||
### CUDA Build (NVIDIA GPU)
|
||||
|
||||
```bash
|
||||
# Requires CUDA toolkit installed
|
||||
cmake -B build -DGGML_CUDA=ON
|
||||
cmake --build build --config Release -j 8
|
||||
```
|
||||
|
||||
**Non-native build (works on all CUDA GPUs):**
|
||||
```bash
|
||||
cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=OFF
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
**Override compute capabilities:**
|
||||
```bash
|
||||
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86;89"
|
||||
```
|
||||
|
||||
### Metal Build (Apple Silicon)
|
||||
|
||||
Metal is enabled by default on macOS. No special flags needed:
|
||||
|
||||
```bash
|
||||
cmake -B build
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
Disable GPU offloading at runtime with `--n-gpu-layers 0`.
|
||||
|
||||
### Other GPU Backends
|
||||
|
||||
| Backend | Flag | Platform |
|
||||
|---------|------|----------|
|
||||
| HIP/ROCm (AMD GPU) | `-DGGML_HIP=ON` | Linux |
|
||||
| Vulkan | `-DGGML_VULKAN=ON` | All |
|
||||
| SYCL (Intel GPU) | `-DGGML_SYCL=ON` | Linux |
|
||||
| CANN (Ascend NPU) | `-DGGML_CANN=ON` | Linux |
|
||||
| OpenVINO | `-DGGML_OPENVINO=ON` | Intel |
|
||||
| ZenDNN (AMD CPU) | `-DGGML_ZENDNN=ON` | Linux |
|
||||
| WebGPU | `-DGGML_WEBGPU=ON` | All (WASM) |
|
||||
|
||||
### SSL/TLS Support
|
||||
|
||||
```bash
|
||||
# Requires OpenSSL dev libraries
|
||||
cmake -B build -DLLAMA_OPENSSL=ON
|
||||
cmake --build build --config Release -t llama-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Command-Line Options
|
||||
|
||||
### Model Loading
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-m, --model FNAME` | Path to GGUF model file | required |
|
||||
| `-hf, --hf-repo USER/MODEL` | Download from Hugging Face | — |
|
||||
| `-mmproj FILE` | Multimodal projector file | — |
|
||||
| `-lora FNAME` | LoRA adapter (repeatable) | — |
|
||||
| `-ngl, --gpu-layers N` | Layers to offload to GPU | auto |
|
||||
|
||||
### Context & Performance
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-c, --ctx-size N` | Prompt context size | 0 (from model) |
|
||||
| `-t, --threads N` | CPU threads | -1 (all) |
|
||||
| `-b, --batch-size N` | Max logical batch size | 2048 |
|
||||
| `--flash-attn` | Flash Attention | auto |
|
||||
| `--mlock` | Keep model in RAM (no swap) | false |
|
||||
| `--mmap` | Memory-map model file | true |
|
||||
| `--fit` | Auto-fit to GPU memory | on |
|
||||
|
||||
### Server Configuration
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--host HOST` | Bind address | 127.0.0.1 |
|
||||
| `--port PORT` | Port number | 8080 |
|
||||
| `-np, --parallel N` | Concurrent slots | -1 (auto) |
|
||||
| `--api-key KEY` | API key (repeatable) | none |
|
||||
| `--metrics` | Prometheus metrics | disabled |
|
||||
| `--jinja` | Jinja template engine | enabled |
|
||||
|
||||
### Sampling Parameters
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-s, --seed N` | RNG seed | -1 (random) |
|
||||
| `--temp, --temperature N` | Temperature | 0.80 |
|
||||
| `--top-k N` | Top-k sampling | 40 |
|
||||
| `--top-p N` | Top-p sampling | 0.95 |
|
||||
| `--min-p N` | Min-p sampling | 0.05 |
|
||||
| `--repeat-penalty N` | Repetition penalty | 1.1 |
|
||||
|
||||
---
|
||||
|
||||
## GPU Offloading
|
||||
|
||||
```bash
|
||||
# Offload all layers to GPU
|
||||
llama-server -m model.gguf --n-gpu-layers 99
|
||||
|
||||
# Auto-detect (default)
|
||||
llama-server -m model.gguf --n-gpu-layers auto
|
||||
|
||||
# Disable GPU (CPU-only)
|
||||
llama-server -m model.gguf --n-gpu-layers 0
|
||||
|
||||
# Multi-GPU (layer mode)
|
||||
llama-server -m model.gguf --device 0,1 --split-mode layer
|
||||
|
||||
# Multi-GPU (row split)
|
||||
llama-server -m model.gguf --device 0,1 --split-mode row
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Length
|
||||
|
||||
```bash
|
||||
# Use model's native context
|
||||
llama-server -m model.gguf -c 0
|
||||
|
||||
# Set specific context
|
||||
llama-server -m model.gguf -c 8192
|
||||
|
||||
# RoPE scaling to extend beyond trained size
|
||||
llama-server -m model.gguf -c 65536 --rope-scale 2
|
||||
|
||||
# YaRN scaling
|
||||
llama-server -m model.gguf -c 65536 --rope-scaling yarn --yarn-orig-ctx 8192
|
||||
```
|
||||
|
||||
**Important**: Larger context = more VRAM/RAM usage (KV cache grows linearly). Reduce with quantization:
|
||||
|
||||
```bash
|
||||
llama-server -m model.gguf -c 32768 \
|
||||
--cache-type-k q4_0 --cache-type-v q4_0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Speculative Decoding
|
||||
|
||||
```bash
|
||||
# Draft model based
|
||||
llama-server -m main_model.gguf -md draft_model.gguf
|
||||
|
||||
# N-gram based (no draft model needed)
|
||||
llama-server -m model.gguf --spec-type ngram-mod --spec-ngram-mod-n-max 64
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Compose Example
|
||||
|
||||
```yaml
|
||||
services:
|
||||
llamacpp-server:
|
||||
image: ghcr.io/ggml-org/llama.cpp:server-cuda
|
||||
ports:
|
||||
- 8080:8080
|
||||
volumes:
|
||||
- ./models:/models
|
||||
environment:
|
||||
LLAMA_ARG_MODEL: /models/my_model.gguf
|
||||
LLAMA_ARG_CTX_SIZE: 8192
|
||||
LLAMA_ARG_N_PARALLEL: 2
|
||||
LLAMA_ARG_PORT: 8080
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- driver: nvidia
|
||||
count: 1
|
||||
capabilities: [gpu]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running as systemd Service
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/llama-server.service
|
||||
[Unit]
|
||||
Description=llama.cpp Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=dank
|
||||
ExecStart=/home/dank/GitPackages/llama.cpp/build/bin/llama-server \
|
||||
-m /home/dank/models/my_model.gguf -c 131072 -ngl 12 \
|
||||
--host 0.0.0.0 --port 8080
|
||||
Restart=on-failure
|
||||
WorkingDirectory=/home/dank/GitPackages/llama.cpp
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable llama-server
|
||||
sudo systemctl start llama-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- See [Overview](index.md) for API reference and usage examples.
|
||||
- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for model-specific configuration.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
type: reference
|
||||
title: Niri Action Reference
|
||||
description: Complete reference of all available niri actions — window operations, focus, movement, spawning, and system actions.
|
||||
tags:
|
||||
- niri
|
||||
- actions
|
||||
- reference
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Action Reference
|
||||
|
||||
## Window/Column Actions
|
||||
|
||||
- `close-window` — Close focused window
|
||||
- `toggle-window-floating` — Toggle floating/tiling
|
||||
- `maximize-column` — Maximize column with gaps
|
||||
- `maximize-window-to-edges` — Maximize without gaps
|
||||
- `expand-column-to-available-width` — Fill remaining space
|
||||
- `center-column` — Center focused column
|
||||
- `center-visible-columns` — Center all visible columns
|
||||
- `switch-preset-column-width` — Cycle preset widths
|
||||
- `switch-preset-column-width-back` — Cycle backwards
|
||||
- `switch-preset-window-height` — Cycle preset heights
|
||||
- `reset-window-height` — Reset height
|
||||
- `toggle-column-tabbed-display` — Toggle vertical tabs mode
|
||||
- `consume-or-expel-window-left/right` — Consume/expel window
|
||||
- `consume-window-into-column` — Consume window into column
|
||||
- `expel-window-from-column` — Expel window from column
|
||||
- `set-column-width "-10%"` / `set-column-width "+10%"` — Fine width adjustment
|
||||
- `set-window-height "-10%"` / `set-window-height "+10%"` — Fine height adjustment
|
||||
|
||||
## Focus Actions
|
||||
|
||||
- `focus-column-left/right` — Focus adjacent column
|
||||
- `focus-window-up/down` — Focus window within column
|
||||
- `focus-column-first/last` — Focus first/last column
|
||||
- `focus-workspace N` — Focus workspace N
|
||||
- `focus-workspace-down/up` — Focus next/previous workspace
|
||||
- `focus-workspace-previous` — Focus previously active workspace
|
||||
- `focus-monitor-left/right/up/down` — Focus adjacent monitor
|
||||
|
||||
## Move Actions
|
||||
|
||||
- `move-column-left/right` — Move column left/right
|
||||
- `move-window-up/down` — Move window within column
|
||||
- `move-column-to-first/last` — Move column to edge
|
||||
- `move-column-to-workspace-down/up` — Move column to adjacent workspace
|
||||
- `move-column-to-workspace N` — Move column to workspace N
|
||||
- `move-column-to-monitor-left/right/up/down` — Move column to adjacent monitor
|
||||
|
||||
## Other Actions
|
||||
|
||||
- `spawn "program"` — Run program (no shell expansion)
|
||||
- `spawn-sh "command"` — Run command through shell
|
||||
- `spawn-at-startup "program"` — Run at startup
|
||||
- `quit` — Quit compositor (with confirmation)
|
||||
- `show-hotkey-overlay` — Show keybind cheat sheet
|
||||
- `toggle-overview` — Toggle overview
|
||||
- `screenshot` — Interactive screenshot
|
||||
- `screenshot-screen` — Screenshot monitor
|
||||
- `screenshot-window` — Screenshot window
|
||||
- `power-off-monitors` — Turn off displays
|
||||
- `toggle-keyboard-shortcuts-inhibit` — Toggle inhibitor
|
||||
- `do-screen-transition` — Smooth screen transition (for theme switching)
|
||||
|
||||
## Related
|
||||
|
||||
* [Default Bindings](/tools/niri/default-bindings.md) — Default key bindings that invoke these actions
|
||||
* [Tips](/tools/niri/tips.md) — Programmatic invocation and other tips
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
type: reference
|
||||
title: Niri Default Key Bindings
|
||||
description: Complete table of all default key bindings organized by category — window management, navigation, workspaces, media keys, etc.
|
||||
tags:
|
||||
- niri
|
||||
- keybindings
|
||||
- reference
|
||||
- unverified
|
||||
---
|
||||
|
||||
# Default Key Bindings
|
||||
|
||||
## Application Launching
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+T` | Open terminal (alacritty) |
|
||||
| `Mod+D` | Run application launcher (fuzzel) |
|
||||
| `Super+Alt+L` | Lock screen (swaylock) |
|
||||
| `Super+Alt+S` | Toggle screen reader (orca) |
|
||||
|
||||
## Window Management
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Q` | Close window |
|
||||
| `Mod+F` | Maximize column (with gaps) |
|
||||
| `Mod+Shift+F` | Fullscreen window |
|
||||
| `Mod+M` | Maximize window to edges (like double-click titlebar) |
|
||||
| `Mod+Ctrl+F` | Expand column to fill remaining space |
|
||||
| `Mod+V` | Toggle window floating |
|
||||
| `Mod+Shift+V` | Switch focus between floating and tiling |
|
||||
| `Mod+W` | Toggle column tabbed display mode |
|
||||
| `Mod+BracketLeft` | Consume/expel window left |
|
||||
| `Mod+BracketRight` | Consume/expel window right |
|
||||
| `Mod+Comma` | Consume window into column |
|
||||
| `Mod+Period` | Expel window from column |
|
||||
|
||||
## Column Navigation
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Left` or `Mod+H` | Focus column left |
|
||||
| `Mod+Right` or `Mod+L` | Focus column right |
|
||||
| `Mod+Home` | Focus first column |
|
||||
| `Mod+End` | Focus last column |
|
||||
| `Mod+C` | Center focused column |
|
||||
| `Mod+Ctrl+C` | Center all visible columns |
|
||||
|
||||
## Column Movement
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Ctrl+Left` or `Mod+Ctrl+H` | Move column left |
|
||||
| `Mod+Ctrl+Right` or `Mod+Ctrl+L` | Move column right |
|
||||
| `Mod+Ctrl+Home` | Move column to first position |
|
||||
| `Mod+Ctrl+End` | Move column to last position |
|
||||
|
||||
## Column Sizing
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+R` | Switch preset column width (1/3, 1/2, 2/3) |
|
||||
| `Mod+Shift+R` | Switch preset width (reverse) |
|
||||
| `Mod+Minus` | Decrease column width by 10% |
|
||||
| `Mod+Equal` | Increase column width by 10% |
|
||||
|
||||
## Window Navigation (within column)
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Up` or `Mod+K` | Focus window up |
|
||||
| `Mod+Down` or `Mod+J` | Focus window down |
|
||||
|
||||
## Window Height Sizing
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Ctrl+Shift+R` | Switch preset window height |
|
||||
| `Mod+Ctrl+R` | Reset window height |
|
||||
| `Mod+Shift+Minus` | Decrease window height by 10% |
|
||||
| `Mod+Shift+Equal` | Increase window height by 10% |
|
||||
|
||||
## Multi-Monitor Navigation
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Shift+Left` or `Mod+Shift+H` | Focus monitor left |
|
||||
| `Mod+Shift+Right` or `Mod+Shift+L` | Focus monitor right |
|
||||
| `Mod+Shift+Up` or `Mod+Shift+K` | Focus monitor up |
|
||||
| `Mod+Shift+Down` or `Mod+Shift+J` | Focus monitor down |
|
||||
|
||||
## Multi-Monitor Column Movement
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Shift+Ctrl+Left` | Move column to monitor left |
|
||||
| `Mod+Shift+Ctrl+Right` | Move column to monitor right |
|
||||
| `Mod+Shift+Ctrl+Up` | Move column to monitor up |
|
||||
| `Mod+Shift+Ctrl+Down` | Move column to monitor down |
|
||||
|
||||
## Workspace Navigation
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Page_Down` or `Mod+U` | Focus workspace down |
|
||||
| `Mod+Page_Up` or `Mod+I` | Focus workspace up |
|
||||
| `Mod+1` through `Mod+9` | Focus workspace 1-9 |
|
||||
| `Mod+Shift+Page_Down` or `Mod+Shift+U` | Move workspace down |
|
||||
| `Mod+Shift+Page_Up` or `Mod+Shift+I` | Move workspace up |
|
||||
| `Mod+Tab` | Focus previous workspace (commented out by default) |
|
||||
|
||||
## Workspace Column Movement
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Ctrl+Page_Down` or `Mod+Ctrl+U` | Move column to workspace down |
|
||||
| `Mod+Ctrl+Page_Up` or `Mod+Ctrl+I` | Move column to workspace up |
|
||||
| `Mod+Ctrl+1` through `Mod+Ctrl+9` | Move column to workspace 1-9 |
|
||||
|
||||
## Mouse/Touchpad Scrolling
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+WheelScrollDown` | Focus workspace down |
|
||||
| `Mod+WheelScrollUp` | Focus workspace up |
|
||||
| `Mod+WheelScrollRight` | Focus column right |
|
||||
| `Mod+WheelScrollLeft` | Focus column left |
|
||||
| `Mod+Ctrl+WheelScrollDown` | Move column to workspace down |
|
||||
| `Mod+Ctrl+WheelScrollUp` | Move column to workspace up |
|
||||
| `Mod+Ctrl+WheelScrollRight` | Move column right |
|
||||
| `Mod+Ctrl+WheelScrollLeft` | Move column left |
|
||||
| `Mod+Shift+WheelScrollDown` | Focus column right |
|
||||
| `Mod+Shift+WheelScrollUp` | Focus column left |
|
||||
| `Mod+Ctrl+Shift+WheelScrollDown` | Move column right |
|
||||
| `Mod+Ctrl+Shift+WheelScrollUp` | Move column left |
|
||||
|
||||
## Overview
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+O` | Toggle overview (zoomed-out view of workspaces/windows) |
|
||||
|
||||
## Screenshot
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Print` | Interactive screenshot UI |
|
||||
| `Ctrl+Print` | Screenshot screen |
|
||||
| `Alt+Print` | Screenshot window |
|
||||
|
||||
## System
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Mod+Shift+E` | Quit niri (with confirmation) |
|
||||
| `Ctrl+Alt+Delete` | Quit niri (with confirmation) |
|
||||
| `Mod+Shift+P` | Power off monitors |
|
||||
| `Mod+Escape` | Toggle keyboard shortcuts inhibitor |
|
||||
| `Mod+Shift+/` | Show hotkey overlay |
|
||||
|
||||
## Media Keys
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `XF86AudioRaiseVolume` | Increase volume 10% |
|
||||
| `XF86AudioLowerVolume` | Decrease volume 10% |
|
||||
| `XF86AudioMute` | Toggle mute |
|
||||
| `XF86AudioMicMute` | Toggle mic mute |
|
||||
| `XF86AudioPlay` / `XF86AudioPause` | Play/pause |
|
||||
| `XF86AudioStop` | Stop |
|
||||
| `XF86AudioPrev` | Previous track |
|
||||
| `XF86AudioNext` | Next track |
|
||||
| `XF86MonBrightnessUp` | Increase brightness 10% |
|
||||
| `XF86MonBrightnessDown` | Decrease brightness 10% |
|
||||
|
||||
## Related
|
||||
|
||||
* [Key Bindings Syntax](/tools/niri/key-bindings-syntax.md) — How to write custom bindings
|
||||
* [Action Reference](/tools/niri/action-reference.md) — All available actions
|
||||
@@ -0,0 +1,95 @@
|
||||
# Niri Wayland Compositor
|
||||
|
||||
Niri is a scrollable-tiling Wayland compositor. Windows are arranged in columns that scroll horizontally. It uses KDL-format configuration with an include-based modular structure.
|
||||
|
||||
**Version:** 26.04 (8ed0da4)
|
||||
**Config:** `~/.config/niri/config.kdl`
|
||||
|
||||
---
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
```
|
||||
~/.config/niri/
|
||||
├── config.kdl # Main entry, includes all modules
|
||||
└── cfg/
|
||||
├── animation.kdl # Spring and curve animations
|
||||
├── autostart.kdl # Startup applications
|
||||
├── display.kdl # Output configuration
|
||||
├── input.kdl # Keyboard, touchpad, mouse
|
||||
├── keybinds.kdl # All key bindings
|
||||
├── layout.kdl # Gaps, column widths, struts
|
||||
├── rules.kdl # Window and layer rules
|
||||
└── misc.kdl # Environment, cursor, debug
|
||||
```
|
||||
|
||||
## Layout
|
||||
|
||||
Column-based scrollable tiling. Columns are cycled with Mod+Left/Right (or Mod+H/L). Windows within columns stack vertically.
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **Gaps** | 16px |
|
||||
| **Center focused column** | Never |
|
||||
| **Background** | Transparent (for Noctalia wallpaper) |
|
||||
| **Column presets** | 33%, 50%, 67% |
|
||||
|
||||
## Input
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **Focus follows mouse** | Enabled |
|
||||
| **Workspace back-and-forth** | Enabled |
|
||||
| **Numlock** | Enabled on startup |
|
||||
| **Touchpad tap** | Enabled |
|
||||
| **Natural scroll** | Enabled |
|
||||
|
||||
## Window Rules
|
||||
|
||||
| Rule | Match | Effect |
|
||||
|------|-------|--------|
|
||||
| All windows | — | 20px corner radius, clipped |
|
||||
| Steam (non-window) | `app-id="steam"`, exclude title `Steam` | Open floating |
|
||||
| Steam notifications | `app-id="steam"`, title `notificationtoasts_*` | Floating, bottom-right |
|
||||
| Noctalia wallpaper | namespace `noctalia-wallpaper*` | Place in backdrop |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Value | Purpose |
|
||||
|----------|-------|---------|
|
||||
| `ELECTRON_OZONE_PLATFORM_HINT` | `auto` | Electron Wayland support |
|
||||
| `QT_QPA_PLATFORM` | `wayland` | Qt Wayland |
|
||||
| `QT_QPA_PLATFORMTHEME` | `gtk3` | Qt GTK theme |
|
||||
| `QT_WAYLAND_DISABLE_WINDOWDECORATION` | `1` | Remove Qt CSD |
|
||||
| `XDG_CURRENT_DESKTOP` | `niri` | Desktop identification |
|
||||
| `XDG_SESSION_TYPE` | `wayland` | Session type |
|
||||
| `render-node` | `/dev/dri/renderD129` | Intel Arc iGPU |
|
||||
|
||||
## Animations
|
||||
|
||||
| Animation | Type | Parameters |
|
||||
|-----------|------|------------|
|
||||
| Workspace switch | Spring | damping=1.0, stiffness=1000 |
|
||||
| Window open | Duration | 200ms, ease-out-quad |
|
||||
| Window close | Duration | 200ms, ease-out-cubic |
|
||||
| Window movement | Spring | damping=1.0, stiffness=800 |
|
||||
| Window resize | Spring | damping=1.0, stiffness=1000 |
|
||||
|
||||
---
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [[action-reference|action-reference.md]] | reference | Complete reference of all available niri actions |
|
||||
| [[default-bindings|default-bindings.md]] | reference | Default key bindings organized by category |
|
||||
| [[key-bindings-syntax|key-bindings-syntax.md]] | reference | KDL configuration syntax for key bindings |
|
||||
| [[tips|tips.md]] | howto | Practical tips for working with niri |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [[noctalia-shell|noctalia-shell]] — Desktop shell integration
|
||||
- [[displays|displays]] — Three-monitor setup
|
||||
- [[cachyos|cachyos]] — Operating system
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
type: reference
|
||||
title: Niri Key Bindings Syntax
|
||||
description: Configuration syntax for niri key bindings — KDL format, modifiers, bind options, and finding key names with wev.
|
||||
tags:
|
||||
- niri
|
||||
- keybindings
|
||||
- kdl
|
||||
- configuration
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Key Bindings Syntax
|
||||
|
||||
Key bindings go in the `binds {}` section of the config file (`~/.config/niri/config.kdl`):
|
||||
|
||||
```kdl
|
||||
binds {
|
||||
Mod+T { spawn "alacritty"; }
|
||||
Mod+Left { focus-column-left; }
|
||||
}
|
||||
```
|
||||
|
||||
## Modifiers
|
||||
|
||||
- `Ctrl` or `Control`
|
||||
- `Shift`
|
||||
- `Alt`
|
||||
- `Super` or `Win`
|
||||
- `ISO_Level3_Shift` or `Mod5` (AltGr)
|
||||
- `ISO_Level5_Shift` (for lv5 options like `lv5:caps_switch`)
|
||||
- `Mod` — Special: equals `Super` on TTY, equals `Alt` in nested window
|
||||
|
||||
## Bind Options
|
||||
|
||||
```kdl
|
||||
binds {
|
||||
Mod+T repeat=false { spawn "alacritty"; } // Do not repeat on hold
|
||||
Mod+T cooldown-ms=500 { spawn "alacritty"; } // Rate-limit
|
||||
Super+Alt+L allow-when-locked=true { spawn "swaylock"; } // Works when locked
|
||||
Mod+Q hotkey-overlay-title="Close Window" { close-window; } // Custom title in overlay
|
||||
Mod+Escape allow-inhibiting=false { ... } // Always works (even with inhibitors)
|
||||
}
|
||||
```
|
||||
|
||||
## Finding Key Names
|
||||
|
||||
Use [`wev`](https://git.sr.ht/~sircmpwn/wev) to find XKB key names:
|
||||
|
||||
```bash
|
||||
wev
|
||||
# Then press the key you want to bind — look at `sym: XXXX` in output
|
||||
```
|
||||
|
||||
Shifted keys require Shift + the unshifted key (for example, `Mod+Shift+Comma` for `<` on US QWERTY).
|
||||
|
||||
## Related
|
||||
|
||||
* [Default Key Bindings](/tools/niri/default-bindings.md) — What niri ships with out of the box
|
||||
* [Action Reference](/tools/niri/action-reference.md) — All available actions
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
type: howto
|
||||
title: Niri Tips and Gotchas
|
||||
description: Practical tips for working with niri — Mod key behavior, shell expansion, config reload, vim keys, and programmatic invocation.
|
||||
tags:
|
||||
- niri
|
||||
- tips
|
||||
- gotchas
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Helpful Tips
|
||||
|
||||
## 1. Mod key
|
||||
|
||||
Use `Mod` instead of `Super` for configs that work both on TTY and in nested windows.
|
||||
|
||||
## 2. No shell expansion in spawn
|
||||
|
||||
`spawn` does not expand `$VAR` or `~`. Use `spawn-sh` or wrap in `sh -c`.
|
||||
|
||||
## 3. Config reload
|
||||
|
||||
niri supports live-reloading config without restart.
|
||||
|
||||
## 4. Alternative navigation
|
||||
|
||||
Vim-like keys (H/J/K/L) are bound by default alongside arrow keys.
|
||||
|
||||
## 5. Programmatic invocation
|
||||
|
||||
Every action can be invoked via `niri msg action <action-name>`.
|
||||
|
||||
## 6. Find XKB keys
|
||||
|
||||
Use `wev` to discover key names.
|
||||
|
||||
## Related
|
||||
|
||||
* [Key Bindings Syntax](/tools/niri/key-bindings-syntax.md) — Configuration details
|
||||
* [Action Reference](/tools/niri/action-reference.md) — All available actions
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
type: reference
|
||||
title: Noctalia Shell
|
||||
description: Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls.
|
||||
tags:
|
||||
- noctalia
|
||||
- quickshell
|
||||
- wayland
|
||||
- shell
|
||||
- launcher
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
# Noctalia Shell
|
||||
|
||||
Noctalia Shell is a sleek, minimal desktop shell for Wayland built with [Quickshell](https://github.com/outfoxxed/quickshell). It provides an app launcher, wallpaper manager, session menu, lock screen, hotkey overlay, media controls, and brightness/volume controls.
|
||||
|
||||
**Version:** 4.7.7
|
||||
**Dependency:** noctalia-qs / qs 0.0.12
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Noctalia communicates through an IPC system accessed via the `qs` command:
|
||||
|
||||
```bash
|
||||
qs -c noctalia-shell ipc call <module> <action> [params]
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
| Component | IPC Command | Description |
|
||||
|-----------|-------------|-------------|
|
||||
| **Shell** | `qs -c noctalia-shell` | Main shell process |
|
||||
| **Launcher** | `ipc call launcher toggle` | Application launcher |
|
||||
| **Lock Screen** | `ipc call lockScreen lock` | Screen locker |
|
||||
| **Session Menu** | `ipc call sessionMenu toggle` | Power/logout menu |
|
||||
| **Hotkey Overlay** | `ipc call overlay toggle` | Visual keybind reference |
|
||||
| **Volume** | `ipc call volume increase/decrease/muteOutput` | Audio controls |
|
||||
| **Media** | `ipc call media playPause/next/previous` | Media playback |
|
||||
| **Brightness** | `ipc call brightness increase/decrease` | Display brightness |
|
||||
| **Wallpaper** | Layer namespace `noctalia-wallpaper*` | Desktop wallpaper |
|
||||
|
||||
---
|
||||
|
||||
## Niri Integration
|
||||
|
||||
Noctalia is deeply integrated with the Niri compositor configuration:
|
||||
|
||||
### Autostart
|
||||
|
||||
**File:** `~/.config/niri/cfg/autostart.kdl`
|
||||
|
||||
```kdl
|
||||
spawn-sh-at-startup "qs -c noctalia-shell"
|
||||
```
|
||||
|
||||
### Keybindings
|
||||
|
||||
**File:** `~/.config/niri/cfg/keybinds.kdl`
|
||||
|
||||
| Keybind | Action | IPC Command |
|
||||
|---------|--------|-------------|
|
||||
| `Mod+Return` | Terminal | `spawn "ghostty"` |
|
||||
| `Mod+CTRL+Return` | App Launcher | `noctalia-shell ipc call launcher toggle` |
|
||||
| `Mod+B` | Browser | `spawn "firefox"` |
|
||||
| `Mod+ALT+L` | Lock Screen | `noctalia-shell ipc call lockScreen lock` |
|
||||
| `Mod+Shift+Q` | Session Menu | `noctalia-shell ipc call sessionMenu toggle` |
|
||||
| `Mod+Shift+Escape` | Hotkey Overlay | `show-hotkey-overlay` |
|
||||
| `Mod+E` | File Manager | `spawn "nautilus"` |
|
||||
|
||||
### Media and Brightness
|
||||
|
||||
| Key | Action | IPC Command |
|
||||
|-----|--------|-------------|
|
||||
| `XF86AudioRaiseVolume` | Volume Up | `volume increase` |
|
||||
| `XF86AudioLowerVolume` | Volume Down | `volume decrease` |
|
||||
| `XF86AudioMute` | Mute | `volume muteOutput` |
|
||||
| `XF86AudioMicMute` | Mic Mute | `volume muteInput` |
|
||||
| `XF86AudioPlay` | Play/Pause | `media playPause` |
|
||||
| `XF86AudioNext` | Next Track | `media next` |
|
||||
| `XF86AudioPrev` | Previous | `media previous` |
|
||||
| `XF86MonBrightnessUp` | Brightness Up | `brightness increase` |
|
||||
| `XF86MonBrightnessDown` | Brightness Down | `brightness decrease` |
|
||||
|
||||
### Wallpaper
|
||||
|
||||
The wallpaper layer is placed in the backdrop:
|
||||
|
||||
```kdl
|
||||
// In ~/.config/niri/cfg/rules.kdl
|
||||
layer-rule {
|
||||
match namespace="^noctalia-wallpaper*"
|
||||
place-within-backdrop true
|
||||
}
|
||||
```
|
||||
|
||||
The background color is set to transparent to allow the wallpaper to show:
|
||||
|
||||
```kdl
|
||||
// In ~/.config/niri/cfg/layout.kdl
|
||||
layout {
|
||||
background-color "transparent"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| `noctalia-qs` / `qs` | Quickshell runtime |
|
||||
| `imagemagick` | Image processing |
|
||||
| `brightnessctl` | Brightness control |
|
||||
| `ffmpeg` | Media processing |
|
||||
| `qt6-multimedia` | Qt multimedia |
|
||||
| `python` | Python runtime |
|
||||
| `wlr-randr` | Display information |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [niri](niri/index.md) — Compositor configuration
|
||||
- [[displays|displays]] — Display layout
|
||||
- [[cachyos|cachyos]] — Operating system documentation
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
type: guide
|
||||
title: Skill Author Best Practices
|
||||
description: Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- best-practices
|
||||
- authoring
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Best Practices for Skill Authors
|
||||
|
||||
## Description Writing
|
||||
|
||||
1. **Be specific about capabilities** — "Extracts text and tables from PDF files, fills forms, merges documents" vs "Helps with documents"
|
||||
2. **Include trigger phrases** — "Use when working with PDF files or when user mentions PDFs, forms, or document extraction"
|
||||
3. **Keep under 1024 characters**
|
||||
4. **Write in third person**
|
||||
5. **First sentence = what it does, second sentence = when to use it**
|
||||
|
||||
## File Organization
|
||||
|
||||
1. **Use progressive disclosure** — Keep SKILL.md focused; reference detailed docs in `references/`
|
||||
2. **Add scripts for deterministic operations** — When the same code would be generated repeatedly, scripts save tokens and improve reliability
|
||||
3. **Split files when content exceeds ~500 lines** — Agents load the entire file on activation
|
||||
4. **Include a config.json** for configurable paths or settings
|
||||
5. **Add tests** — Include test scripts and mock data for validation
|
||||
|
||||
## Security
|
||||
|
||||
1. **Review skill content before use** — Skills can instruct the model to perform any action
|
||||
2. **Scripts run with your full system permissions** — Only install from trusted sources
|
||||
3. **Document dependencies clearly** — List all required tools, API keys, and setup steps
|
||||
|
||||
## Distribution
|
||||
|
||||
1. **Add `pi-package` keyword** to package.json for npm discoverability
|
||||
2. **Include `video` or `image` fields** in the pi manifest for the gallery
|
||||
3. **Use peerDependencies** for pi-provided packages: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `typebox`
|
||||
4. **List runtime deps in `dependencies`** — They get installed automatically
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How to structure your npm package
|
||||
* [Installation](/tools/npx-skills/installation.md) — How users will install your skills
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
type: reference
|
||||
title: Ecosystem Resources
|
||||
description: GitHub repositories, npm packages, and community resources for the pi skills ecosystem.
|
||||
tags:
|
||||
- unverified
|
||||
- ecosystem
|
||||
- npm
|
||||
- repositories
|
||||
- community
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Ecosystem Resources
|
||||
|
||||
## Official Documentation
|
||||
|
||||
- [Pi Skills Documentation](https://github.com/earendil-works/pi)
|
||||
- [Pi Packages Documentation](https://github.com/earendil-works/pi)
|
||||
- [Agent Skills Specification](https://agentskills.io/specification)
|
||||
- [Agent Skills Integration Guide](https://agentskills.io/integrate-skills)
|
||||
- [Pi Packages Gallery](https://pi.dev/packages)
|
||||
|
||||
## GitHub Repositories
|
||||
|
||||
| Repository | Description | Stars |
|
||||
|------------|-------------|-------|
|
||||
| [badlogic/pi-skills](https://github.com/badlogic/pi-skills) | Official skills collection (brave-search, browser-tools, Google APIs, transcription) | 2,138 |
|
||||
| [ifiokjr/monopi](https://github.com/ifiokjr/monopi) | One-click pi setup with skills, extensions, themes, subagents | 136 |
|
||||
| [VenTheZone/pi-dots](https://github.com/VenTheZone/pi-dots) | 60+ skills covering research, content, project management, debugging | 42 |
|
||||
| [HazAT/pi-config](https://github.com/HazAT/pi-config) | Personal pi config with skills, extensions, agents | 418 |
|
||||
| [qualisero/awesome-pi-agent](https://github.com/qualisero/awesome-pi-agent) | Awesome list of pi add-ons, hooks, tools, skills | 1,093 |
|
||||
| [getpipher/pi-package-index](https://github.com/getpipher/pi-package-index) | Unofficial community index with GitHub stars + downloads | 2 |
|
||||
| [lukaspanni/pi-package-template](https://github.com/lukaspanni/pi-package-template) | Template for creating pi packages | 0 |
|
||||
|
||||
## Notable npm Packages
|
||||
|
||||
| Package | Description | Keywords |
|
||||
|---------|-------------|----------|
|
||||
| `pi-web-access` | Web search, URL fetching, PDF extraction, YouTube analysis | pi-package, web-search, perplexity |
|
||||
| `@wierdbytes/pi-peon` | Sound-pack player for pi (installed) | pi-package, peon, sound |
|
||||
| `bigpowers` | 73 agent skills for solo developers | skills, agents, claude, pi-package |
|
||||
| `pi-spark` | Polishes daily pi experience | pi-coding-agent, pi-package |
|
||||
| `@anton-kochev/pi-skills` | Planning, TDD, SRS, requirements skills | pi-package, pi-skill, tdd |
|
||||
| `@monopi/skills` | Curated skill packs (debug-helper, btw, nushell) | pi-package, skills |
|
||||
| `@dietrichgebert/ponytail` | Lazy senior dev mode with skills | opencode, pi-package, skills |
|
||||
| `pi-mcp-adapter` | MCP adapter for pi | pi-package, mcp |
|
||||
| `pi-subagents` | Subagent delegation with chains | pi-package, subagents |
|
||||
| `pi-lens` | Real-time code feedback (LSP, linters) | pi-package, linter |
|
||||
| `@vanillagreen/pi-skills-manager` | Skills manager with /skill menu | pi-package, skills, manager |
|
||||
|
||||
## Community Resources
|
||||
|
||||
- [pi-package.rectorspace.com](https://pi-package.rectorspace.com) — Unofficial package index with stars, downloads, maintenance signals
|
||||
- [Anthropic Skills](https://github.com/anthropics/skills) — Document processing skills (docx, pdf, pptx, xlsx)
|
||||
- [skills.sh](https://skills.sh) — Skills directory (by Vercel Labs)
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/npx-skills/installation.md) — How to install from these resources
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — How to contribute your own skills
|
||||
@@ -0,0 +1,18 @@
|
||||
# Npx Skills — Distribution & Installation
|
||||
|
||||
Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [best-practices.md](best-practices.md) | best-practices | Tips for writing good skill descriptions, organizing files, and distributing ... |
|
||||
| [ecosystem.md](ecosystem.md) | reference | GitHub repositories, npm packages, and community resources for the pi skills ... |
|
||||
| [installation.md](installation.md) | howto | Three methods for installing skills — pi install, npx-based setup tools, and ... |
|
||||
| [package-structure.md](package-structure.md) | reference | How pi packages bundle skills, extensions, prompts, and themes into a single ... |
|
||||
| [skill-commands.md](skill-commands.md) | reference | The /skill:name command system for explicitly loading and executing skills wi... |
|
||||
| [skill-file-structure.md](skill-file-structure.md) | reference | The directory structure of a skill — SKILL.md as the required entry point, wi... |
|
||||
| [skill-loading.md](skill-loading.md) | reference | The discovery flow, progressive disclosure pattern, and system prompt integra... |
|
||||
| [skills-spec.md](skills-spec.md) | reference | The Agent Skills standard that defines SKILL.md format, frontmatter fields, a... |
|
||||
| [skills-vs-extensions.md](skills-vs-extensions.md) | comparison | Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-... |
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
type: howto
|
||||
title: Installing Skills via npm / npx
|
||||
description: Three methods for installing skills — pi install, npx-based setup tools, and manual git clone.
|
||||
tags:
|
||||
- unverified
|
||||
- installation
|
||||
- npm
|
||||
- npx
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installing Skills via NPM / Npx
|
||||
|
||||
## Method 1: Direct `pi install` (recommended)
|
||||
|
||||
```bash
|
||||
# Install a package containing skills
|
||||
pi install npm:pi-web-access
|
||||
pi install npm:@anton-kochev/pi-skills
|
||||
pi install npm:bigpowers
|
||||
pi install npm:@monopi/skills
|
||||
|
||||
# Install from GitHub (also works for packages with skills)
|
||||
pi install git:github.com/badlogic/pi-skills
|
||||
pi install https://github.com/badlogic/pi-skills
|
||||
|
||||
# Project-level install (goes to .pi/settings.json)
|
||||
pi install -l npm:pi-web-access
|
||||
|
||||
# Try without installing (current session only)
|
||||
pi -e npm:pi-web-access
|
||||
```
|
||||
|
||||
## Method 2: Npx-based setup tools
|
||||
|
||||
Some meta-installers provide one-command setup:
|
||||
|
||||
```bash
|
||||
# monopi: one-command setup for pi with skills, extensions, themes, etc.
|
||||
npx @monopi/monopi
|
||||
|
||||
# Pin a version
|
||||
npx @monopi/monopi --version 0.2.13
|
||||
|
||||
# Project-local install
|
||||
npx @monopi/monopi --local
|
||||
|
||||
# Remove all monopi packages
|
||||
npx @monopi/monopi --remove
|
||||
```
|
||||
|
||||
## Method 3: Manual clone (git repos)
|
||||
|
||||
```bash
|
||||
# Clone the official pi-skills collection
|
||||
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
|
||||
|
||||
# Or project-level
|
||||
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills
|
||||
```
|
||||
|
||||
## Package Sources
|
||||
|
||||
| Source Type | Example | Notes |
|
||||
|-------------|---------|-------|
|
||||
| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` |
|
||||
| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` |
|
||||
| **local** | `./relative/path` | Points to local directory, added without copying |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Runtime dependencies belong in `dependencies` in `package.json`
|
||||
- Pi-provided packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`) as `peerDependencies` with `"*"` range
|
||||
- When pi installs from npm or git, it runs `npm install` automatically
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How pi packages are structured for npm distribution
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — Distribution tips for skill authors
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
type: reference
|
||||
title: Pi Package Structure
|
||||
description: How pi packages bundle skills, extensions, prompts, and themes into a single npm package with a pi manifest.
|
||||
tags:
|
||||
- unverified
|
||||
- packages
|
||||
- npm
|
||||
- distribution
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Packages — The Distribution Mechanism
|
||||
|
||||
Pi packages are npm packages that declare resources via a `pi` manifest in `package.json`. They are the primary way to distribute skills (along with extensions, prompts, and themes) through npm.
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
my-pi-package/
|
||||
├── package.json # npm metadata + pi manifest
|
||||
├── skills/ # Conventional directory (auto-discovered)
|
||||
│ ├── my-skill/
|
||||
│ │ └── SKILL.md
|
||||
│ └── another-skill/
|
||||
│ └── SKILL.md
|
||||
├── extensions/ # TypeScript extensions
|
||||
├── prompts/ # Prompt templates
|
||||
├── themes/ # TUI themes
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Package.json with pi Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-pi-package",
|
||||
"keywords": ["pi-package"],
|
||||
"pi": {
|
||||
"extensions": ["./extensions"],
|
||||
"skills": ["./skills"],
|
||||
"prompts": ["./prompts"],
|
||||
"themes": ["./themes"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Gallery Metadata
|
||||
|
||||
Packages tagged with `pi-package` appear on the [pi.dev/packages gallery](https://pi.dev/packages). Add preview media:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"skills": ["./skills"],
|
||||
"video": "https://example.com/demo.mp4",
|
||||
"image": "https://example.com/screenshot.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Two-Layer Model
|
||||
|
||||
```
|
||||
npm package (tagged pi-package)
|
||||
├── pi.skills manifest → points to ./skills/
|
||||
└── skills/
|
||||
├── brave-search/SKILL.md
|
||||
├── browser-tools/SKILL.md
|
||||
└── tdd-workflow/SKILL.md
|
||||
```
|
||||
|
||||
Skills are the **content** (SKILL.md + scripts). Pi packages are the **delivery mechanism** (npm tarball with a `pi` manifest).
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/npx-skills/installation.md) — How to install pi packages
|
||||
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — What goes inside a skill
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skill Commands
|
||||
description: The /skill:name command system for explicitly loading and executing skills with optional arguments.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- commands
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill Commands (`/skill:name`)
|
||||
|
||||
Skills register as `/skill:name` commands:
|
||||
|
||||
```bash
|
||||
/skill:brave-search # Load and execute the skill
|
||||
/skill:pdf-tools extract # Load skill with arguments
|
||||
```
|
||||
|
||||
Arguments after the command are appended to the skill content as `User: <args>`.
|
||||
|
||||
Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enableSkillCommands": true
|
||||
}
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill Loading](../npx-skills/skill-loading.md) — How skills are normally loaded
|
||||
* [Npx Skills Overview](../npx-skills/index.md) — Settings and package control
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skill File Structure
|
||||
description: The directory structure of a skill — SKILL.md as the required entry point, with optional scripts, references, and assets directories.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- structure
|
||||
- SKILL.md
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill File Structure
|
||||
|
||||
A skill is a **directory** with a `SKILL.md` file. Everything else is freeform.
|
||||
|
||||
## Standard Structure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Required: frontmatter + instructions
|
||||
├── scripts/ # Helper scripts (bash, js, python, etc.)
|
||||
│ ├── process.sh
|
||||
│ └── analyze.js
|
||||
├── references/ # Detailed docs loaded on-demand
|
||||
│ ├── api-reference.md
|
||||
│ └── FORMS.md
|
||||
├── assets/ # Templates, configs, binary data
|
||||
│ └── template.json
|
||||
├── config.json # Skill-specific configuration
|
||||
└── tests/ # Test scripts (optional)
|
||||
└── test_runner.sh
|
||||
```
|
||||
|
||||
## Real Example: zim-knowledge-base
|
||||
|
||||
```
|
||||
zim-knowledge-base/
|
||||
├── SKILL.md # Main skill instructions
|
||||
├── config.json # ZIM file path configuration
|
||||
├── scripts/
|
||||
│ ├── search.sh # Search ZIM file index
|
||||
│ ├── extract.sh # Extract article as HTML
|
||||
│ ├── list.sh # List article titles
|
||||
│ └── metadata.sh # Get article metadata
|
||||
└── tests/
|
||||
├── mock_zimdump.sh # Mock for testing
|
||||
├── test_runner.sh # Test harness
|
||||
└── test_zim_file.zim # Test fixture
|
||||
```
|
||||
|
||||
## Real Example: brave-search (from badlogic/pi-skills)
|
||||
|
||||
```
|
||||
brave-search/
|
||||
├── SKILL.md # Setup + usage instructions
|
||||
├── search.js # Brave Search API wrapper
|
||||
└── content.js # Page content extraction
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skills Specification](/tools/npx-skills/skills-spec.md) — Frontmatter fields and requirements
|
||||
* [Best Practices](/tools/npx-skills/best-practices.md) — File organization tips
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
type: reference
|
||||
title: How Pi Loads Skills
|
||||
description: The discovery flow, progressive disclosure pattern, and system prompt integration for skills in pi.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- loading
|
||||
- progressive-disclosure
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# How the Pi Agent Loads and Uses Skills
|
||||
|
||||
## Discovery Flow
|
||||
|
||||
1. Pi scans all configured skill locations at startup
|
||||
2. Extracts names and descriptions from each `SKILL.md`
|
||||
3. Builds the system prompt with skill descriptions in XML format
|
||||
4. The LLM decides which skill(s) to activate based on the user's prompt
|
||||
5. When activated, the agent reads the full SKILL.md using the `read` tool
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
|
||||
```
|
||||
System prompt (always in context):
|
||||
- "Available skills: brave-search (Web search...), browser-tools (Browser automation...), ..."
|
||||
|
||||
User: "Search for information about React hooks"
|
||||
|
||||
Agent decides: activate brave-search
|
||||
Agent reads: ~/.pi/agent/skills/brave-search/SKILL.md (full file)
|
||||
Agent executes: {baseDir}/search.js "React hooks"
|
||||
```
|
||||
|
||||
## This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
|
||||
|
||||
## Related
|
||||
|
||||
* [Skills Specification](/tools/npx-skills/skills-spec.md) — What the agent sees in the system prompt
|
||||
* [Skill Commands](/tools/npx-skills/skill-commands.md) — The `/skill:name` override
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
type: reference
|
||||
title: Agent Skills Specification
|
||||
description: The Agent Skills standard that defines SKILL.md format, frontmatter fields, and cross-agent compatibility.
|
||||
tags:
|
||||
- unverified
|
||||
- agent-skills
|
||||
- specification
|
||||
- npm
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Agent Skills Specification
|
||||
|
||||
Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. The specification defines:
|
||||
|
||||
- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields
|
||||
- A **Markdown body** with the skill's instructions
|
||||
- Optional subdirectories: `scripts/`, `references/`, `assets/`
|
||||
|
||||
The specification is designed to be **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and other compatible agents.
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. No leading/trailing hyphens. No consecutive hyphens. |
|
||||
| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. **This is the only thing the agent sees when deciding whether to activate the skill.** |
|
||||
| `license` | No | License name or reference to bundled file. |
|
||||
| `compatibility` | No | Max 500 chars. Environment requirements. |
|
||||
| `metadata` | No | Arbitrary key-value mapping. |
|
||||
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
|
||||
| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly. |
|
||||
|
||||
### Name Rules
|
||||
|
||||
Valid: `pdf-processing`, `data-analysis`, `code-review`
|
||||
Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
|
||||
|
||||
**Note:** Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories.
|
||||
|
||||
### Description Best Practices
|
||||
|
||||
The description determines when the agent loads the skill. Be specific.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
|
||||
```
|
||||
|
||||
**Poor:**
|
||||
```yaml
|
||||
description: Helps with PDFs.
|
||||
```
|
||||
|
||||
## Cross-Agent Compatibility
|
||||
|
||||
Skills follow a shared specification that works across:
|
||||
|
||||
- Pi (`~/.pi/agent/skills/`)
|
||||
- Claude Code (`~/.claude/skills/`)
|
||||
- Codex (`~/.codex/skills/`)
|
||||
- OpenCode (`~/.config/opencode/skills/`)
|
||||
- And [68+ other agents](/tools/vercel-labs-skills/agent-support.md)
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — How to organize SKILL.md and its supporting files
|
||||
* [Ecosystem](/tools/npx-skills/ecosystem.md) — Where to find community skills
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills vs Extensions
|
||||
description: Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-based) for pi coding agent.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- extensions
|
||||
- comparison
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skills vs Extensions
|
||||
|
||||
| Feature | Skills | Extensions |
|
||||
|---------|--------|------------|
|
||||
| **Format** | Markdown (`SKILL.md` + optional scripts) | TypeScript (`.ts` files) |
|
||||
| **Purpose** | Instructions for the LLM to follow | Code that intercepts events, registers tools/commands |
|
||||
| **Execution** | Agent reads and follows instructions | Runs in pi's Node.js runtime |
|
||||
| **Loading** | On-demand (progressive disclosure) | Always loaded at startup |
|
||||
| **Power** | Can instruct the agent to run anything | Full programmatic access to pi's API |
|
||||
| **Security** | Review content (instructs model) | Review code (runs arbitrary code) |
|
||||
| **Best for** | Domain knowledge, workflows, scripts | Permission gates, custom tools, event handling |
|
||||
| **Location** | `skills/` directory | `extensions/` directory |
|
||||
| **Can distribute via npm?** | Yes (via pi packages) | Yes (via pi packages) |
|
||||
|
||||
## When to Use Each
|
||||
|
||||
- **Skill**: You want to teach the agent a new workflow, provide domain expertise, or bundle helper scripts
|
||||
- **Extension**: You need to intercept tool calls, register new LLM-callable tools, modify system prompts programmatically, or add custom TUI components
|
||||
|
||||
## They Can Work Together
|
||||
|
||||
A pi package can contain both:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"extensions": ["./extensions"],
|
||||
"skills": ["./skills"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example: `pi-web-access` provides both a web-search extension AND skill documentation for it.
|
||||
|
||||
## Related
|
||||
|
||||
* [Package Structure](/tools/npx-skills/package-structure.md) — How to bundle both in one npm package
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
type: reference
|
||||
title: llama.cpp Server API Endpoints
|
||||
description: Complete reference for health check, model listing, chat completions, and native completion endpoints.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- api
|
||||
- llama.cpp
|
||||
- endpoints
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# API Endpoints
|
||||
|
||||
The llama.cpp server provides these endpoints:
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## List Models
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/models
|
||||
```
|
||||
|
||||
## Chat Completions (OpenAI-compatible)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "frank-default-local",
|
||||
"messages": [...],
|
||||
"max_tokens": 100
|
||||
}'
|
||||
```
|
||||
|
||||
## Native Completion Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/completion \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "Hello, how are you?",
|
||||
"n_predict": 100
|
||||
}'
|
||||
```
|
||||
|
||||
## Model Features
|
||||
|
||||
### Reasoning/Thinking Blocks
|
||||
|
||||
Ornith models use `<think>...</think>` blocks for reasoning. The server automatically:
|
||||
- Detects and preserves reasoning content
|
||||
- Returns reasoning in `reasoning_content` field
|
||||
- Supports the `developer` role (or falls back to `system`)
|
||||
|
||||
### Chat Template
|
||||
|
||||
The model uses a specific chat template that supports:
|
||||
- System prompts
|
||||
- User/Assistant roles
|
||||
- Reasoning preservation
|
||||
|
||||
## Related
|
||||
|
||||
* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — How pi connects to these endpoints
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Starting the server
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
type: reference
|
||||
title: GPU Layer Offloading Guidelines
|
||||
description: How many GPU layers to offload based on your VRAM size for both Ornith 9B and 35B models.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- gpu
|
||||
- offloading
|
||||
- llama.cpp
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# GPU Layer Offloading
|
||||
|
||||
## For 9B Q4_K_M (5.63 GB):
|
||||
|
||||
- **8GB VRAM:** `-ngl 35-40` (fits most layers)
|
||||
- **12GB VRAM:** `-ngl 99` (all layers)
|
||||
- **16GB+ VRAM:** `-ngl 99` (all layers + room for large KV cache)
|
||||
|
||||
## For 35B Q4_K_M (~20 GB):
|
||||
|
||||
- **8GB VRAM:** `-ngl 10-14` (partial offload)
|
||||
- **12GB VRAM:** `-ngl 18-22` (partial offload)
|
||||
- **16GB VRAM:** `-ngl 28-32` (partial offload)
|
||||
- **24GB VRAM:** `-ngl 40-48` (majority of layers)
|
||||
- **40GB+ VRAM:** `-ngl 99` (all layers)
|
||||
|
||||
**Note:** The 35B model is a MoE architecture, so actual memory usage depends on which experts are activated.
|
||||
|
||||
## Context Window Considerations
|
||||
|
||||
- **9B model:** Supports up to 262,144 tokens
|
||||
- **35B model:** Supports up to 262,144 tokens
|
||||
- **KV Cache Memory:** Larger context windows require more VRAM/RAM for the key-value cache
|
||||
- 131K context: ~8-16 GB depending on model and quantization
|
||||
- 256K context: ~16-32 GB depending on model and quantization
|
||||
|
||||
**Recommendation:** Start with 131K context if you have limited VRAM, increase to 256K if you have headroom.
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set the -ngl flag
|
||||
* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Memory requirements
|
||||
@@ -0,0 +1,17 @@
|
||||
# Ornith llama.cpp Setup
|
||||
|
||||
Complete reference for running Ornith-9B/35B MoE models with llama.cpp server on dankware.
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [api-endpoints.md](api-endpoints.md) | reference | Complete reference for health check, model listing, chat completions, and nat... |
|
||||
| [gpu-offloading.md](gpu-offloading.md) | reference | How many GPU layers to offload based on your VRAM size for both Ornith 9B and... |
|
||||
| [installation.md](installation.md) | howto | Step-by-step setup — clone and build llama.cpp, download models, start the se... |
|
||||
| [model-specs.md](model-specs.md) | reference | Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — contex... |
|
||||
| [performance.md](performance.md) | reference | Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU infe... |
|
||||
| [pi-configuration.md](pi-configuration.md) | howto | How to add Ornith models to models.json so pi can use the local llama.cpp ser... |
|
||||
| [systemd-service.md](systemd-service.md) | howto | Set up llama.cpp server as a background service with systemd for persistent o... |
|
||||
| [troubleshooting.md](troubleshooting.md) | howto | Common errors — CUDA OOM, segfaults, model not responding, poor performance —... |
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
type: howto
|
||||
title: Installing Ornith + llama.cpp
|
||||
description: Step-by-step setup — clone and build llama.cpp, download models, start the server, verify it works.
|
||||
tags:
|
||||
- ornith
|
||||
- installation
|
||||
- llama.cpp
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
## 1. Clone and Build llama.cpp
|
||||
|
||||
```bash
|
||||
cd ~/GitPackages
|
||||
git clone https://github.com/ggerganov/llama.cpp
|
||||
cd llama.cpp
|
||||
cmake -B build -DLLAMA_CUDA=ON
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
## 2. Download the Model
|
||||
|
||||
```bash
|
||||
mkdir -p ~/models/ornith
|
||||
cd ~/models/ornith
|
||||
|
||||
# For 9B model (faster, less memory)
|
||||
wget https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF/resolve/main/ornith-1.0-9b-Q4_K_M.gguf
|
||||
|
||||
# OR for 35B MoE model (better performance, more memory)
|
||||
wget https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF/resolve/main/ornith-1.0-35b-Q4_K_M.gguf
|
||||
```
|
||||
|
||||
## 3. Start the Server
|
||||
|
||||
**For 9B model with full GPU offload (8GB+ VRAM):**
|
||||
```bash
|
||||
cd ~/GitPackages/llama.cpp
|
||||
./build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-9b-Q4_K_M.gguf \
|
||||
-c 262144 \
|
||||
-ngl 99 \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080
|
||||
```
|
||||
|
||||
**For 35B MoE model with partial GPU offload (8GB VRAM example):**
|
||||
```bash
|
||||
cd ~/GitPackages/llama.cpp
|
||||
./build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 \
|
||||
-ngl 12 \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080
|
||||
```
|
||||
|
||||
**Key Parameters:**
|
||||
- `-m`: Path to GGUF model file
|
||||
- `-c` / `--ctx-size`: Context window size (131072 or 262144)
|
||||
- `-ngl` / `--n-gpu-layers`: Number of layers to offload to GPU
|
||||
- 99 = all layers
|
||||
- Lower values = more CPU inference
|
||||
- `--host`: Bind address (0.0.0.0 for all interfaces, 127.0.0.1 for local only)
|
||||
- `--port`: Server port (default 8080)
|
||||
|
||||
## 4. Verify Server is Running
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
# Expected: {"status":"ok"}
|
||||
```
|
||||
|
||||
## 5. Test the Model
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "frank-default-local",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello, what is 2+2?"}
|
||||
],
|
||||
"max_tokens": 150,
|
||||
"temperature": 0.7
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Model options and quantization
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Tuning GPU layer counts
|
||||
* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — Adding to models.json
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
type: reference
|
||||
title: Ornith Model Specifications
|
||||
description: Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — context length, quantization options, memory requirements.
|
||||
tags:
|
||||
- ornith
|
||||
- models
|
||||
- llama.cpp
|
||||
- GGUF
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Model Specifications
|
||||
|
||||
## Ornith-1.0-9B-GGUF
|
||||
|
||||
- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF
|
||||
- **Architecture:** Dense ~9B model
|
||||
- **Context Length:** 262,144 tokens (256K)
|
||||
- **Quantization Options:**
|
||||
- Q4_K_M: 5.3 GB (recommended for most systems)
|
||||
- Q5_K_M: 6.47 GB
|
||||
- Q6_K: 7.36 GB
|
||||
- Q8_0: 9.53 GB
|
||||
- bf16: 17.9 GB
|
||||
|
||||
## Ornith-1.0-35B-GGUF (MoE)
|
||||
|
||||
- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF
|
||||
- **Architecture:** 35B MoE (Mixture of Experts)
|
||||
- **Context Length:** 262,144 tokens (256K)
|
||||
- **Quantization Options:**
|
||||
- Q4_K_M: 20 GB (recommended)
|
||||
- Other quantizations available
|
||||
|
||||
**Note:** No fp4 quantization exists for these models. Q4_K_M is the lightest quantization.
|
||||
|
||||
## Comparison: 9B vs 35B MoE
|
||||
|
||||
| Aspect | 9B Dense | 35B MoE |
|
||||
|--------|----------|---------|
|
||||
| **Memory (Q4)** | 5.3 GB | 20 GB |
|
||||
| **VRAM for Full GPU** | 8 GB | 24-40 GB |
|
||||
| **Speed (GPU)** | Faster | Slower but better quality |
|
||||
| **Quality** | Good | Excellent |
|
||||
| **Context** | 256K | 256K |
|
||||
| **Best For** | Quick tasks, limited RAM | Complex reasoning, best quality |
|
||||
|
||||
## Requirements
|
||||
|
||||
### Hardware
|
||||
- **RAM:** Minimum 16GB for 9B model, 32GB+ for 35B model
|
||||
- **GPU** (optional but recommended):
|
||||
- 9B Q4: 6-8GB VRAM for full GPU offload
|
||||
- 35B Q4: 24GB+ VRAM for full GPU offload
|
||||
|
||||
### Software
|
||||
- llama.cpp built with CUDA support (for GPU acceleration)
|
||||
- Git (for cloning llama.cpp repo)
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set up the server
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Layer allocation by VRAM
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
type: reference
|
||||
title: Performance Benchmarks
|
||||
description: Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU inference.
|
||||
tags:
|
||||
- ornith
|
||||
- performance
|
||||
- benchmarks
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Performance
|
||||
# Performance
|
||||
|
||||
## 9B Model:
|
||||
|
||||
- **Prompt Processing:** ~10-15 tokens/sec (CPU), ~50-100 tokens/sec (GPU)
|
||||
- **Generation:** ~8-12 tokens/sec (CPU), ~40-80 tokens/sec (GPU)
|
||||
|
||||
## 35B MoE Model:
|
||||
|
||||
- **Prompt Processing:** ~5-8 tokens/sec (CPU+GPU mix), ~30-50 tokens/sec (full GPU)
|
||||
- **Generation:** ~4-8 tokens/sec (CPU+GPU mix), ~20-40 tokens/sec (full GPU)
|
||||
|
||||
**Note:** MoE models can be slower due to expert routing overhead, but provide better quality.
|
||||
|
||||
## Tuning Tips
|
||||
|
||||
1. **Increase GPU layers** (`-ngl`) for better speed
|
||||
2. **Enable Flash Attention:** `--flash-attn on` (if supported)
|
||||
3. **Use a smaller quantization** (Q4_K_M instead of Q8_0)
|
||||
4. **Reduce context window size** if memory-bound
|
||||
5. **KV Cache Quantization:** `--cache-type-k q8_0` to reduce KV cache memory
|
||||
|
||||
## Related
|
||||
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Optimize GPU layers for your hardware
|
||||
* [Troubleshooting](/tools/ornith-llama-cpp-setup/troubleshooting.md) — Fix performance issues
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
type: howto
|
||||
title: Pi Configuration for Ornith Models
|
||||
description: How to add Ornith models to models.json so pi can use the local llama.cpp server as a provider.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- pi
|
||||
- models.json
|
||||
- configuration
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Pi Configuration
|
||||
|
||||
Add to `~/.pi/agent/models.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"llamacpp (local-ornith)": {
|
||||
"baseUrl": "http://localhost:8080/v1",
|
||||
"api": "openai-completions",
|
||||
"apiKey": "EMPTY",
|
||||
"compat": {
|
||||
"supportsDeveloperRole": false,
|
||||
"supportsReasoningEffort": false
|
||||
},
|
||||
"models": [
|
||||
{
|
||||
"id": "frank-default-local",
|
||||
"name": "Ornith-1.0-35B-Q4_K_M (Local)",
|
||||
"contextWindow": 131072,
|
||||
"reasoning": true,
|
||||
"thinkingLevelMap": {
|
||||
"max": "xhigh"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important Compatibility Settings:**
|
||||
|
||||
- `supportsDeveloperRole: false` — The server does not support the `developer` role, uses `system` instead
|
||||
- `supportsReasoningEffort: false` — The server does not support the `reasoning_effort` parameter
|
||||
- `reasoning: true` — Model supports reasoning/thinking blocks
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Get the server running first
|
||||
* [API Endpoints](/tools/ornith-llama-cpp-setup/api-endpoints.md) — The endpoints this configuration targets
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
type: howto
|
||||
title: Running Ornith as a Systemd Service
|
||||
description: Set up llama.cpp server as a background service with systemd for persistent operation.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- systemd
|
||||
- service
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Systemd Service
|
||||
|
||||
## Using nohup:
|
||||
|
||||
```bash
|
||||
nohup ~/GitPackages/llama.cpp/build/bin/llama-server \
|
||||
-m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 -ngl 12 \
|
||||
--host 0.0.0.0 --port 8080 \
|
||||
> ~/logs/llama-server.log 2>&1 &
|
||||
```
|
||||
|
||||
## Using systemd (advanced):
|
||||
|
||||
Create `/etc/systemd/system/llama-server.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=llama.cpp Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=dank
|
||||
ExecStart=/home/dank/GitPackages/llama.cpp/build/bin/llama-server \
|
||||
-m /home/dank/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \
|
||||
-c 131072 -ngl 12 \
|
||||
--host 0.0.0.0 --port 8080
|
||||
Restart=on-failure
|
||||
WorkingDirectory=/home/dank/GitPackages/llama.cpp
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable llama-server
|
||||
sudo systemctl start llama-server
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The server setup this service wraps
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
type: howto
|
||||
title: Troubleshooting Ornith + llama.cpp
|
||||
description: Common errors — CUDA OOM, segfaults, model not responding, poor performance — and their fixes.
|
||||
tags:
|
||||
- unverified
|
||||
- ornith
|
||||
- troubleshooting
|
||||
- llama.cpp
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## CUDA Out of Memory
|
||||
|
||||
```
|
||||
Error: cudaMalloc failed: out of memory
|
||||
```
|
||||
|
||||
**Solution:** Reduce `-ngl` value to offload fewer layers to GPU.
|
||||
|
||||
## Segmentation Fault
|
||||
|
||||
```
|
||||
Segmentation fault (core dumped)
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Reduce context size (`-c` parameter)
|
||||
2. Reduce GPU layers (`-ngl`)
|
||||
3. Check if model file is corrupted
|
||||
|
||||
## Model Not Responding
|
||||
|
||||
```
|
||||
curl: (7) Failed to connect to localhost port 8080
|
||||
```
|
||||
|
||||
**Solution:** Check if server is running:
|
||||
```bash
|
||||
ps aux | grep llama-server
|
||||
tail -f ~/logs/llama-server.log
|
||||
```
|
||||
|
||||
## Poor Performance
|
||||
|
||||
**Solutions:**
|
||||
1. Increase GPU layers (`-ngl`)
|
||||
2. Enable Flash Attention: `--flash-attn on` (if supported)
|
||||
3. Use a smaller quantization (Q4_K_M instead of Q8_0)
|
||||
4. Reduce context window size
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Local Server:** By default, binds to localhost (127.0.0.1)
|
||||
- **Network Exposure:** If binding to 0.0.0.0, consider:
|
||||
- Adding authentication (`--api-key`)
|
||||
- Using a firewall to restrict access
|
||||
- Running behind a reverse proxy with TLS
|
||||
|
||||
```bash
|
||||
# Add API key authentication
|
||||
./build/bin/llama-server ... --api-key your-secret-key
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The commands that might be causing issues
|
||||
* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — GPU configuration
|
||||
@@ -0,0 +1,409 @@
|
||||
---
|
||||
type: reference
|
||||
title: tmux
|
||||
description: Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
|
||||
tags:
|
||||
- terminal
|
||||
- multiplexer
|
||||
- tmux
|
||||
timestamp: 2026-08-06
|
||||
---
|
||||
|
||||
# tmux Configuration Guide
|
||||
|
||||
Complete reference for tmux keyboard configuration, extended-keys, and best practices.
|
||||
|
||||
**Verified for tmux 3.6** (June 2026)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Extended Keys Configuration](#extended-keys-configuration)
|
||||
2. [Best Practices for Keyboard Input](#best-practices-for-keyboard-input)
|
||||
3. [Reloading vs. Restarting tmux](#reloading-vs-restarting-tmux)
|
||||
4. [Essential Configuration Reference](#essential-configuration-reference)
|
||||
5. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Extended Keys Configuration
|
||||
|
||||
### What is `extended-keys`?
|
||||
|
||||
The `extended-keys` option enables tmux to forward modified key combinations (keys pressed with Shift, Ctrl, Alt/Meta, or other modifiers) to applications running inside tmux. Without this configuration, tmux strips modifier information from certain keys by default.
|
||||
|
||||
### Why is it needed?
|
||||
|
||||
By default, tmux cannot distinguish between many modified key combinations:
|
||||
|
||||
| Key | Without extended-keys | With extended-keys (csi-u) |
|
||||
|-----|----------------------|---------------------------|
|
||||
| Enter | `\r` | `\r` |
|
||||
| Shift+Enter | `\r` (indistinguishable!) | `\x1b[13;2u` |
|
||||
| Ctrl+Enter | `\r` (indistinguishable!) | `\x1b[13;5u` |
|
||||
| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
|
||||
|
||||
This affects:
|
||||
- Applications that rely on modified Enter keys (like Pi, Neovim, etc.)
|
||||
- Custom keybindings using Shift+Enter, Ctrl+Enter, etc.
|
||||
- Any application using the Kitty keyboard protocol or CSI-u format
|
||||
|
||||
### The Recommended Configuration
|
||||
|
||||
Add these lines to `~/.tmux.conf`:
|
||||
|
||||
```tmux
|
||||
# Enable extended key reporting
|
||||
set -g extended-keys on
|
||||
|
||||
# Use CSI-u format (requires tmux 3.5+)
|
||||
set -g extended-keys-format csi-u
|
||||
```
|
||||
|
||||
### Why `csi-u` format is recommended
|
||||
|
||||
tmux supports two formats for extended keys:
|
||||
|
||||
1. **xterm (default)**: Uses `modifyOtherKeys` format
|
||||
- `Ctrl+C` → `\x1b[27;5;99~`
|
||||
- `Ctrl+D` → `\x1b[27;5;100~`
|
||||
- `Ctrl+Enter` → `\x1b[27;5;13~`
|
||||
|
||||
2. **csi-u (recommended)**: Uses CSI-u format
|
||||
- `Ctrl+C` → `\x1b[99;5u`
|
||||
- `Ctrl+D` → `\x1b[100;5u`
|
||||
- `Ctrl+Enter` → `\x1b[13;5u`
|
||||
|
||||
The `csi-u` format is more reliable and is the modern standard. Applications like Pi automatically request extended key reporting when Kitty keyboard protocol is not available.
|
||||
|
||||
### Requirements
|
||||
|
||||
- **tmux 3.5 or later** for `extended-keys-format csi-u`
|
||||
- Check version: `tmux -V`
|
||||
- For tmux 3.2–3.4, omit the `extended-keys-format` line. The default xterm format still works
|
||||
- A terminal emulator that supports extended keys:
|
||||
- Ghostty
|
||||
- Kitty
|
||||
- iTerm2
|
||||
- WezTerm
|
||||
- Windows Terminal
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Keyboard Input and Keybindings
|
||||
|
||||
### Essential Settings
|
||||
|
||||
```tmux
|
||||
# Fix Vim ESC delay (tmux 3.5+ already defaults to 10ms)
|
||||
set -sg escape-time 0
|
||||
|
||||
# Increase scrollback buffer
|
||||
set -g history-limit 50000
|
||||
|
||||
# Start windows and panes at 1, not 0
|
||||
set -g base-index 1
|
||||
setw -g pane-base-index 1
|
||||
|
||||
# Enable mouse support
|
||||
set -g mouse on
|
||||
|
||||
# Enable focus events for vim autoread
|
||||
set -g focus-events on
|
||||
|
||||
# Set terminal with proper colors
|
||||
set -g default-terminal "tmux-256color"
|
||||
set -as terminal-features ",xterm-256color:RGB"
|
||||
|
||||
# Aggressive resize for multi-client
|
||||
setw -g aggressive-resize on
|
||||
```
|
||||
|
||||
### Prefix Key Customization
|
||||
|
||||
The default prefix `C-b` is awkward. Common alternatives:
|
||||
|
||||
```tmux
|
||||
# Option 1: Change to Ctrl+a (common, but conflicts with readline)
|
||||
unbind C-b
|
||||
set -g prefix C-a
|
||||
bind-key C-a send-prefix
|
||||
|
||||
# Option 2: Use Alt+w or another comfortable combination
|
||||
set -g prefix M-w
|
||||
bind-key M-w send-prefix
|
||||
```
|
||||
|
||||
### Intuitive Split Commands
|
||||
|
||||
Replace the default `"` and `%` with visual separators:
|
||||
|
||||
```tmux
|
||||
# Split panes using | and -
|
||||
bind | split-window -h -c "#{pane_current_path}"
|
||||
bind - split-window -v -c "#{pane_current_path}"
|
||||
unbind '"'
|
||||
unbind %
|
||||
```
|
||||
|
||||
### Vim-Style Pane Navigation
|
||||
|
||||
```tmux
|
||||
# Switch panes using Alt+arrow without prefix
|
||||
bind -n M-Left select-pane -L
|
||||
bind -n M-Right select-pane -R
|
||||
bind -n M-Up select-pane -U
|
||||
bind -n M-Down select-pane -D
|
||||
|
||||
# Or use vim-style hjkl (requires prefix)
|
||||
bind h select-pane -L
|
||||
bind j select-pane -D
|
||||
bind k select-pane -U
|
||||
bind l select-pane -R
|
||||
```
|
||||
|
||||
### Copy Mode Configuration
|
||||
|
||||
```tmux
|
||||
# Use vi keys in copy mode
|
||||
setw -g mode-keys vi
|
||||
|
||||
# Vi-style copy bindings
|
||||
bind -T copy-mode-vi v send -X begin-selection
|
||||
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i" # Linux
|
||||
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy" # macOS
|
||||
```
|
||||
|
||||
### Quick Config Reload Binding
|
||||
|
||||
```tmux
|
||||
# Reload config with C-a r (or your prefix + r)
|
||||
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reloading vs. Restarting tmux
|
||||
|
||||
### Reloading Configuration (Preserves Sessions)
|
||||
|
||||
For most configuration changes, you can reload without losing sessions:
|
||||
|
||||
**Method 1: Command-line**
|
||||
```bash
|
||||
tmux source-file ~/.tmux.conf
|
||||
```
|
||||
|
||||
**Method 2: From within tmux**
|
||||
1. Press your prefix key (default `C-b`)
|
||||
2. Type `:` to open the command prompt
|
||||
3. Enter: `source-file ~/.tmux.conf`
|
||||
|
||||
**Method 3: Using a keybinding** (recommended)
|
||||
```tmux
|
||||
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"
|
||||
```
|
||||
Then press `C-b r` (or your configured prefix + r).
|
||||
|
||||
### When Full Restart is Required
|
||||
|
||||
Some changes require a complete tmux server restart:
|
||||
|
||||
- `extended-keys` and `extended-keys-format` changes
|
||||
- `default-terminal` changes
|
||||
- Server-level options like `message-limit`
|
||||
- Changes to terminal features
|
||||
|
||||
**Full restart procedure:**
|
||||
```bash
|
||||
# 1. Detach from current session (if attached)
|
||||
# Press: C-b d
|
||||
|
||||
# 2. Kill the tmux server (ends all sessions)
|
||||
tmux kill-server
|
||||
|
||||
# 3. Start fresh
|
||||
tmux
|
||||
```
|
||||
|
||||
**Alternative: Restart while preserving sessions** (tmux 3.2+)
|
||||
```bash
|
||||
# 1. Save session state (requires tmux-resurrect plugin)
|
||||
# Press: C-a C-s
|
||||
|
||||
# 2. Kill server
|
||||
tmux kill-server
|
||||
|
||||
# 3. Restart and restore
|
||||
tmux
|
||||
# Press: C-a C-r (to restore sessions)
|
||||
```
|
||||
|
||||
### Quick Reference: Reload vs. Restart
|
||||
|
||||
| Change Type | Reload OK? | Restart Required? |
|
||||
|-------------|------------|-------------------|
|
||||
| Keybindings | ✅ Yes | ❌ No |
|
||||
| Status bar styles | ✅ Yes | ❌ No |
|
||||
| Mouse settings | ✅ Yes | ❌ No |
|
||||
| Copy mode bindings | ✅ Yes | ❌ No |
|
||||
| `extended-keys` | ❌ No | ✅ Yes |
|
||||
| `extended-keys-format` | ❌ No | ✅ Yes |
|
||||
| `default-terminal` | ❌ No | ✅ Yes |
|
||||
| `escape-time` | ⚠️ Sometimes | ✅ Yes (for full effect) |
|
||||
|
||||
---
|
||||
|
||||
## Essential Configuration Reference
|
||||
|
||||
### Complete Production-Ready `~/.tmux.conf`
|
||||
|
||||
```tmux
|
||||
# ============================================
|
||||
# ESSENTIAL SETTINGS
|
||||
# ============================================
|
||||
|
||||
# Extended keys (required for modern applications)
|
||||
set -g extended-keys on
|
||||
set -g extended-keys-format csi-u
|
||||
|
||||
# Fix Vim ESC delay
|
||||
set -sg escape-time 0
|
||||
|
||||
# Increase scrollback buffer
|
||||
set -g history-limit 50000
|
||||
|
||||
# Start windows and panes at 1, not 0
|
||||
set -g base-index 1
|
||||
setw -g pane-base-index 1
|
||||
|
||||
# Enable mouse support
|
||||
set -g mouse on
|
||||
|
||||
# Enable focus events for vim autoread
|
||||
set -g focus-events on
|
||||
|
||||
# Set terminal with proper colors
|
||||
set -g default-terminal "tmux-256color"
|
||||
set -as terminal-features ",xterm-256color:RGB"
|
||||
|
||||
# Aggressive resize for multi-client
|
||||
setw -g aggressive-resize on
|
||||
|
||||
# ============================================
|
||||
# KEY BINDINGS
|
||||
# ============================================
|
||||
|
||||
# Change prefix to Ctrl+a (more ergonomic)
|
||||
unbind C-b
|
||||
set -g prefix C-a
|
||||
bind C-a send-prefix
|
||||
|
||||
# Reload config
|
||||
bind r source-file ~/.tmux.conf \; display "Config reloaded!"
|
||||
|
||||
# Better pane splitting (and keep current path)
|
||||
bind | split-window -h -c "#{pane_current_path}"
|
||||
bind - split-window -v -c "#{pane_current_path}"
|
||||
bind c new-window -c "#{pane_current_path}"
|
||||
|
||||
# Vim-style pane navigation
|
||||
bind h select-pane -L
|
||||
bind j select-pane -D
|
||||
bind k select-pane -U
|
||||
bind l select-pane -R
|
||||
|
||||
# Vim-style pane resizing
|
||||
bind -r H resize-pane -L 5
|
||||
bind -r J resize-pane -D 5
|
||||
bind -r K resize-pane -U 5
|
||||
bind -r L resize-pane -R 5
|
||||
|
||||
# ============================================
|
||||
# COPY MODE
|
||||
# ============================================
|
||||
|
||||
# Use vi keys
|
||||
setw -g mode-keys vi
|
||||
|
||||
# Vi-style copy bindings
|
||||
bind -T copy-mode-vi v send -X begin-selection
|
||||
# Linux:
|
||||
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"
|
||||
# macOS:
|
||||
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Modified keys still not working
|
||||
|
||||
1. **Check tmux version:**
|
||||
```bash
|
||||
tmux -V
|
||||
```
|
||||
Must be 3.5+ for `extended-keys-format csi-u`.
|
||||
|
||||
2. **Verify configuration is loaded:**
|
||||
```bash
|
||||
tmux show-options -g extended-keys
|
||||
tmux show-options -g extended-keys-format
|
||||
```
|
||||
|
||||
3. **Ensure terminal supports extended keys:**
|
||||
- Test in Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal
|
||||
- Some older terminals do not support the CSI-u format
|
||||
|
||||
4. **Full restart required:**
|
||||
```bash
|
||||
tmux kill-server
|
||||
tmux
|
||||
```
|
||||
|
||||
### Configuration changes not taking effect
|
||||
|
||||
- **Most changes:** Use `tmux source-file ~/.tmux.conf`
|
||||
- **Extended keys changes:** Must restart with `tmux kill-server`
|
||||
- **Check for errors:** Look at the first session created after restart for error messages
|
||||
|
||||
### Escape key delay
|
||||
|
||||
If you experience delay when pressing Escape:
|
||||
```tmux
|
||||
set -sg escape-time 0
|
||||
```
|
||||
|
||||
### Mouse scrolling not working in copy mode
|
||||
|
||||
```tmux
|
||||
bind -n WheelUpPane copy-mode -e
|
||||
bind -n WheelDownPane copy-mode -e
|
||||
```
|
||||
|
||||
### Clipboard not working
|
||||
|
||||
For Linux:
|
||||
```tmux
|
||||
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"
|
||||
```
|
||||
|
||||
For macOS:
|
||||
```tmux
|
||||
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [tmux Manual Page](https://man7.org/linux/man-pages/man1/tmux.1.html)
|
||||
- [tmux GitHub Wiki](https://github.com/tmux/tmux/wiki)
|
||||
- [Pi tmux Setup Documentation](https://pi.dev/docs/latest/tmux)
|
||||
|
||||
---
|
||||
|
||||
*Documentation last updated: June 2026*
|
||||
*Tested with tmux 3.6b*
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Agent Support Matrix
|
||||
description: Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- agents
|
||||
- compatibility
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Agent Support
|
||||
|
||||
The CLI supports **68+ agents**. It automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.
|
||||
|
||||
## Full Agent Path Table
|
||||
|
||||
| Agent | `--agent` | Project Path | Global Path |
|
||||
|-------|-----------|--------------|-------------|
|
||||
| Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
|
||||
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
|
||||
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
|
||||
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
|
||||
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
|
||||
| Cline, Dexto, Kimi Code CLI, Loaf, Warp, Zed | `cline`, `dexto`, `kimi-code-cli`, `loaf`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` |
|
||||
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
|
||||
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
|
||||
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
|
||||
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
|
||||
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
|
||||
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
|
||||
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
|
||||
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
|
||||
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
|
||||
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
|
||||
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
|
||||
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
|
||||
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
|
||||
| Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
|
||||
| Droid / Factory AI | `droid` | `.factory/skills/` | `~/.factory/skills/` |
|
||||
| Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` |
|
||||
| Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` |
|
||||
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
|
||||
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
|
||||
| Anthropic Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
|
||||
| Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` |
|
||||
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
|
||||
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
|
||||
| Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` |
|
||||
| Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` |
|
||||
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
|
||||
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
|
||||
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
|
||||
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
|
||||
| AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` |
|
||||
| IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` |
|
||||
| CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` |
|
||||
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
|
||||
| Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` |
|
||||
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
|
||||
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
|
||||
| Eve | `eve` | `agent/skills/` | N/A (project-only) |
|
||||
| ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` |
|
||||
| Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` |
|
||||
| inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` |
|
||||
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
|
||||
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
|
||||
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
|
||||
| Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` |
|
||||
| PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) |
|
||||
| Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` |
|
||||
| Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` |
|
||||
| Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` |
|
||||
| Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` |
|
||||
| Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` |
|
||||
| Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` |
|
||||
|
||||
> **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no configuration needed.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — Using the `--agent` flag with commands
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Commands
|
||||
description: Complete reference for all skills CLI commands — add, use, list, find, update, remove, init, experimental_install, experimental_sync.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- cli
|
||||
- commands
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Commands Reference
|
||||
|
||||
## `skills add` — Install Skills
|
||||
|
||||
Install skills from a source (git repo, URL, or local path) into your agent directories.
|
||||
|
||||
```bash
|
||||
npx skills add <source> [options]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-g, --global` | Install to user directory (`~/`) instead of project (`./`) |
|
||||
| `-a, --agent <agents...>` | Target specific agents |
|
||||
| `-s, --skill <skills...>` | Install specific skills by name. Use `'*'` for all. |
|
||||
| `-l, --list` | List available skills without installing |
|
||||
| `--copy` | Copy files instead of symlinking |
|
||||
| `-y, --yes` | Skip all confirmation prompts |
|
||||
| `--all` | Install all skills to all agents without prompts |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
npx skills add vercel-labs/agent-skills --list
|
||||
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
|
||||
npx skills add vercel-labs/agent-skills -a claude-code -a opencode
|
||||
npx skills add vercel-labs/agent-skills --all
|
||||
```
|
||||
|
||||
## `skills use` — Use Without Installing
|
||||
|
||||
Generate a prompt for one skill, or start a supported coding agent interactively with the skill loaded.
|
||||
|
||||
```bash
|
||||
npx skills use <source> [options]
|
||||
# Generate prompt only
|
||||
npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
|
||||
# Use with specific agent
|
||||
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code
|
||||
```
|
||||
|
||||
## `skills list` (alias: `ls`) — List Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills list
|
||||
npx skills ls -g # Global only
|
||||
npx skills ls -a claude-code -a cursor
|
||||
```
|
||||
|
||||
## `skills find` — Search for Skills
|
||||
|
||||
```bash
|
||||
npx skills find # Interactive search
|
||||
npx skills find typescript # Search by keyword
|
||||
npx skills find react --owner vercel
|
||||
```
|
||||
|
||||
## `skills update` — Update Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills update # All skills (interactive)
|
||||
npx skills update my-skill # Single skill
|
||||
npx skills update -g # Global only
|
||||
npx skills update -y # Non-interactive
|
||||
```
|
||||
|
||||
## `skills remove` (alias: `rm`) — Remove Installed Skills
|
||||
|
||||
```bash
|
||||
npx skills remove # Interactive
|
||||
npx skills remove web-design-guidelines
|
||||
npx skills remove --all # Remove everything
|
||||
```
|
||||
|
||||
## `skills init` — Create a New SKILL.md Template
|
||||
|
||||
```bash
|
||||
npx skills init # In current directory
|
||||
npx skills init my-skill # In a subdirectory
|
||||
```
|
||||
|
||||
## `skills experimental_install` — Restore from Lock File
|
||||
|
||||
```bash
|
||||
npx skills experimental_install
|
||||
```
|
||||
|
||||
## Aliases
|
||||
|
||||
| Alias | Full Command |
|
||||
|-------|-------------|
|
||||
| `skills a` | `skills add` |
|
||||
| `skills i` | `skills experimental_install` |
|
||||
| `skills install` (no args) | `skills experimental_install` |
|
||||
| `skills ls` | `skills list` |
|
||||
| `skills rm` | `skills remove` |
|
||||
|
||||
## Related
|
||||
|
||||
* [Source Formats](/tools/vercel-labs-skills/source-formats.md) — What sources you can use with add/use
|
||||
* [Installation Scope](/tools/vercel-labs-skills/installation-scope.md) — Global vs project
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Environment Variables
|
||||
description: Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TRACK.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- environment
|
||||
- telemetry
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
|
||||
| `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
|
||||
| `DO_NOT_TRACK` | Alternative way to disable telemetry |
|
||||
|
||||
```bash
|
||||
# Install internal skills
|
||||
INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
|
||||
```
|
||||
|
||||
## Telemetry
|
||||
|
||||
The CLI collects anonymous usage data to help improve the tool. No personal information is collected. Telemetry is automatically disabled in CI environments.
|
||||
|
||||
## Related
|
||||
|
||||
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — `metadata.internal: true`
|
||||
@@ -0,0 +1,18 @@
|
||||
# Vercel Labs `skills` CLI
|
||||
|
||||
Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global).
|
||||
|
||||
## Concept Files
|
||||
|
||||
| File | Type | Description |
|
||||
|------|------|-------------|
|
||||
| [agent-support.md](agent-support.md) | reference | Complete list of 68+ supported coding agents, their --agent flags, and instal... |
|
||||
| [commands.md](commands.md) | reference | Complete reference for all skills CLI commands — add, use, list, find, update... |
|
||||
| [env-variables.md](env-variables.md) | reference | Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TR... |
|
||||
| [installation-scope.md](installation-scope.md) | reference | Project vs global installation, symlink vs copy methods. |
|
||||
| [lock-file.md](lock-file.md) | reference | Version pinning and update checking via global and local lock files (.skill-l... |
|
||||
| [related-links.md](related-links.md) | reference | Links to the Agent Skills specification, skills directory, integration guide,... |
|
||||
| [skill-discovery.md](skill-discovery.md) | reference | How the skills CLI discovers SKILL.md files in repositories — flat layout, ca... |
|
||||
| [skill-format.md](skill-format.md) | reference | The required frontmatter fields, optional fields, internal skills, and struct... |
|
||||
| [source-formats.md](source-formats.md) | reference | All accepted source formats for skills add and use — GitHub shorthand, full U... |
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Installation Scope
|
||||
description: Project vs global installation, symlink vs copy methods.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- installation
|
||||
- scope
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Installation Scope
|
||||
|
||||
## Project vs Global
|
||||
|
||||
| Scope | Flag | Location | Use Case |
|
||||
|-------|------|----------|----------|
|
||||
| **Project** | _(default)_ | `./<agent>/skills/` | Committed with your project, shared with team |
|
||||
| **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
|
||||
|
||||
## Symlink vs Copy
|
||||
|
||||
When installing interactively, you can choose:
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| **Symlink** _(Recommended)_ | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
|
||||
| **Copy** | Creates independent copies for each agent. Use when symlinks are not supported. |
|
||||
|
||||
Use `--copy` to force copy mode.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add, use, list, remove commands
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Lock File System
|
||||
description: Version pinning and update checking via global and local lock files (.skill-lock.json and skills-lock.json).
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- lockfile
|
||||
- versioning
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Lock File System
|
||||
|
||||
The `skills` CLI uses a lock file system for version pinning and update checking.
|
||||
|
||||
## Lock File Locations
|
||||
|
||||
| Type | Path | Scope |
|
||||
|------|------|-------|
|
||||
| **Global lock** | `~/.agents/.skill-lock.json` | Global (user-wide) |
|
||||
| **Local lock** | `skills-lock.json` | Project (checked into version control) |
|
||||
|
||||
## How `skills check` and `skills update` Work
|
||||
|
||||
1. Read `~/.agents/.skill-lock.json` for installed skills
|
||||
2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath`
|
||||
3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`
|
||||
- Optional auth token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`
|
||||
4. `fetchSkillFolderHash` calls GitHub Trees API (`/git/trees/<branch>?recursive=1` for `main`, then `master` fallback)
|
||||
5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available
|
||||
6. `skills update` reinstalls changed skills by invoking the current CLI directly
|
||||
|
||||
## Lock File Format
|
||||
|
||||
- **Version:** v3
|
||||
- **Key field:** `skillFolderHash` — GitHub tree SHA for the skill folder
|
||||
- **Compatibility:** If reading an older lock file version, it is wiped. Users must reinstall skills to populate the new format.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — check, update, experimental_install
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
type: reference
|
||||
title: Vercel Labs Skills — Related Links
|
||||
description: Links to the Agent Skills specification, skills directory, integration guide, and agent-specific skill documentation.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- links
|
||||
- resources
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Related Links
|
||||
|
||||
## Specification & Ecosystem
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| [Agent Skills Specification](https://agentskills.io) | agentskills.io/specification |
|
||||
| [Skills Directory](https://skills.sh) | skills.sh |
|
||||
| [Agent Skills Integration Guide](https://agentskills.io/integrate-skills) | agentskills.io/integrate-skills |
|
||||
| [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills) | github.com/vercel-labs/agent-skills |
|
||||
|
||||
## Agent-Specific Skill Documentation
|
||||
|
||||
| Agent | Documentation |
|
||||
|-------|--------------|
|
||||
| Amp | [Amp Skills Documentation](https://ampcode.com/manual#agent-skills) |
|
||||
| Claude Code | [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) |
|
||||
| Codex | [Codex Skills Documentation](https://developers.openai.com/codex/skills) (url unreachable 2026-08-28) |
|
||||
| Cursor | [Cursor Skills Documentation](https://cursor.com/docs/context/skills) |
|
||||
| Gemini CLI | [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/) (url unreachable 2026-08-28) |
|
||||
| GitHub Copilot | [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) |
|
||||
| OpenCode | [OpenCode Skills Documentation](https://opencode.ai/docs/skills) (url unreachable 2026-08-28) |
|
||||
| OpenHands | [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills) (url unreachable 2026-08-28) |
|
||||
| Pi | [Pi Skills Documentation](https://github.com/earendil-works/pi) |
|
||||
| Roo Code | [Roo Code Skills Documentation](https://docs.roocode.com/features/skills) (url unreachable 2026-08-28) |
|
||||
| Windsurf | [Windsurf](https://www.codeium.com/windsurf) (url unreachable 2026-08-28) |
|
||||
|
||||
## Related
|
||||
|
||||
* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — Full list of 68+ supported agents
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Skill Discovery
|
||||
description: How the skills CLI discovers SKILL.md files in repositories — flat layout, catalog layout, plugin manifests.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- discovery
|
||||
- repository
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Skill Discovery
|
||||
|
||||
The CLI searches for skills in these locations within a repository. Each skill container directory is walked:
|
||||
|
||||
- **One level deep** for the common flat layout: `skills/<name>/SKILL.md`
|
||||
- **One extra level deep** for catalog layouts: `skills/<category>/<name>/SKILL.md`
|
||||
|
||||
A `SKILL.md` discovered at the shallower level shadows anything nested below it. Use `--full-depth` to also discover `SKILL.md` files outside these container directories.
|
||||
|
||||
## Standard Discovery Locations
|
||||
|
||||
- `SKILL.md` in root directory (if present)
|
||||
- `skills/`
|
||||
- `skills/.curated/`
|
||||
- `skills/.experimental/`
|
||||
- `skills/.system/`
|
||||
- `.agents/skills/`
|
||||
- `.claude/skills/`
|
||||
- `.goose/skills/`
|
||||
- `.openhands/skills/`
|
||||
- `.pi/skills/`
|
||||
- And many more per-agent directories (see [Agent Support](/tools/vercel-labs-skills/agent-support.md))
|
||||
|
||||
## Plugin Manifest Discovery
|
||||
|
||||
If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered. This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
|
||||
|
||||
Example `marketplace.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": { "pluginRoot": "./plugins" },
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "my-plugin",
|
||||
"skills": ["./skills/review", "./skills/test"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Skill paths declared in a manifest are searched at their declared depth.
|
||||
|
||||
If no skills are found in standard locations, a **recursive search** is performed as a fallback.
|
||||
|
||||
## Related
|
||||
|
||||
* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — What a discovered skill looks like
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
type: reference
|
||||
title: SKILL.md Format
|
||||
description: The required frontmatter fields, optional fields, internal skills, and structure for SKILL.md files.
|
||||
tags:
|
||||
- skills
|
||||
- SKILL.md
|
||||
- format
|
||||
- unverified
|
||||
verified: 2026-08-28
|
||||
|
||||
# SKILL.md Format
|
||||
|
||||
Skills are directories containing a `SKILL.md` file with YAML frontmatter.
|
||||
|
||||
## Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does and when to use it
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Instructions for the agent to follow when this skill is activated.
|
||||
|
||||
## When to Use
|
||||
|
||||
Describe the scenarios where this skill is used.
|
||||
|
||||
## Steps
|
||||
|
||||
1. First, do this
|
||||
2. Then, do that
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `name` | string | Unique identifier (lowercase, hyphens allowed) |
|
||||
| `description` | string | Brief explanation of what the skill does |
|
||||
|
||||
## Optional Frontmatter Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `metadata.internal` | boolean | Set to `true` to hide the skill from normal discovery. Requires `INSTALL_INTERNAL_SKILLS=1` |
|
||||
| `license` | string | License name or reference to bundled file |
|
||||
| `compatibility` | string | Environment requirements (max 500 chars) |
|
||||
| `metadata` | object | Arbitrary key-value mapping |
|
||||
| `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental) |
|
||||
| `disable-model-invocation` | boolean | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly |
|
||||
|
||||
## Internal Skills Example
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-internal-skill
|
||||
description: An internal skill not shown by default
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are discovered in repos
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — `skills init` to create new skills
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
type: reference
|
||||
title: Skills CLI Source Formats
|
||||
description: All accepted source formats for skills add and use — GitHub shorthand, full URLs, GitLab, git URLs, local paths.
|
||||
tags:
|
||||
- unverified
|
||||
- skills
|
||||
- sources
|
||||
- git
|
||||
timestamp: 2026-07-18
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
# Source Formats
|
||||
|
||||
The `skills` CLI accepts multiple source formats for the `add` and `use` commands:
|
||||
|
||||
```bash
|
||||
# GitHub shorthand (owner/repo)
|
||||
npx skills add vercel-labs/agent-skills
|
||||
|
||||
# Full GitHub URL
|
||||
npx skills add https://github.com/vercel-labs/agent-skills
|
||||
|
||||
# Direct path to a skill in a repo
|
||||
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
|
||||
|
||||
# GitLab URL
|
||||
npx skills add https://gitlab.com/org/repo
|
||||
|
||||
# Any git URL
|
||||
npx skills add git@github.com:vercel-labs/agent-skills.git
|
||||
|
||||
# Local path
|
||||
npx skills add ./my-local-skills
|
||||
```
|
||||
|
||||
The source parser (`src/source-parser.ts`) handles all these formats, cloning repos as needed and resolving skill directories.
|
||||
|
||||
## Related
|
||||
|
||||
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands
|
||||
* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are found within repos
|
||||
Reference in New Issue
Block a user