Incipio

Incipio is a command-line launcher application built with Go, featuring a modular architecture and a terminal user interface powered by Bubble Tea.

Features

• Modular Design: The application is structured with distinct plugins for different functionalities.
• Terminal User Interface: Interactive TUI built with Bubble Tea and styled with Lipgloss.
• Plugins: Comes with several useful plugins out-of-the-box:
  • App Launcher: Finds and launches desktop applications.
  • Calculator: Performs basic arithmetic calculations.
  • Plugin Manager: Allows enabling/disabling optional plugins.
  • Wikipedia Search: Searches Wikipedia for articles (example plugin, located in examples/plugins/).
  • Nix Shell: Provides an interface to launch applications with nix shell (example plugin, located in examples/plugins/).

Warning

Nix Shell Plugin: Requires the nix-locate command (part of the nix-index package) to be installed and available in your PATH. Generating the nix-locate database using nix-index is also required for it to function correctly.

Usage

Configuring Sway Keybinding

To launch Incipio using a keyboard shortcut in the Sway window manager, add the following line to your Sway configuration file:

# ~/.config/sway/config

# Set your terminal (e.g., wezterm, kitty)
set $term wezterm start

# Optional: Make the launcher window floating
for_window [app_id="^incipio$"] floating enable, sticky enable, resize set 50 ppt 60 ppt

# Define the command to launch Incipio within the terminal
#    Use --class or --app-id depending on your terminal and preference for matching the window rule.
#    Use the --plugins flag to specify which plugins to load (comma-separated).
set $menu $term --class incipio-launcher -e incipio
# Example using foot terminal with app-id:
# set $menu foot --app-id incipio-launcher -e incipio

bindsym $mod+d exec $menu

Plugins

Incipio features a flexible plugin system that allows for extending its functionality. Plugins can be either built-in or loaded dynamically at runtime using Yaegi.

Plugin Types

• Built-in Plugins: These are compiled directly into the Incipio binary and are always available. Core functionalities like the App Launcher (internal/plugins/applauncher/launcher.go), Calculator (internal/plugins/calculator/calculator.go), and the Plugin Manager itself (internal/plugins/pluginmanager/pluginmanager.go) are implemented as built-in plugins.
• Yaegi Plugins: These are external Go files (.go) that are interpreted at runtime. This allows users to add custom functionality without recompiling Incipio.
  • Place your custom Yaegi plugins in ~/.config/incipio/plugins/.
  • Example Yaegi plugins can be found in the examples/plugins/ directory of this repository (e.g., hello.go, wikipedia.go, nixshell.go). These serve as templates for creating your own.

Enabling Optional Plugins

Some plugins are optional and can be enabled at startup using the --plugins command-line flag. Provide a comma-separated list of plugin flags. For example:

incipio --plugins=wikipedia,nixshell

Building

To build Incipio from source, you need Go installed (version 1.24.2).

git clone https://github.com/barab-i/incipio
cd incipio
go build ./cmd/incipio

Installing

1. Using nix profile install (User Environment)

This installs the application into your user profile from the official GitHub repository:

nix profile install github:barab-i/incipio

If you have cloned the repository locally (e.g., for development or to test changes), you can install from the local flake:

# Navigate to the cloned directory 
nix profile install .#incipio

2. Adding to NixOS Configuration (System-wide)

If you are using NixOS, you can add Incipio to your system configuration (/etc/nixos/configuration.nix or wherever your configuration resides).

First, add the flake as an input in your main flake.nix:

# filepath: /path/to/your/flake.nix
{
  description = "My NixOS Configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    # Add incipio flake input
    incipio = {
      url = "github:barab-i/incipio";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    # ... other inputs like home-manager etc.
  };

  outputs = { self, nixpkgs, incipio, ... }@inputs: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      # ... system configuration ...
      specialArgs = { inherit inputs; }; # Pass inputs to modules
      modules = [
        ./configuration.nix
        # ... other modules
      ];
    };
  };
}

Then, add the package to your environment.systemPackages in configuration.nix:

# filepath: /path/to/your/configuration.nix
{ config, pkgs, inputs, ... }:

{
  # ... other configuration options ...

  environment.systemPackages = [
    # ... other packages ...
    inputs.incipio.packages.${pkgs.system}.default
  ];

  # ... rest of configuration ...
}

3. Adding to Home Manager Configuration

If you use Home Manager, either standalone or as a NixOS module, you can add Incipio to your user environment.

Add the flake input similarly to the NixOS example above (either in your system flake.nix if using the module, or your standalone home-manager flake.nix).

Then, add the package to home.packages in your home.nix:

# filepath: /path/to/your/home.nix
{ config, pkgs, inputs, ... }:

{
  # ... other home-manager options ...

  home.packages = [
    # ... other packages ...
    inputs.incipio.packages.${pkgs.system}.default
  ];

  # ... rest of configuration ...
}

Theming

Incipio allows customization of its appearance through theme files based on the Base16 Styling Guidelines.

The application looks for a theme.yaml file in the XDG config directory (~/.config/incipio/theme.yaml by default). You can place a Base16 theme definition in this file to change the application's colors.

A wide variety of pre-built Base16 themes can be found at tinted-theming/base16-schemes.

Roadmap

Done

• Modular plugin architecture (internal/app/plugin_manager.go, pkgs/plugin/interface.go)
• Terminal User Interface with Bubble Tea (internal/app/model.go)
• Built-in plugins:
  • App Launcher (internal/plugins/applauncher/launcher.go)
  • Calculator (internal/plugins/calculator/calculator.go)
  • Plugin Manager (view status) (internal/plugins/pluginmanager/pluginmanager.go)
• Dynamic plugin loading with Yaegi (internal/yaegi/yaegi.go)
• Base16 Theming support (internal/theme/theme.go)
• Command-line flag for enabling optional plugins (cmd/incipio/main.go)

To Do

• Detailed documentation for creating custom Yaegi plugins.
• More built-in plugins (e.g., File Browser, Clipboard Manager).
• Persistent configuration for plugins (beyond CLI flags).
• UI for enabling/disabling/configuring plugins directly within the Plugin Manager plugin.
• Plugin Manager Plugin: Add option to discover and install Yaegi plugins from a curated online repository or user-defined URLs.
• Asynchronous plugin loading to improve startup time.
• More sophisticated layout options for plugins that render their own views.