Krusty Shell

Krusty is a modern, feature-rich shell built with TypeScript and Bun. It provides a familiar shell experience with enhanced features, intelligent auto-suggestions, comprehensive scripting support, and extensive customization options for developers.

Features

• 🚀 Performance: Built on Bun for lightning-fast execution
• 🧠 Smart completion: Context-aware command/file completions with caching
• 💡 Auto-suggestions: Intelligent inline suggestions with history integration
• 🧩 Aliases & functions: Powerful aliasing and shell functions with expansion
• 🧵 Pipelines & redirections: Full |, >, >>, 2>&1, here-strings, process substitution
• 🧭 Job control: Advanced job management with Ctrl+Z, Ctrl+C, jobs, bg, fg, kill, wait
• 📜 Scripting: Complete scripting engine with control flow, functions, and error handling
• 🎨 Themes: Highly configurable prompts with Git status and runtime detection
• 🔌 Plugins: Extensible plugin system with hooks and lifecycle management

Quick start

# Install Krusty globally
bun add -g krusty
npm install -g krusty
yarn global add krusty
pnpm global add krusty

# Start the shell
krusty

# Or run directly with Bun
bunx krusty

Built-in Commands

Krusty ships with a comprehensive set of built-ins. Run help for details.

Core shell

• alias, unalias — manage aliases
• type, which, hash — identify commands and hash lookups
• help, history — builtin help and command history
• set, export, unset, umask — shell/options and environment
• source, eval, exec, read — script and execution helpers
• printf, echo, test, true, false — basic utilities
• time, times, trap, timeout, getopts — timing, signals, option parsing
• command — run a command bypassing functions/aliases
• exit, pwd, cd, dirs, pushd, popd — navigation and exit
• env, clear — environment display and screen clear

Jobs & processes

• jobs — list jobs
• bg — resume a job in background
• fg — bring a job to foreground
• kill — send signals to jobs/processes
• disown — remove jobs from job table
• wait — wait for jobs to complete

Developer utilities

• reload — reload configuration
• library — manage/inspect libraries
• show — display information/details
• script-builtins — scripting helpers (internal)

Networking & system helpers

• ip — display IP info
• localip — show local IP
• reloaddns — reload DNS cache

Productivity helpers

• bookmark — manage bookmarks/paths
• copyssh — copy SSH public key
• dotfiles — dotfiles helper
• emptytrash — empty system trash
• ft — quick fuzzy file helper
• hide — hide/show files
• pstorm — open in PhpStorm
• code — open in VS Code
• shrug — print ¯\(ツ)/¯
• wip — work-in-progress helper

Short aliases (quality-of-life)

• b, bb, bd, bf, bi, bl, br — convenience wrappers

Note: A few items are convenience helpers specific to Krusty and not POSIX/Bash standard.

Usage

Basic Commands

• Execute external commands and pipelines: echo hi | tr a-z A-Z
• Redirect output and duplicate FDs: sh -c 'echo out; echo err 1>&2' 2>&1 | wc -l
• Process substitution: diff <(ls /tmp) <(ls /var/tmp)

Job Control

• Background processes: sleep 5 &
• Suspend with Ctrl+Z, resume with bg %1 or fg %1
• List jobs: jobs, kill jobs: kill %1, wait for completion: wait %1

Auto-suggestions & History

• Navigate history with ↑/↓ arrows
• Inline suggestions appear as you type
• History expansion: !! (last command), !n (command n), !prefix (last command starting with prefix)
• Fuzzy history search with Ctrl+R

Customization

Configuration File

Krusty uses a krusty.config.ts file for configuration. Create one in your project root or home directory:

export default {
  // Core settings
  verbose: false,
  streamOutput: true,

  // Aliases
  aliases: {
    ll: 'ls -la',
    gs: 'git status',
    commit: 'git add .; git commit -m',
    wip: 'git add -A && git commit -m "chore: wip" && git push',
  },

  // Environment variables
  environment: {
    EDITOR: 'code',
    PAGER: 'less',
  },

  // History configuration
  history: {
    maxEntries: 10000,
    file: '~/.krusty_history',
    ignoreDuplicates: true,
    ignoreSpace: true,
    searchMode: 'fuzzy', // 'fuzzy' | 'exact' | 'startswith' | 'regex'
  },

  // Completion settings
  completion: {
    enabled: true,
    caseSensitive: false,
    showDescriptions: true,
    maxSuggestions: 10,
    cache: {
      enabled: true,
      ttl: 3600000, // 1 hour
      maxEntries: 1000,
    },
  },
}

Themes & Prompts

Krusty supports extensive prompt customization with module detection:

export default {
  // Prompt format with placeholders
  prompt: {
    format: '{path} on {git} {modules} {duration} \n{symbol} ',
    showGit: true,
    showTime: false,
    showUser: false,
    showHost: false,
    showPath: true,
    showExitCode: true,
    transient: false,
  },

  // Theme configuration
  theme: {
    name: 'default',
    autoDetectColorScheme: true,
    enableRightPrompt: true,

    // Git status display
    gitStatus: {
      enabled: true,
      showStaged: true,
      showUnstaged: true,
      showUntracked: true,
      showAheadBehind: true,
      format: '({branch}{ahead}{behind}{staged}{unstaged}{untracked})',
    },

    // Colors
    colors: {
      primary: '#00D9FF',
      secondary: '#FF6B9D',
      success: '#00FF88',
      warning: '#FFD700',
      error: '#FF4757',
      git: {
        branch: '#A277FF',
        ahead: '#50FA7B',
        behind: '#FF5555',
        staged: '#50FA7B',
        unstaged: '#FFB86C',
        untracked: '#FF79C6',
      },
    },

    // Symbols
    symbols: {
      prompt: '❯',
      git: {
        branch: '',
        ahead: '⇡',
        behind: '⇣',
        staged: '●',
        unstaged: '○',
        untracked: '?',
      },
    },
  },

  // Runtime modules (auto-detected)
  modules: {
    bun: { enabled: true, format: 'via {symbol} {version}', symbol: '🐰' },
    nodejs: { enabled: true, format: 'via {symbol} {version}', symbol: '⬢' },
    python: { enabled: true, format: 'via {symbol} {version}', symbol: '🐍' },
    // ... many more supported runtimes
  },
}

Plugins & Hooks

Extend Krusty with plugins and lifecycle hooks:

export default {
  // Plugin system
  plugins: [
    'my-custom-plugin',
    {
      name: 'git-plugin',
      enabled: true,
      config: { autoFetch: true },
    },
  ],

  // Lifecycle hooks
  hooks: {
    'shell:init': [
      { command: 'echo "Welcome to Krusty!"' },
    ],
    'command:before': [
      { script: 'echo "Executing: $1"' },
    ],
    'directory:change': [
      { command: 'ls -la', conditions: ['directory'] },
    ],
  },

  // Expansion cache limits
  expansion: {
    cacheLimits: {
      arg: 200,
      exec: 500,
      arithmetic: 500,
    },
  },
}

Scripting

Krusty includes a comprehensive scripting engine with full shell compatibility:

Control Flow

# Conditional statements
if [ -f "file.txt" ]; then
    echo "File exists"
else
    echo "File not found"
fi

# Loops
for i in {1..5}; do
    echo "Count: $i"
done

while [ $count -lt 10 ]; do
    echo $count
    ((count++))
done

# Case statements
case $1 in
    start) echo "Starting..." ;;
    stop)  echo "Stopping..." ;;
    *)     echo "Usage: $0 {start|stop}" ;;
esac

Functions

# Function definitions
function greet() {
    local name=${1:-"World"}
    echo "Hello, $name!"
}

# Alternative syntax
greet() {
    echo "Hello, $1!"
}

Error Handling

# Set error handling modes
set -e  # Exit on error
set -u  # Exit on undefined variable
set -o pipefail  # Exit on pipe failure

# Trap signals
trap 'echo "Cleanup on exit"' EXIT

Script Built-in Commands

• Control: source, eval, exec, return, break, continue
• Variables: local, declare, readonly, unset, export
• Testing: test, [, [[, true, false
• I/O: read, printf, echo

See test/scripting.test.ts for comprehensive examples.

Advanced Job Management

Krusty provides advanced job management with proper signal handling:

Signal Handling

• Ctrl+Z: Suspend foreground job (SIGTSTP)
• Ctrl+C: Terminate foreground job (SIGINT)
• Process Groups: Proper process group management for signal propagation

Job Management Commands

# Background a command
sleep 60 &

# List all jobs
jobs
# Output: [1]+ Running    sleep 60 &

# Bring job to foreground
fg %1

# Resume job in background
bg %1

# Send signals to jobs
kill -TERM %1    # Terminate job 1
kill -STOP %2    # Stop job 2
kill -CONT %2    # Continue job 2

# Wait for job completion
wait %1          # Wait for job 1
wait             # Wait for all jobs

# Remove job from job table
disown %1

Real-time Monitoring

• Automatic job status updates
• Background job completion notifications
• Process group cleanup on job termination

Development

# Clone the repository
git clone https://github.com/stacksjs/krusty.git
cd krusty

# Install dependencies
bun install

# Build the project
bun run build

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙