Kontext

A CLI tool for managing development profiles and automating shell environment switching.

Kontext allows developers to define and switch between distinct development profiles, automating the management of their shell environment and Git configurations. It provides seamless, directory-based context switching to eliminate the manual, error-prone process of juggling configurations between different projects.

See Kontext in action: automatic environment switching

• Profile Management: Define profiles in YAML files with Git identity and environment configurations
• Directory-based Activation: Automatically switch profiles when entering directories with .kontext-profile files
• Git Identity Management: Automatically configure Git user name and email based on the active profile
• Environment Variables: Set profile-specific environment variables
• .env File Support: Load environment variables from .env files within profiles
• Shell Script Integration: Source custom shell scripts for profile-specific configurations
• Hooks: Execute custom scripts on profile activation and deactivation
• Cross-shell Support: Works with Bash, Zsh, and Fish shells
• Modern Command Structure: Intuitive profile and tag command groups for organized management

⭐ If you find Kontext useful, please consider starring the repository! It helps others discover the project and motivates continued development.

Install Kontext globally via npm:

npm install -g kontext-cli

Then set up shell integration:

kontext init

Follow the instructions to add the shell hook to your configuration file, then restart your shell or source your config file.

kontext profile new work

Follow the interactive prompts to configure your work profile with Git configuration, dotfiles, and environment variables.

Navigate to your work project directory and tag it:

cd ~/work/my-project
kontext tag work

Now whenever you cd into that directory (or any subdirectory), Kontext will automatically:

• Switch to the "work" profile
• Execute activation hooks (if configured)
• Update your Git configuration
• Set environment variables
• Source any profile-specific shell scripts
• Update your shell prompt to show the active profile

You can also manually switch profiles for the current session:

kontext switch personal
# Profile "personal" activated

Manual switches are temporary and only affect the current shell session. When you open a new terminal, the automatic directory-based rules apply.

• kontext profile new [name] - Create a new profile interactively
• kontext profile list [--detailed] - List all available profiles
• kontext profile edit <name> - Edit a profile in your default editor
• kontext profile delete <name> - Delete a profile and its files

• kontext tag <profile> - Apply a profile to the current directory
• kontext tag remove (or rm) - Remove profile association from current directory
• kontext tag list [--interactive] - List and manage all profile tags across filesystem

• kontext status [profile] - Show detailed profile status and system state
• kontext switch <profile> - Manually switch to a profile (temporary, session-only)

• kontext init - Set up shell integration
• kontext config - Show configuration information and helpful commands

• kontext hook init - Generate shell integration script (used internally)

Profiles are stored as folders in ~/.config/kontext/profiles/, each containing a profile.yml file and associated configuration files. Each profile can configure:

• Git Configuration: Use a dedicated .gitconfig file for the profile
• Environment Variables: Export custom environment variables or load from .env files
• Dotfile Management: Automatically symlink dotfiles like .vimrc, .tmux.conf, etc.
• Hooks: Execute custom scripts on activation and deactivation

name: work
git:
  config_path: ${KONTEXT_PROFILE_DIR}/.gitconfig
environment:
  # Load variables from .env file (optional)
  env_file: ${KONTEXT_PROFILE_DIR}/.env
  # Direct variables (can override .env file variables)
  variables:
    NODE_ENV: development
    API_URL: https://api.company.com
    AWS_PROFILE: work
  # Source shell script for complex setup (optional)
  script_path: ${KONTEXT_PROFILE_DIR}/setup.sh
dotfiles:
  ~/.vimrc: ${KONTEXT_PROFILE_DIR}/.vimrc
  ~/.tmux.conf: ${KONTEXT_PROFILE_DIR}/.tmux.conf
hooks:
  on_activate: ${KONTEXT_PROFILE_DIR}/hooks/activate.sh
  on_deactivate: ${KONTEXT_PROFILE_DIR}/hooks/deactivate.sh

Kontext supports multiple ways to configure environment variables with different precedence levels:

1. .env File Variables (lowest precedence): Load from a .env file within the profile directory
2. Direct Variables (medium precedence): Define variables directly in the profile YAML
3. Shell Script Variables (highest precedence): Set via custom shell script execution

You can specify a .env file to automatically load environment variables:

environment:
  env_file: ${KONTEXT_PROFILE_DIR}/.env

Create a .env file in your profile directory:

# ~/.config/kontext/profiles/work/.env
NODE_ENV=development
API_URL=https://api.company.com
AWS_PROFILE=work
DATABASE_URL=postgresql://localhost:5432/myapp

# Comments are supported
SECRET_KEY=your-secret-key-here

Important Notes:

• The .env file must be located within the profile directory for security
• Variables defined in the variables section can override .env file variables
• Shell scripts executed via script_path can override both

View profile details:

kontext status work

Edit a profile:

kontext profile edit work  # Opens in your default editor
kontext status             # View currently active profile

Find configuration files:

kontext config             # Shows all configuration locations
kontext status             # Shows active profile with file paths

# Navigate to your project directory
cd ~/work/my-project

# Tag the directory with a profile
kontext tag work

# Test it works
kontext status

# In your project directory
echo "work" > .kontext-profile

# Test it works
kontext status

# List all profile tags across your filesystem
kontext tag list

# Interactive tag management dashboard
kontext tag list --interactive

# Remove a tag from current directory
kontext tag remove
# or use the short alias
kontext tag rm

Pro Tips:

• Subdirectories inherit parent directory profiles
• Use kontext status to see detailed profile information and system state
• Environment variables are only active when the profile is loaded via shell integration
• Manual profile switches with kontext switch are temporary and session-specific
• Default profiles can be set in your home directory (~/.kontext-profile) for non-project folders

Hooks allow you to execute custom scripts when profiles are activated or deactivated, enabling powerful automation and environment setup.

• Activation Hooks (on_activate): Run when a profile is activated
• Deactivation Hooks (on_deactivate): Run when a profile is deactivated

When hooks execute, they receive these environment variables:

• KONTEXT_PROFILE: Name of the profile being activated/deactivated
• KONTEXT_HOOK_TYPE: Either "activate" or "deactivate"

Activation Hook (~/.config/kontext/profiles/work/hooks/activate.sh):

#!/bin/bash
echo "🚀 Starting work session for $KONTEXT_PROFILE"

# Start development services
docker-compose up -d database redis

# Switch Node.js version
nvm use 18

# Connect to work VPN
sudo vpn-connect work-profile

# Send notification
osascript -e 'display notification "Work environment activated" with title "Kontext"'

Deactivation Hook (~/.config/kontext/profiles/work/hooks/deactivate.sh):

#!/bin/bash
echo "🛑 Ending work session for $KONTEXT_PROFILE"

# Stop development services
docker-compose down

# Disconnect VPN
sudo vpn-disconnect

# Backup work
rsync -av ~/work/ ~/backups/work-$(date +%Y%m%d)/

# Send notification
osascript -e 'display notification "Work environment deactivated" with title "Kontext"'

Add hooks to your profile YAML file:

hooks:
  on_activate: ${KONTEXT_PROFILE_DIR}/hooks/activate.sh
  on_deactivate: ${KONTEXT_PROFILE_DIR}/hooks/deactivate.sh

Hook scripts are stored in the hooks/ directory within each profile folder alongside other configuration files. This ensures all profile-related assets are centrally located.

Hooks also support:

• Absolute paths (/usr/local/bin/script.sh)
• Home directory expansion (~/scripts/hook.sh)
• Relative paths (resolved from current directory)

When creating profiles with kontext profile new, you can choose to automatically create template hook scripts that are stored in the profile directory.

• Hook failures generate warnings but don't prevent profile switching
• Hooks have a 30-second timeout to prevent hanging
• Failed hooks are logged to stderr for debugging

This project is built with TypeScript and uses a monorepo structure:

• packages/core/ - Core functionality (profile management, directory scanning, etc.)
• packages/cli/ - Command-line interface

pnpm install
pnpm run build

pnpm run package

This creates single executables for macOS, Linux, and Windows in the build/ directory.

This project uses Release Please for automated versioning and publishing. When contributing:

Use conventional commit format for automatic version bumping:

• feat: add new feature → Minor version bump (1.6.5 → 1.7.0)
• fix: resolve bug → Patch version bump (1.6.5 → 1.6.6)
• feat!: breaking change → Major version bump (1.6.5 → 2.0.0)
• chore: update dependencies → No version bump
• docs: update README → No version bump

1. Push changes to main branch with conventional commit messages
2. Release Please automatically creates/updates a release PR with:
   • Version bump based on commit types
   • Generated changelog from commit messages
3. Review and merge the release PR to trigger automated publishing to npm

No manual version bumping or changelog maintenance required!

All releases are automatically documented with generated changelogs. View the latest releases and changelogs on the GitHub Releases page.

MIT