🚀 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.

⭐ 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.)

🧠 Agent Mode (Copilot + BYOK)

Full agentic workflow with two interchangeable backends and a review-before-apply repository workspace

• 🔀 Two providers behind one command — GitHub Copilot SDK or any OpenAI-compatible API (OpenAI, DeepSeek, Gemini, OpenRouter, DeepInfra, Mistral) via BYOK
• 📚 Live model catalog — models fetched from each provider on demand, annotated with context window + per-token pricing, cached for 24h
• 🔍 Repo-as-workspace — the agent edits files directly as uncommitted git diffs; you review before applying
• ✏️ Inline diff editor — edit the agent's proposed change in a 3-pane diff before approving; choose whether the AI gets notified of your edits
• 📜 Per-file revert — session diff history with one ORIG entry per file lets you roll back any single file to its pre-session baseline
• 🛡️ Tool approval — approve each tool call, allow by family, or go YOLO
• 🔌 MCP server support — extend either provider with custom tools via settings.toml; BYOK auto-loads kra-bash + kra-web
• 🧠 Persistent project memory + multi-codebase semantic search (kra-memory MCP) — local LanceDB + on-device fastembed, remember / recall / update_memory carry design decisions, gotchas, and follow-ups across sessions and compaction. semantic_search can search code by concept when the repo is indexed and search all long-term memories with memoryKind: 'findings'; memory reads are intercepted through a Telescope picker so you choose which entries the agent actually receives. Code indexing stays opt-in per launch and is tracked in a central registry (~/.kra-memory/registry.json) keyed by git origin so identity survives renames and re-clones. Catch-up reindex on launch (git diff + status union) covers edits made between sessions; kra memory is a blessed UI to manage memories, docs sources, search, and every indexed repo from one place
• 📊 Copilot quota monitoring — live monthly usage + cached weekly/session limits with terminal warnings at 50%/25%/10%

🎯 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

📝 Notes

Self-contained markdown note app — bundled Neovim config, render-markdown, telescope picker, wiki-links & backlinks

🛠️ 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. | | save-session 💾 | Save a single tmux session (pre-selecting the attached one) into its own file. Captures windows, panes, and Neovim state for that session only. | | load-session ♻️ | Load a saved single-session file into the running tmux server without tearing down the rest. Prompts to rename or overwrite on a name collision. | | manage-saves 🗂️ | Two-tab dashboard for browsing saved files. Press 1 for server saves, 2 for single-session saves. Browse, preview, rename, delete, or build a new save interactively. | | 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, built-in web tools (web_search + web_fetch with Jina / DuckDuckGo / Wayback fallbacks), and socket-based communication. Press Enter in normal mode to send prompts; press <leader>h to inspect the tool-call history. Provider models are sourced from the same live catalog the agent uses (cached 24h, network-free fallback). | | agent 🧠 | Launch an agent session in Neovim with a provider picker (Copilot SDK or BYOK / OpenAI-compatible), project-local MCP servers, an inline diff editor, and per-file revert from session diff history. | | 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
• 🌐 Built-in web tools in chat - Models can call web_search and web_fetch mid-conversation. Search uses Jina → DuckDuckGo Lite; fetch uses Jina Reader → direct (handles JS-rendered and paywalled pages). Set JINA_API to enable the Jina backends.
• 🧠 Multi-provider AI support - OpenAI, Anthropic, Gemini, and custom providers
• 🤖 Agent mode (Copilot + BYOK) — Agentic tool use, MCP support, an inline diff editor, and interactive ask-user requests inside Neovim
• 💾 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

Agent-first coding workflow:

1. Provider selection — pick copilot (GitHub Copilot SDK) or byok (any OpenAI-compatible API)
2. Model selection — live catalog with context window + pricing annotations; Copilot also picks a reasoning effort.
3. Repo workspace — the agent writes changes directly to your repo as uncommitted git diffs; nothing is staged automatically
4. Diff review in Neovim — review the generated git diff, optionally edit the agent's proposed change in the 3-pane diff editor, then explicitly apply or reject
5. Per-file revert — <leader>s opens session diff history with an ORIG entry per file so you can undo a single file at any time

MCP configuration:

• Define MCP servers under ai.agent.mcpServers.* in settings.toml
• Active servers are injected into both providers automatically
• BYOK additionally auto-loads kra-bash (shell) and kra-web (web_fetch / web_search) since BYOK has no built-in tools
• Copilot also accepts remote (http/sse) MCP servers; BYOK only spawns local stdio servers

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

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. | | reflog 🧭 | Browse the reflog in the same multi-pane dashboard as git log, with side-panel commit stats for each HEAD movement. | | scout 🔭 | Scan the workspace for every git repo and inspect branch, dirty state, ahead/behind, and recent activity at a glance. |

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. Press c on the highlighted commit to open the interactive cherry-pick menu (apply / --edit / -x / --no-commit / preview commit / preview files / cancel); on conflicts you drop into an in-place resolver that lists conflicted files with status indicators, opens each file in nvim -c Gvdiffsplit!, and offers continue / skip / abort actions. A aborts an in-progress cherry-pick from the dashboard, and B scopes the view to a specific branch (or back to all).

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, conflict detection. Branches can be filtered by commit titles.

Reuses the multi-pane log dashboard against git reflog, so each entry (checkout / reset / rebase / commit) shows its full commit context, stat summary, and changed files in side panels. Useful for finding commits orphaned by a reset, rebase, or accidental branch delete. Inherits the dashboard keymaps, including the interactive cherry-pick menu on c (with the in-place conflict resolver), A to abort an in-progress cherry-pick, and B to scope the reflog to a specific branch.

Scans the workspace for every git repository (up to 2 levels deep) and shows them in a full multi-pane dashboard. Dirty repos bubble to the top. Three always-visible right-side panels — repo details (branch, modified/untracked counts, ahead/behind, stash count), recent log (last 20 commits), and git status — all load automatically as you navigate.

Keybindings: enter open Neovim, l open kra git log for that repo (pauses scout, restores it on quit), d file-by-file diff picker (opens each changed file in a fugitive split), f fetch, p pull, D/S-d toggle dirty-only filter, r rescan, y copy path, s// search by name · path · branch, Tab cycle panels, q quit.

🛠️ 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 🔍 | Unified search dashboard — find files/dirs by name or grep content, preview, open in Neovim, batch-delete. | | scripts 🧪 | Custom script execution system (experimental) - Run user-defined automation scripts. | | process-manager 📊 | Live ps dashboard - search, sort by CPU/MEM/PID, view per-process details, send SIGTERM/SIGKILL. | | disk-usage 💾 | du-style explorer — scan sizes, expand directories inline, batch-delete, sort by size/name/mtime, open in finder. |

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

Demo Previews - Click to expand

Three search modes: f (files by name), d (directories by name), c (content grep inside files). Results appear in a navigable list with instant preview and metadata panels.

Keybindings: f/d/c switch mode · enter search (in search box) or open in Neovim (on a result) · x delete with confirmation · space toggle batch-select · X delete all selected · y copy path · s// focus search · Tab cycle panels · q quit.

Interactive ps browser with search, sort modes (CPU / MEM / PID), windowed list rendering, per-process details and signal sending (SIGTERM / SIGKILL).

Scan the current directory tree and rank entries by size. Expand directories inline (e / l), batch-select with space and bulk-delete with X. Switch sort modes (s) between size/name/mtime/count. Change root with R, jump home with H, open in finder with o. Live filter via /.

Keybindings: j/k nav · enter descend · - up · e/l expand · space select · X delete selected · o open · s sort · / filter · r refresh · R new root · H home · y yank path · Tab cycle panels · q quit.

🚀 Getting Started

📋 Prerequisites

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

⚡ Quick Installation

Install the published package globally:

npm install -g kra-workflow

# postinstall auto-creates ~/.kra/, copies a default settings.toml,
# and patches your ~/.bashrc / ~/.zshrc / nvim init.lua.

# Restart your shell (or `source ~/.bashrc`) to pick up the autocompletion
# and tmux/neovim hooks, then run `kra`.
kra

Or install from a clone:

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

User data lives under ~/.kra/ by default. Override with KRA_HOME=/path/to/dir. If you previously had the project at ~/programming/kra-tmux/, the first install will copy settings.toml, git-files/, tmux-files/, ai-files/, system-files/, and lock-files/ from there into ~/.kra/ (originals are left in place).

📚 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