Keystorm

An AI-native programming editor written in Go.

Keystorm combines the modal editing power of Vim with modern IDE capabilities and deep AI integration. Built from the ground up to be extensible, performant, and AI-aware.

Features

Editor Capabilities

• Modal Editing - Vim-style modes (Normal, Insert, Visual, Command)
• Multi-cursor Support - Edit multiple locations simultaneously
• Syntax Highlighting - Fast, tree-sitter-ready highlighting
• 60+ FPS Rendering - Smooth terminal rendering with dirty region updates
• Undo/Redo - Full command pattern with branching history
• Macro Recording - Record and playback keystroke sequences

Project Intelligence

• Workspace Model - Project-aware file management
• File Watching - Automatic detection of external changes
• Fuzzy Search - Fast file and content search
• Project Graph - Understand relationships between files, modules, and tests

Language Support

• LSP Integration - Completions, diagnostics, go-to-definition, formatting
• Multi-language - Per-language configuration and settings
• Semantic Highlighting - Enhanced token-based coloring

Extensibility

• Lua Plugins - Lightweight, sandboxed plugin system
• Capability-based Security - Fine-grained plugin permissions
• Event System - Pub/sub architecture for loose coupling
• Custom Keymaps - Full keybinding customization

AI Integration (Planned)

• Context Engine - Curated context from project graph for AI prompts
• Intent Router - Maps user actions to AI workflows
• Agent Runtime - Coder, Reviewer, Planner, and Verifier agents
• Diff-based Proposals - AI suggestions as reviewable diffs

Requirements

• Go 1.25 or later
• A terminal with true color support (recommended)

Installation

From Source

# Clone the repository
git clone https://github.com/dshills/keystorm.git
cd keystorm

# Build
make build

# Install to GOPATH/bin
make install

Binary

The built binary will be at ./bin/keystorm.

Usage

# Open with empty buffer
keystorm

# Open a file
keystorm file.go

# Open multiple files
keystorm main.go utils.go config.go

# Open a workspace
keystorm -w ./my-project

# Open in read-only mode
keystorm -R important-file.go

Command Line Options

Flag	Description
-c, --config <path>	Path to configuration file
-w, --workspace <path>	Workspace/project directory
-d, --debug	Enable debug mode
--log-level <level>	Log level: debug, info, warn, error
-R, --readonly	Open files in read-only mode
-v, --version	Show version information
-h, --help	Show help message

Configuration

Keystorm uses a layered configuration system (highest to lowest priority):

1. Command-line arguments
2. Environment variables
3. Plugin settings
4. Project config (.keystorm/config.toml)
5. User keymaps (~/.config/keystorm/keymaps.toml)
6. User settings (~/.config/keystorm/settings.toml)
7. Built-in defaults

Example Configuration

# ~/.config/keystorm/settings.toml

[editor]
tab_size = 4
insert_spaces = true
line_numbers = true
relative_numbers = false
wrap_lines = false
cursor_style = "block"

[editor.theme]
name = "default"

[languages.go]
tab_size = 4
insert_spaces = false

[languages.python]
tab_size = 4
insert_spaces = true

Architecture

Keystorm is built with a modular architecture consisting of 10 core components:

internal/
├── engine/       # Text buffer with B+ tree rope, undo/redo, multi-cursor
├── renderer/     # Terminal display, syntax highlighting, viewport
├── input/        # Keystroke handling, mode management, command palette
├── dispatcher/   # Input → action mapping with context awareness
├── event/        # Pub/sub event bus for component communication
├── config/       # 7-layer configuration system with live reload
├── plugin/       # Lua plugin system with sandboxing
├── lsp/          # Language Server Protocol client
├── project/      # Workspace model with file graph
├── integration/  # Terminal, Git, debugger, task runner
└── app/          # Application coordinator and lifecycle

Design Principles

• AI-Agnostic Core - Editor layer is solid and independent
• Event-Driven - Loose coupling via pub/sub messaging
• Thread-Safe - Concurrent access with proper synchronization
• Minimal Dependencies - Lean on Go's standard library

Development

Prerequisites

# Install golangci-lint for linting
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Building

make build          # Build optimized binary
make build-debug    # Build with debug symbols
make run            # Build and run

Testing

make test           # Run all tests
make test-race      # Run with race detector
make test-short     # Run short tests only
make coverage       # Generate coverage report
make bench          # Run benchmarks

Code Quality

make fmt            # Format code
make vet            # Run go vet
make lint           # Run golangci-lint
make check          # Run fmt, vet, and lint

Dependencies

make tidy           # Tidy go.mod
make deps           # Download dependencies
make verify         # Verify dependencies
make update         # Update all dependencies

Plugin Development

Keystorm supports Lua plugins with a capability-based security model.

Example Plugin

-- ~/.config/keystorm/plugins/hello/init.lua

local ks = require("ks")

-- Plugin metadata
local M = {
    name = "hello-world",
    version = "1.0.0",
    description = "A simple hello world plugin"
}

function M.setup(config)
    -- Register a command
    ks.command.register("HelloWorld", function()
        ks.ui.message("Hello from Lua!")
    end)

    -- Add a keybinding
    ks.keymap.set("n", "<leader>h", ":HelloWorld<CR>")
end

return M

Available Capabilities

Capability	Description
filesystem.read	Read files
filesystem.write	Write files
network	Network access
shell	Shell command execution
clipboard	Clipboard access
process.spawn	Spawn processes
unsafe	Full Lua stdlib (trusted plugins only)

Project Structure

keystorm/
├── cmd/keystorm/       # Entry point
├── internal/           # Core packages (not importable)
├── pkg/                # Public API (future)
├── design/             # Architecture and specs
│   ├── specs/          # Design documents
│   └── plans/          # Implementation plans
├── bin/                # Build output
├── coverage/           # Test coverage reports
├── Makefile            # Build automation
├── go.mod              # Go module definition
└── README.md           # This file

Dependencies

Package	Purpose
tcell/v2	Terminal handling
fsnotify	File system notifications
go-toml/v2	TOML configuration
gopher-lua	Lua scripting

Roadmap

Completed

• Core text engine with B+ tree rope
• Terminal rendering with tcell
• Modal input system
• Action dispatcher
• Event bus with pub/sub
• Configuration system
• Lua plugin system
• LSP client
• Project workspace model
• Application integration

In Progress

• Performance optimization
• Extended test coverage
• Documentation improvements

Planned

• AI orchestration layer
• Context engine for AI prompts
• Agent runtime (Coder, Reviewer, Planner)
• Model registry with provider abstraction
• Inline AI completions
• Multi-file refactoring with AI

Contributing

Contributions are welcome! Please ensure:

1. Code passes all checks: make check
2. Tests pass with race detector: make test-race
3. New features include tests
4. Commits follow conventional commit format

License

[License information to be added]

Acknowledgments

Keystorm draws inspiration from:

• Vim - Modal editing
• Neovim - Lua extensibility
• VS Code - LSP and extensions
• Helix - Modern terminal editor design