Shizuku App Manager

This skill helps create and manage shizuku application configurations.

What This Skill Does

When invoked, this skill helps you:

1. Scaffold new apps - Create complete directory structure and registration
2. Add template files - Create and manage .tmpl files in app contents
3. Modify existing apps - Update app configurations and template data
4. Add installer logic - Implement Install() method for Homebrew packages

App Structure Overview

Apps live under apps/ in one of three category directories:

• apps/languages/ — language toolchains (e.g. golang, rust)
• apps/programs/ — regular programs (e.g. helix, kitty)
• apps/agents/ — agentic coding tools (e.g. claude)

Each shizuku app follows this pattern:

apps/{category}/{appName}/
├── {appName}.go           # App struct with methods
└── contents/              # Template files and assets (optional, embedded via //go:embed)
    ├── file.conf          # Regular files (copied as-is)
    └── file.tmpl          # Go templates (processed)

Modern App Architecture

Apps use an interface-based design with optional capabilities:

Core Interface (Required)

All apps must implement the App interface:

• Name() string - Returns the app name
• Enabled(cfg *config.Config) bool - Checks if app is enabled

Optional Interfaces

Apps can optionally implement:

• FileSyncer - For apps that sync configuration files
  • Sync(outDir string, cfg *config.Config) error
• FileGenerator - For diff support without syncing side effects
  • Generate(outDir string, cfg *config.Config) (*app.GenerateResult, error)
• Installer - For apps that need installation
  • Install(cfg *config.Config) error
• EnvProvider - For apps that provide environment variables/aliases
  • Env() (*app.EnvSetup, error)
• AgentConfigProvider - For apps that need agentic tools (LSP plugins, sandbox hosts/paths) to support them
  • AgentConfig() app.AgentConfig

Creating a New App

Step 1: Gather Requirements

Ask the user:

1. Category - Which category does this app belong to?
   • languages/ - language toolchains (e.g. golang, rust)
   • programs/ - regular programs (e.g. helix, kitty)
   • agents/ - agentic coding tools (e.g. claude)
2. App name - What is the name of the application? (e.g., "glow", "alacritty")
3. Default enabled - Should this app be enabled by default? (most apps: true, optional services: false)
4. Installation - Does the app need installation via Homebrew? (y/n)
   • If yes: package name, cask vs formula, any taps needed?
5. File syncing - Does the app need to sync configuration files? (y/n)
   • If yes: destination path (e.g., "~/.config/glow/")
6. Template data - Does the app need any template variables? (y/n)
7. Remote files - Does the app need to download any remote resources like plugins? (y/n)
8. Environment - Does the app need environment variables or aliases? (y/n)
9. Agent config - Does the app need agentic tools to install LSP plugins, allow specific sandbox hosts, or write to specific paths? (y/n)

Step 2: Create Directory Structure

mkdir -p apps/{category}/{appName}
# Only create contents/ if the app will sync files
mkdir -p apps/{category}/{appName}/contents

Step 3: Create the Go File

Create apps/{category}/{appName}/{appName}.go with the appropriate template:

Minimal App (No File Syncing)

package {appName}

import (
    "github.com/eleonorayaya/shizuku/config"
)

type App struct{}

func New() *App {
    return &App{}
}

func (a *App) Name() string {
    return "{appName}"
}

func (a *App) Enabled(cfg *config.Config) bool {
    return cfg.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

App with Installation

package {appName}

import (
    "fmt"

    "github.com/eleonorayaya/shizuku/config"
    "github.com/eleonorayaya/shizuku/util"
)

type App struct{}

func New() *App {
    return &App{}
}

func (a *App) Name() string {
    return "{appName}"
}

func (a *App) Enabled(cfg *config.Config) bool {
    return cfg.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

func (a *App) Install(cfg *config.Config) error {
    // For Homebrew formula
    if err := util.InstallBrewPackage("{packageName}"); err != nil {
        return fmt.Errorf("failed to install {packageName}: %w", err)
    }

    // For Homebrew cask
    // if err := util.InstallCask("{caskName}"); err != nil {
    //     return fmt.Errorf("failed to install {caskName}: %w", err)
    // }

    // For custom tap
    // if err := util.AddTap("{tapName}"); err != nil {
    //     return fmt.Errorf("failed to add tap: %w", err)
    // }

    return nil
}

App with File Syncing

package {appName}

import (
    "fmt"

    "github.com/eleonorayaya/shizuku/app"
    "github.com/eleonorayaya/shizuku/config"
)

type App struct{}

func New() *App {
    return &App{}
}

func (a *App) Name() string {
    return "{appName}"
}

func (a *App) Enabled(cfg *config.Config) bool {
    return cfg.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

//go:embed all:contents
var contents embed.FS

func (a *App) Sync(outDir string, cfg *config.Config) error {
    data := map[string]any{}

    fileMap, err := app.GenerateAppFiles("{appName}", contents, data, outDir)
    if err != nil {
        return fmt.Errorf("failed to generate app files: %w", err)
    }

    if err := app.SyncAppFiles(fileMap, "{destinationPath}"); err != nil {
        return fmt.Errorf("failed to sync app files: %w", err)
    }

    return nil
}

App with Remote Files

func (a *App) Sync(outDir string, cfg *config.Config) error {
    data := map[string]any{}

    fileMap, err := app.GenerateAppFiles("{appName}", contents, data, outDir)
    if err != nil {
        return fmt.Errorf("failed to generate app files: %w", err)
    }

    remoteFiles := map[string]string{
        "plugins/file.wasm": "https://example.com/file.wasm",
    }
    pluginMap, err := app.FetchRemoteAppFiles(outDir, "{appName}", remoteFiles)
    if err != nil {
        return fmt.Errorf("failed to fetch remote files: %w", err)
    }
    maps.Copy(fileMap, pluginMap)

    if err := app.SyncAppFiles(fileMap, "{destinationPath}"); err != nil {
        return fmt.Errorf("failed to sync app files: %w", err)
    }

    return nil
}

Note: If using maps.Copy, add import: "maps"

App with Environment Variables

func (a *App) Env() (*app.EnvSetup, error) {
    return &app.EnvSetup{
        Variables: []app.EnvVar{
            {Key: "EDITOR", Value: "hx"},
        },
        Aliases: []app.Alias{
            {Name: "ls", Command: "lsd"},
        },
    }, nil
}

Step 4: Register the App

1. Open the consumer binary at examples/eleonora/main.go
2. Add import: "github.com/eleonorayaya/shizuku/apps/{category}/{appName}"
3. Add the app to the matching AddLanguages / AddPrograms / AddAgent call in newBuilder():

   {appName}.New(),
   

IMPORTANT: Apps are registered in the consumer binary via the shizuku Builder — not in a central registry. The shizuku library itself does not know about any specific apps.

Step 4b: Add AgentConfig (optional)

If the app needs agentic tools to install LSP plugins, allow specific sandbox domains, or write to specific paths, implement AgentConfigProvider:

func (a *App) AgentConfig() app.AgentConfig {
    return app.AgentConfig{
        Plugins:               []string{"my-lsp@claude-plugins-official"},
        SandboxAllowedDomains: []string{"my-package-registry.example"},
        SandboxAllowWrite:     []string{"~/.cache/my-tool"},
    }
}

The sync orchestrator collects this from every enabled app and passes it to agents (e.g. claude) via a SyncContext. No agent code needs to change when a new app declares its requirements.

Step 5: Build and Test

task build
task run -- list        # Verify app appears
task run -- install     # Test installation (if implemented)
task run -- sync        # Test file syncing (if implemented)

Configuration System

Checking if App is Enabled

All apps implement Enabled() which checks the config:

func (a *App) Enabled(cfg *config.Config) bool {
    return cfg.GetAppConfigBool(a.Name(), "enabled", true)  // default: true
}

• Most apps default to true (core functionality)
• Optional services default to false (protonpass, protonvpn, sfsymbols)

User Config Example

Users can control apps in ~/.config/shizuku/shizuku.yml:

apps:
  helix:
    enabled: false
  terraform:
    enabled: false
  protonpass:
    enabled: true

Using Other Config Values

Use cfg.GetAppConfigBool() for boolean values:

useNerdFont := cfg.GetAppConfigBool(a.Name(), "nerd_font", true)

Use cfg.GetAppConfig() for other types:

theme, ok := cfg.GetAppConfig(a.Name(), "theme")
if ok {
    themeStr, ok := theme.(string)
    if ok {
        data["Theme"] = themeStr
    }
}

Adding Template Files

When the user wants to add configuration files to an app:

1. Ask for file path - Relative to contents/ directory (e.g., "config.conf")
2. Ask if it's a template - Does it need variable substitution? (y/n)
3. Create the file - If template, use .tmpl extension
4. Update template data - If template, add necessary variables to the data map in the Sync method

Template Example

If creating contents/config.conf.tmpl:

# {{ .AppName }} Configuration
theme = "{{ .Theme }}"

Update the Sync method:

data := map[string]any{
    "AppName": "MyApp",
    "Theme":   "monade",
}

Modifying Existing Apps

When modifying an app:

1. Read the current Go file to understand existing structure
2. List contents/ to see existing files (if applicable)
3. Make requested changes while preserving the app pattern
4. Ensure all required interfaces are still implemented

Important Notes

• No comments - Don't add comments unless explicitly requested (per CLAUDE.md)
• Error wrapping - Always use fmt.Errorf("context: %w", err) pattern
• Template extension - .tmpl files are processed, extension is removed in output
• File syncing - SyncAppFiles handles directory creation and file copying
• App struct - Always use type App struct{} with New() *App constructor
• Interface implementation - Implement only the interfaces the app needs
• Registration - Apps are registered in the consumer binary (examples/eleonora/main.go) via AddLanguages/AddPrograms/AddAgent on the Builder, not in a central registry

Installation Utilities

Available Homebrew utilities in util/homebrew.go:

• InstallBrewPackage(packageName string) error - Install formula (auto-checks if exists)
• InstallCask(caskName string) error - Install cask (auto-checks if exists)
• AddTap(tapName string) error - Add Homebrew tap (auto-checks if exists)
• BrewPackageExists(packageName string) (bool, error) - Check if package is installed

All utilities are idempotent - safe to call multiple times.

Workflow

1. Use TodoWrite to track the scaffolding steps
2. Ask clarifying questions using AskUserQuestion (always ask the category first)
3. Create all necessary files in apps/{category}/{appName}/
4. Register the app in examples/eleonora/main.go under the matching Builder call
5. Suggest running task build and task run -- list to verify

Examples

Simple App (Installation Only)

• App: rust
• Default enabled: true
• Installation: InstallBrewPackage("rustup")
• No file syncing

App with File Syncing

• App: helix
• Default enabled: true
• Installation: pkg.Install(pkg.Spec{Brew: "helix", ...})
• Syncs to: ~/.config/helix/
• Provides: Environment variables (EDITOR=hx, VISUAL=hx)

Optional Service App

• App: protonpass
• Default enabled: false
• Installation: InstallCask("proton-pass")
• No file syncing

App with Templates

• App: sketchybar
• Default enabled: true
• Installation: Tap + formula
• Syncs to: ~/.config/sketchybar/
• Templates: Uses {{ .Theme }} and other variables

App with Remote Files

• App: terminal
• Default enabled: true
• Installation: pkg.Install for zsh and oh-my-posh
• Syncs to: ~/.config/ohmyposh/
• Remote: Clones the zsh-vi-mode plugin from GitHub

App with Custom Installer

• App: kitty
• Default enabled: true
• Installation: Uses curl installation script (not Homebrew)
• Syncs to: ~/.config/kitty/