Cauldron

Bringing Magik to Fish Shell 🪄🐟

With the help of your beloved familiar, become an arcane master of the terminal.

Cauldron is a comprehensive Fish Shell utility suite that enhances your terminal experience with AI-powered assistance, rich UI components, and powerful developer tools. Whether you're managing packages, searching code, or automating workflows, Cauldron provides the magical touch your terminal needs.

Features

🤖 AI-Powered Familiar

Interactive AI Assistant: Get help from your terminal companion
LLM Integration: Query the llama3.2 model directly from your shell
Smart Code Search: Find and preview code with intelligent suggestions
🧠 Context Awareness: Familiar remembers conversations and understands your projects
💾 Conversation Memory: Persistent history across sessions with recall and search
⚙️ User Preferences: Learns your coding style and project-specific preferences
🗂️ Project Detection: Automatically detects languages, frameworks, and package managers
🎭 Personality System: Six built-in personalities (Wise Mentor, Sarcastic Debugger, Enthusiastic Cheerleader, Zen Master, Mad Scientist, Pair Programmer)
📊 Relationship Building: Your familiar learns and grows with you, unlocking features as you interact
🎯 Adaptive Responses: Adjusts tone and detail based on your error rate, project complexity, and stress levels

🎨 Rich Terminal UI

Visual Components: Boxes, badges, spinners, and progress indicators
Color Palettes: Pre-configured themes (berry, malory, neodutch)
Text Styling: Bold, italic, underline, and banner effects
Visual Effects: Rain, orbiting volleys, and VHS effects

📦 Package Management

Multi-Source Installation: Install from APT, Homebrew, and Snap
Language Version Management: ASDF and NVM integration
Automated Updates: System-wide update orchestration

🛠 Developer Tools

Workspace Creation: Quick project scaffolding
Repository Management: Git workflow automation
Node.js Utilities: Environment initialization and Yarn management
Code Search: Recursive grep with fzf preview and VS Code integration

🗄 Data Management

SQLite Integration: Built-in database for configuration storage
Environment Conversion: Export environment variables to JSON
Backup Automation: Automatic file backups before editing

Quick Start

# One-line installation
curl -fsSL https://raw.githubusercontent.com/MagikIO/cauldron/main/install.sh | bash

# Or manual installation
git clone https://github.com/MagikIO/cauldron.git ~/.cauldron
cd ~/.cauldron
./install.sh

# Start using Cauldron
ask "How do I create a new React component?"  # Query AI with personality
personality list                               # See available personalities
personality set sarcastic_debugger            # Change your familiar's personality
hamsa "TODO"                                   # Search code with preview
familiar "Hello, what can you help me with?"  # Chat with your familiar
cauldron --help                               # View all commands

Installation

Prerequisites

Fish Shell (v3.0+)
Git
curl
Node.js v22+ (recommended)
pnpm v9+ (optional, for development)

Quick Installation (Recommended)

# One-line installation with automatic setup
curl -fsSL https://raw.githubusercontent.com/MagikIO/cauldron/main/install.sh | bash

# Restart your shell
exec fish

Manual Installation

# Clone the repository
git clone https://github.com/MagikIO/cauldron.git ~/.cauldron
cd ~/.cauldron

# Run installation script
./install.sh

The installer will:

Set up the ~/.config/cauldron directory structure
Copy all functions to your Fish configuration
Initialize the SQLite database
Set required environment variables
Install essential tools (fzf, bat, cowsay, etc.)
Configure your shell for immediate use

Updating

Keep Cauldron up to date with the built-in update system:

# Check for updates
cauldron_update --check-only

# Apply updates (with automatic backup)
cauldron_update

The update process:

✅ Creates automatic database backup
✅ Pulls latest code from GitHub
✅ Runs database migrations
✅ Updates Fish functions
✅ Updates data files and Node.js dependencies
✅ Preserves your conversation history and preferences

Repair Mode

If something goes wrong, use repair mode:

# Check for issues
cauldron_repair --verify-only

# Auto-fix all issues
cauldron_repair --fix-all

# Interactive repair
cauldron_repair

See INSTALL_UPDATE.md for detailed installation and troubleshooting guide.

Dependency management

For detailed installation instructions, see docs/INSTALLATION.md.

Core Concepts

The Familiar System

Your "familiar" is an AI companion that assists you in the terminal. It can:

Answer questions about your codebase
Provide coding assistance
Display messages with various "emotions" (borg, dead, stoned, paranoid, drunk, greedy)
Use custom cowsay characters (Yoda, Vault-Boy, Wheatley, etc.)

Function Organization

Cauldron organizes its functionality into categories:

functions/ - Core utilities (installs, node_init, workspace creation)
familiar/ - AI companion interface
UI/ - Visual components (badges, boxes, spinners)
text/ - Text formatting (bold, italic, banners)
effects/ - Visual effects (rain, VHS, orbiting)
alias/ - Shell shortcuts and aliases
packages/ - Package manager integrations

Environment Variables

Cauldron uses these environment variables:

CAULDRON_PATH - Base installation directory
CAULDRON_DATABASE - SQLite database location
CAULDRON_PALETTES - Color palette definitions
CAULDRON_SPINNERS - Spinner animation definitions
CAULDRON_INTERNAL_TOOLS - Internal tool scripts

Usage Examples

AI & Search

# Query the AI model (now with context awareness!)
ask "Explain the difference between map and forEach in JavaScript"

# Ask follow-up questions (remembers conversation history)
ask "Which one should I use for this project?"

# Search code with live preview
hamsa "authentication"

# Get help from your familiar
familiar "How do I optimize this database query?"

Memory & Context

# View conversation history
recall                    # Last 10 conversations from current session
recall -a -l 20          # Last 20 from all sessions
recall -s "typescript"   # Search conversations

# Save preferences
remember coding_style "functional programming, immutability"
remember test_framework "vitest"
remember --list          # View all saved preferences

# Project context
context                  # View current project context
context -u               # Update project context in database

# Manage memory
forget -p coding_style   # Remove a preference
forget -s                # Clear session history

Personality System

# List available personalities
personality list

# See current personality and relationship status
personality show

# Change personality
personality set sarcastic_debugger         # Global
personality set zen_master --project       # Project-specific

# View personality details
personality info wise_mentor

# Create custom personality
personality create my_helper

# Edit personality traits
personality edit my_helper

# Export/import personalities
personality export sarcastic_debugger ~/my_personality.json
personality import ~/shared_personality.json

# Reset relationship level
personality reset

See PERSONALITY_SYSTEM.md for detailed personality documentation.

Package Management

# Install packages from multiple sources
installs bat fzf cowsay

# Install from specific package manager
installs --apt build-essential

# Dry run to see what would be installed
installs --dry-run neovim

# Select preferred package manager
choose_packman

Development Workflows

# Initialize a Node.js project
node_init my-project

# Create a new workspace
create_workspace my-app

# Update repository with all dependencies
update_repo

# Manage Yarn packages
roll-yarn

File Operations

# Edit with automatic backup
backup_and_edit config.json

# Create a backup
bak important-file.txt

# Copy Fish functions
cpfunc ./my-functions/ -d

UI & Text Formatting

# Display styled text
bold "Important message"
italic "Emphasized text"
underline "Underlined text"

# Create banners
banner "Welcome"
beam-banner "Project Name"

# Show spinners
spin "Loading..."

# Display badges
badge "SUCCESS" green

System Administration

# Detect operating system
detectOS

# Get latest GitHub release
getLatestGithubReleaseTag owner/repo

# Visual git branch selection
visual_git_checkout

Documentation

Core Documentation

INSTALLATION.md - Detailed installation guide
CONFIGURATION.md - Configuration options and customization
ARCHITECTURE.md - System architecture and design
API.md - Complete function reference
FAMILIAR.md - AI companion guide
MEMORY_SYSTEM.md - 🆕 Context awareness & memory features
MEMORY_SYSTEM_QUICKSTART.md - 🆕 5-minute quick start guide

Function-Specific Documentation

Located in docs/functions/:

ask - AI model querying
backup_and_edit - File editing with backups
cache-pipe - Caching utilities
cpfunc - Function copying
create_service - Service creation
dev-it - Development tools
env2json - Environment to JSON conversion
installs - Package installation
node_init - Node.js initialization
update_repo - Repository updates

Getting Help

Every function supports the -h or --help flag:

installs -h
ask --help
familiar -h

System Requirements

Required

Operating System: Linux (Ubuntu/Debian recommended) or macOS
Shell: Fish Shell v3.0+
Git: For version control and updates
curl: For downloading resources

External Dependencies

Cauldron can install these tools automatically:

Via APT (Linux):

bat, cbonsai, cowsay, fortune, jp2a, linuxlogo
pv, hyfetch, build-essential, procps, curl, git
rig, toilet, sqlite3

Via Homebrew:

glow, fzf, timg, watchman, lsd, fx, navi

Via Snap:

lolcat-c

For AI Features:

Ollama with llama3.2 model

Project Structure

cauldron/
├── node/                    # TypeScript/Node.js components
│   ├── index.ts            # Main entry point
│   ├── Cauldron.ts         # Core orchestrator class
│   ├── DB.ts               # Database manager
│   └── CustomUpdateMech.ts # Update mechanism
│
├── functions/              # Core Fish shell functions
├── familiar/               # AI companion system
├── UI/                     # User interface components
├── text/                   # Text formatting utilities
├── effects/                # Visual effects
├── alias/                  # Shell aliases
├── cli/                    # Command-line interface
├── setup/                  # Installation utilities
├── update/                 # Update system
├── internal/               # Internal utilities
├── tools/                  # Internal tools
├── packages/               # Package manager integrations
│   ├── asdf/              # ASDF version manager
│   └── nvm/               # Node Version Manager
│
├── data/                   # Static data files
│   ├── cauldron.db        # SQLite database
│   ├── palettes.json      # Color palettes
│   ├── spinners.json      # Spinner definitions
│   └── *.cow              # Cowsay characters
│
├── docs/                   # Documentation
│   ├── functions/         # Function-specific docs
│   ├── setup/             # Setup documentation
│   └── text/              # Text utilities docs
│
├── config/                 # Configuration utilities
├── install.fish           # Main installation script
├── dependencies.json      # External dependencies
├── package.json           # NPM configuration
├── tsconfig.json          # TypeScript configuration
└── CHANGELOG.md           # Version history

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/MagikIO/cauldron.git
cd cauldron

# Install dependencies
pnpm install

# Run TypeScript components
pnpm run

# Lint code
pnpm lint

# Run tests
./tests/run_tests.fish

Testing

Cauldron uses Fishtape for testing Fish shell functions. Tests are automatically run via GitHub Actions on every push and pull request.

# Install test dependencies
./tests/setup.fish

# Run all tests
./tests/run_tests.fish

# Run unit tests only
./tests/run_tests.fish --unit

# Run integration tests only
./tests/run_tests.fish --integration

See tests/README.md for comprehensive testing documentation.

Code Style

Fish shell functions follow consistent patterns
TypeScript uses strict mode with ES2022 target
ESLint with @magik_io/lint_golem configuration
Semantic versioning for releases

Submitting Changes

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

Version History

See CHANGELOG.md for detailed version history.

Recent Updates

v0.3.1 - Improved directory creation and copying logic
v0.3.0 - Database initialization improvements
v0.2.1 - Update process bug fixes
v0.2.0 - Added database support, new cow files, improved CLI

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Antonio B. Email: [email protected] Repository: MagikIO/cauldron

Acknowledgments

Fish Shell community for the excellent shell
Ollama team for local LLM support
All the open-source tools that make this possible

Bringing Magik to Fish Shell 🪄🐟
Made with ❤️ by MagikIO

Name		Name	Last commit message	Last commit date
Latest commit History 351 Commits
.github/workflows		.github/workflows
.vscode		.vscode
UI		UI
alias		alias
cli		cli
config		config
data		data
docs		docs
effects		effects
familiar		familiar
functions		functions
integrations		integrations
internal		internal
node		node
packages		packages
setup		setup
tests		tests
text		text
tools		tools
update		update
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.npmignore		.npmignore
.tool-versions		.tool-versions
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PERSONALITY_SYSTEM.md		PERSONALITY_SYSTEM.md
README.md		README.md
cliff.toml		cliff.toml
dependencies.json		dependencies.json
eslint.config.js		eslint.config.js
install.fish		install.fish
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

License

MagikIO/cauldron

Folders and files

Latest commit

History

Repository files navigation

Cauldron

Bringing Magik to Fish Shell 🪄🐟

Table of Contents

Features

🤖 AI-Powered Familiar

🎨 Rich Terminal UI

📦 Package Management

🛠 Developer Tools

🗄 Data Management

Quick Start

Installation

Prerequisites

Quick Installation (Recommended)

Manual Installation

Updating

Repair Mode

Core Concepts

The Familiar System

Function Organization

Environment Variables

Usage Examples

AI & Search

Memory & Context

Personality System

Package Management

Development Workflows

File Operations

UI & Text Formatting

System Administration

Documentation

Core Documentation

Function-Specific Documentation

Getting Help

System Requirements

Required

Recommended

External Dependencies

Project Structure

Contributing

Development Setup

Testing

Code Style

Submitting Changes

Version History

Recent Updates

License

Author

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Contributors 2

Uh oh!

Languages

Packages