📺 Interactive Capsule in Action

╭─ kapsel [pwsh] ~/Projects/Kapsel 14:32:05
╰─ ❯ git checkout -b feature/dynamic-specs
✔ 0  git checkout -b feature/dynamic-specs  ⏱ 24ms

Wrap complexity, expose simplicity. Run your native shell executables as usual, while enjoying automatic command translation, inline suggestions, rich completion specs, and a modular toolchain—all sandboxed within ~/.kapsel/.

💡 Why Kapsel?

Switching between operating systems often leads to broken muscle memory, cluttered dotfiles, and fractured autocompletion setups. Kapsel bridges this gap with a non-invasive capsule layer:

✨ Features

• 🌐 Cross-Platform Command Consistency: Type standard commands (ls -la, cat, rm -rf, grep) naturally in any terminal, automatically translated to host-native primitives without hijacking host built-ins.
• ⚡ Context-Aware Autocompletion: Integrated with Carapace to deliver multi-level argument and context completions (Git branches, Docker images, npm scripts) across PowerShell, Bash, and Zsh.
• 🛡️ Zero-Pollution Sandboxing: Everything (binaries, SQLite history, declarative specs, plugins, and logs) resides inside ~/.kapsel/. Your host shell configuration files remain completely untouched.
• 🧩 Curated Plugin Ecosystem: Access powerful developer utilities (zoxide, mise, chsrc, pueue, AI assistants) directly through the unified kps command.
• 🎨 Modern Card-Framed Aesthetics: Clean visual command card framing with exit code badges (✔ 0 / ✘ 1), execution stopwatch timing, and native i18n support across 7 languages.

🚀 Quick Start

Launch the interactive capsule shell:

kapsel

Inside Kapsel, commands run natively with enhanced feedback:

# 1. Native pass-through with timing & exit code card
git status
docker ps

# 2. Universal command translation on any OS
rm -rf ./temp_dir
cat package.json

# 3. Use built-in plugins anytime
kps portal work        # Jump to directory (zoxide)
kps ai "explain git rebase"  # Ask terminal AI assistant
kps shore get          # Auto-select fastest package mirrors

# 4. Inspect capsule state
kps status

One-Shot Execution: You can also invoke Kapsel tools directly from your regular shell using kps <command> (e.g. kps portal, kps status, kps ai).

🧩 Built-in Plugins

Kapsel comes pre-configured with 11 decoupled, official plugins under the kps namespace:

📦 Installation

Recommended (pipx / pip)

# Isolated installation via pipx (recommended)
pipx install kapsel-cli

# Or standard pip
pip install --upgrade kapsel-cli

One-Line Automated Installers

Quick bootstrap scripts that auto-detect your OS and configure completions:

# macOS & Linux:
curl -fsSL https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.sh | bash

# Windows (PowerShell):
irm https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.ps1 | iex

Other Installation Options

• Standalone Precompiled Binaries: Download ready-to-run releases from GitHub Releases.
• Package Managers: Available on Scoop (scoop install kapsel), Homebrew, and Debian/Ubuntu .deb.
• Build from Source: git clone https://github.com/MrEiu/Kapsel.git && cd Kapsel && pip install -e .

👉 For China mirror acceleration and full platform package manager details, see docs/INSTALLATION.md.

⚙️ Configuration

Kapsel stores its configuration in ~/.kapsel/config.yaml. Manage settings directly from your terminal:

# View configuration dashboard
kps config

# Open configuration file in external editor
kps config edit

# Adjust settings on the fly
kps config set ui.enable_banner false
kps config set interaction.autosuggest_sensitivity 0.2

🏛️ Architecture & Sandboxing

Kapsel follows a Zero-Pollution Principle. All runtime state is strictly contained:

~/.kapsel/
├── config.yaml          # System-wide UI configuration, themes, and interaction settings
├── history.db           # Persistent SQLite database storing command history and stats
├── bin/                 # User-space standalone binary tools (carapace, zoxide, mise...)
├── specs/               # Declarative autocompletion YAML specifications
├── plugins/             # Installed official and community plugin extensions
└── logs/                # Diagnostic logs and session metrics

• Dual-State Engine: Native executables run directly via host subshell passthrough; capsule utilities run via the unified kps registry.
• Collision Sentinel: Ensures native shell built-ins (e.g. PowerShell's Get-Alias, Get-Help) are never intercepted or hijacked.
• Isolated Plugins: Plugins run independently, ensuring third-party extensions cannot crash the core shell.

🧪 Development & Testing

# Clone the repository
git clone https://github.com/MrEiu/Kapsel.git
cd Kapsel

# Install editable package with test dependencies
pip install -e ".[test]"

# Run unit test suite
pytest tests/ -v

📄 License

Distributed under the MIT License. Built by MrEiu and open-source contributors.