🚀 Kra Workflow

Enterprise-grade development productivity suite — A powerful collection of integrations designed to supercharge your development workflow with seamless terminal integrations, intelligent automation, and AI-powered assistance.

📦 Installation

Option 1: Install from npm (Recommended)

npm install -g kra-workflow

Option 2: Install from source

git clone https://github.com/ChrisRistoff/kra-tmux.git
cd kra-tmux
npm install -g

⭐ Flagship Features

💾 Enterprise Autosave System

Unix domain socket-based workspace persistence with zero-overhead event coordination

• ⚡ Instant event processing via kernel-level IPC communication
• 🛡️ Production-ready reliability with multi-layer lock coordination
• 🔄 Complete state synchronization across Tmux/Neovim/Shell environments
• 🎯 Smart debouncing groups events during activity and flushes them once inactive

🤖 AI Chat System with Neovim as Interface

Revolutionary AI conversation interface with advanced file context management

• 📝 Neovim-native chat interface with real-time streaming responses
• 📁 Intelligent file context system - Add entire files or visual selections
• 💾 Smart conversation persistence with AI-generated summaries
• 🔄 Multi-provider support (OpenAI, Anthropic, Gemini, etc.)

🎯 Core Philosophy

Zero-overhead productivity - No background processes unless you're making meaningful changes to your tmux session or actively using the tool.

With on-demand activation and intelligent event-driven architecture, Kra provides seamless terminal integrations including Tmux server management, Git operations, intelligent workspace persistence, and an AI chatbot interface — all with enterprise-grade reliability and zero idle resource consumption.

🌟 Design Principles

• 🔋 Zero background overhead - Processes spawn only when needed, terminate when idle
• 🎯 Event-driven activation - Responds instantly to meaningful workspace changes
• 🔍 Grep-searchable interfaces - Lightning-fast access to any functionality
• ⌨️ Full tab autocompletion - Efficient, intuitive terminal interactions
• 🎨 Modern terminal UI - Rich formatting with zero persistent processes
• 🚀 Zero-configuration - Intelligent defaults with automatic cleanup

The Result: Effortlessly switch between projects, manage Git workflows, chat with AI, and maintain perfect workspace state — all from your terminal with maximum performance and minimal system impact. This comprehensive suite helps you work smarter, faster, and with complete confidence in your system's efficiency.

📚 Complete Feature Set

🖥️ Tmux Integration

Complete server lifecycle management with persistent state

🌿 Git Integration

Advanced source control with conflict resolution and branch management

🤖 AI Chatbot Integration

Intelligent conversation system with file context awareness

⚡ Autosave System

Enterprise-grade automated workspace persistence

🛠️ System Utilities

Developer productivity tools and utilities

🖥️ Tmux Integration

Enterprise-grade tmux server management engineered to give you complete control over your development sessions with persistent workspace state.

📦 Access via:

kra tmux

🛠️ Available Commands

| Command | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | save-server 💾 | Save entire servers — including all sessions, windows, panes, and Neovim states. Perfect for multitasking across different projects or tickets. | | load-server ♻️ | Reload your saved server exactly how you left it — including repos (auto-clones if missing), directories, layouts, and editor states. | | delete-server 🧹 | Clean up specific saved servers. Preview the structure (sessions, windows, names) before confirming deletion. | | list-sessions 📋 | View a summary of the current server's sessions and windows with rich formatting. | | kill ❌ | Terminate the currently running server instantly with graceful cleanup. |

Demo Previews - Click to expand

Saves the current tmux server, including all sessions, windows (with their names), panes (with sizes and positions), and active Neovim sessions with intelligent state tracking.

Select a saved tmux server from a searchable list to load. Automatically runs configured build/watch commands and restores complete development environment state.

Intelligently displays server structure with sessions, windows, and panes count, then confirms deletion with detailed preview.

🤖 AI Chatbot Integration

Revolutionary AI conversation system with Neovim-native interface, advanced file context management, and intelligent conversation persistence.

🎯 Complete AI Chat System Documentation →

📦 Access via:

kra ai

🛠️ Available Commands

| Command | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chat 🗨️ | Launch new AI chat session in Neovim with real-time streaming, file context management, and socket-based communication. Press Enter in normal mode to send prompts. | | load 📂 | Browse saved conversations with AI-generated summaries. Preview summaries before loading full chat sessions. | | delete 🧽 | Manage saved chats with searchable deletion interface and confirmation prompts. |

Key Technical Features

• ⚡ Real-time streaming responses with user-controlled abort capability
• 📁 Advanced file context system - Add entire files or visual selections as context
• 🧠 Multi-provider AI support - OpenAI, Anthropic, Gemini, and custom providers
• 💾 Intelligent conversation persistence with automatic summary generation
• 🎯 Visual selection integration - Select code portions directly in Neovim
• 🔄 Session restoration with complete context reconstruction

Demo Previews - Click to expand

Multi-step chat initialization:

1. Role Selection - Choose from preconfigured roles or define custom ones
2. Provider Selection - Pick from available AI providers with model options
3. Temperature Control - Fine-tune response creativity (0-10 scale, 0-20 for Gemini)
4. Interactive Session - Real-time conversation with streaming responses

Advanced Features:

• Socket-based Neovim integration for instant response delivery
• File context management with visual selection support
• Edit messages and responses before sending or saving
• Complete conversation control with context manipulation

Automatic conversation persistence:

• Prompt to save on chat exit with Y/N confirmation
• Gemini-powered summarization utilizing large context window
• Editable summaries - Review and modify before final save
• Structured storage with metadata and searchable content

Intelligent chat loading workflow:

• Searchable list of saved conversations with timestamps
• Summary preview in Neovim before loading full chat
• Context reconstruction - Rebuilds file contexts automatically
• Seamless continuation - Resume exactly where you left off

Searchable deletion interface with confirmation prompts and permanent removal warnings.

⚡ Autosave System

Enterprise-grade automated workspace persistence with Unix domain socket IPC and intelligent event coordination across your entire development environment.

🎯 Complete Autosave System Documentation →

🚀 Core Architecture

• ⚡ Unix Domain Socket IPC - Kernel-level inter-process communication with zero polling overhead
• 🛡️ Multi-layer lock coordination - Production-ready safety with automatic stale lock cleanup
• 🎯 Smart event debouncing - Configurable 20s timeout prevents excessive saves
• 🔄 Multi-environment sync - Seamless Tmux↔Neovim↔Shell state coordination

🏗️ Technical Highlights

• Event-driven architecture with instant processing via Unix sockets
• Intelligent session tracking with automatic cleanup for closed Neovim instances
• Production-grade error handling with graceful degradation and silent failures
• Smart buffer filtering - Excludes 38+ utility buffer types for clean state saves

📊 Supported Event Sources

| Environment | Integration Method | Events Tracked | |-------------|-------------------|----------------| | Tmux | Native hooks system | Session/window/pane lifecycle events | | Neovim | Lua autocmd integration | Buffer changes, session enter/leave | | Shell | Zsh/Bash hook override | Directory changes, command completion |

⚙️ Configuration

# settings.yaml
autosave:
  active: true                    # Enable/disable autosave
  currentSession: "auto-managed"  # Current session tracking
  timeoutMs: 20000               # 20s debounce window

🌿 Git Integration

Advanced Git workflow management designed to facilitate efficient source control with intelligent conflict resolution and branch lifecycle management.

📦 Access via:

kra git

🛠️ Available Commands

| Command | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | restore ♻️ | Recover single or multiple files effortlessly with intelligent selection interface. | | cache-untracked 📦 | Save untracked files in a branch-specific cache with automatic organization and retrieval. | | retrieve-untracked 🔄 | Retrieve your previously cached untracked files with branch-aware restoration. | | hard-reset 🧹 | Perform intelligent git fetch --prune and hard reset to keep local branches clean and synchronized. | | log 📜 | View a rich, navigable Git log inside Neovim with optimized commit navigation ({ and } keys). | | stash 💼 | Apply or drop stashes using an intuitive, searchable selection interface. | | stash-drop-multiple 🗑️ | Select and drop multiple stashes efficiently with dynamic list updates. | | conflict-handle ⚔️ | Resolve merge conflicts seamlessly in Neovim with three-way split and automatic conflict scanning. | | open-pr 🔗 | Instantly open associated pull request links in your browser with GitHub/Bitbucket support. | | view-changed 🔍 | Instantly inspect file changes with integrated diff viewer and smart file management. | | create-branch 🌿 | Checkout base branch with automatic sync, fetch/prune, hard reset, then create and switch to new branch. | | checkout ⏳ | Filter branches by activity date with dynamic search and smart stash handling. |

All interactive lists feature intelligent grep search with real-time filtering and contextual highlighting.

Demo Previews - Click to expand

Displays searchable list of modified files with "restore all" option for batch operations.

Intelligent untracked file management with branch-specific storage and automatic organization.

Branch-aware retrieval of cached files with intelligent conflict detection.

Comprehensive sync with detailed console output showing pruned branches, fetched updates, and current HEAD state.

Rich Git log interface in Neovim with optimized formatting and keyboard navigation shortcuts.

Searchable stash interface with apply/drop actions and detailed stash information.

Efficient multi-stash deletion with live list updates and confirmation prompts.

Three-way merge conflict resolution with automatic marker detection and progress tracking.

Automatic pull request detection with GitHub/Bitbucket support and cross-platform browser launching.

Two-way diff interface with automatic file list management and smart navigation.

Comprehensive branch creation workflow with base branch selection, sync verification, and clean state guarantee.

Date-filtered branch selection with automatic stash handling and conflict detection.

🛠️ System Utilities

Developer productivity tools and system management utilities for efficient project maintenance and automated cleanup operations.

📦 Access via:

kra sys

🛠️ Available Commands

| Command | Description | | ------------------ | ------------------------------------------------------------------------------------- | | grep-file-remove 🗑️ | Smart file deletion with grep-based search and confirmation prompts. | | grep-dir-remove 📁 | Directory cleanup with intelligent search and recursive removal options. | | scripts 🧪 | Custom script execution system (experimental) - Run user-defined automation scripts. |

Note: Script management system is in active development. Currently requires manual script addition.

Demo Previews - Click to expand

🚀 Getting Started

📋 Prerequisites

• Node.js (v16+ recommended)
• Tmux (v3.0+)
• Neovim (v0.8+)
• Git (v2.0+)
• Zsh/Bash shell environment

⚡ Quick Installation

# Clone and setup
git clone <repository-url>
cd kra-workflow

# Install dependencies and configure integrations
npm install
node setup/configSetup.js

# Verify installation
kra --help

📚 Detailed Setup

For comprehensive installation instructions, environment configuration, and troubleshooting guides, please refer to our Installation Guide.

🎯 Why Kra Workflow?

🚀 For Individual Developers

• Zero work loss from crashes or unexpected reboots
• Instant environment restoration with complete state preservation
• AI-powered development assistance with intelligent context awareness
• Streamlined Git workflows with advanced conflict resolution

🏢 For Development Teams

• Consistent development environments across team members
• Seamless workspace handoff and collaboration
• Enterprise-grade reliability with production-ready error handling
• Advanced automation reducing manual overhead and context switching

⚡ Technical Excellence

• Advanced Node.js process coordination with Unix domain sockets
• Deep Unix system programming integration for maximum performance
• Production-ready architecture with comprehensive error handling
• Modern terminal UI/UX with intelligent search and navigation

📄 License

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

🚀 Supercharge your development workflow with Kra

Built with ❤️ for developers who demand excellence