specs

CleverKeys Technical Specifications

Technical documentation for CleverKeys, an Android keyboard with neural swipe typing. These specs are designed for LLM coding agents to understand the codebase architecture and implementation details.

Specification Index

Core System

Spec	Description
Core Keyboard System	InputMethodService, view hierarchy, key events, layout management
Suggestion Bar & Content Pane	Word predictions, emoji/clipboard pane, ViewFlipper swap
Gesture System	Swipe detection, multi-touch, gesture classification
Layout System	XML layouts, ExtraKeys, key positioning

Neural Prediction

Spec	Description
Neural Prediction	ONNX transformer, beam search, vocabulary
Neural Multilanguage	Multi-language swipe typing architecture
Cursor-Aware Predictions	Context-aware prediction enhancement
KV-Cache Optimization	ONNX inference optimization
Memory Pool Optimization	Memory management for neural inference

Dictionary & Language

Spec	Description
Dictionary System	Word lookup, frequency ranking, user dictionary
Secondary Language	Multi-language typing, language detection
Language-Specific Dictionary	Per-language dictionary management

Customization

Spec	Description
Short Swipe Customization	Per-key gesture customization, CommandRegistry
Per-Layout Subkey	Layout-specific subkey configuration
Subkey Customization	Current subkey implementation details
Profile System	Settings backup/restore, layout import/export

Settings & Modes

Spec	Description
Settings System	SharedPreferences, settings UI, configuration
Settings-Layout Integration	GUI mapping to layout system
Cursor Navigation	Spacebar slider, arrow key navigation
TrackPoint Mode	Joystick-style cursor control
Selection-Delete Mode	Text selection via backspace gesture
Password Field Mode	Secure password input handling

Features

Spec	Description
Quick Settings Tile	Android notification shade tile
Clipboard Privacy	Password manager exclusion
Timestamp Keys	Date/time insertion keys
Termux Integration	Terminal keyboard optimizations

Reference

Spec	Description
Architectural Decisions	ADRs for major design choices
Performance Optimization	Rendering, memory, ONNX performance
SPEC_TEMPLATE.md	Template for new specifications

Key Source Files

File	Purpose
CleverKeysService.kt	Main InputMethodService
Keyboard2View.kt	Custom view rendering
Keyboard2.kt	Key layout and state management
KeyEventHandler.kt	Key press processing
InputConnectionManager.kt	Text editing interface
Pointers.kt	Touch handling and gestures
Config.kt	All settings with defaults
SettingsActivity.kt	Settings UI (Jetpack Compose)
KeyValue.kt	Key definitions (300+ keys)
SwipeTrajectoryProcessor.kt	Neural swipe processing
OptimizedVocabulary.kt	Dictionary management

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    CleverKeysService                        │
│                  (InputMethodService)                       │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────┐  │
│  │ Keyboard2View  │  │ KeyEventHandler│  │ InputConnection│ │
│  │ (Rendering)    │  │ (Processing)   │  │ Manager       │ │
│  └───────┬────────┘  └───────┬────────┘  └──────┬───────┘  │
│          │                   │                   │          │
│  ┌───────▼────────┐  ┌───────▼────────┐         │          │
│  │   Keyboard2    │  │   Pointers     │         │          │
│  │ (Layout/State) │  │ (Touch/Gesture)│         │          │
│  └───────┬────────┘  └───────┬────────┘         │          │
│          │                   │                   │          │
│  ┌───────▼───────────────────▼───────────────────▼───────┐  │
│  │                    Config                              │  │
│  │            (Settings, Preferences)                     │  │
│  └────────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                  Neural Prediction Pipeline                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Swipe      │  │    ONNX      │  │  Vocabulary  │       │
│  │  Trajectory  │→ │  Inference   │→ │   Filter     │       │
│  │  Processor   │  │  (Encoder/   │  │ (Dictionary) │       │
│  │              │  │   Decoder)   │  │              │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘

Common Patterns

Settings Access

// Read setting
val value = Config.globalConfig().settingName

// Save setting
Config.globalConfig().apply {
    settingName = newValue
    saveSetting("setting_key", newValue)
}

Key Event Handling

// In KeyEventHandler
fun handleKeyPress(key: KeyValue): Boolean {
    return when (key.kind) {
        Kind.Char -> commitText(key.char.toString())
        Kind.String -> commitText(key.string)
        Kind.Modifier -> handleModifier(key)
        Kind.Event -> handleEvent(key.event)
        // ... other kinds
    }
}

Gesture Classification

// In Pointers.kt
fun classifyGesture(pointer: Pointer): GestureType {
    return when {
        pointer.isSwipeTyping -> GestureType.SWIPE_TYPING
        pointer.isShortSwipe -> GestureType.SHORT_SWIPE
        pointer.isLongPress -> GestureType.LONG_PRESS
        else -> GestureType.TAP
    }
}

Related Documentation

• User Guide Wiki - End-user documentation
• CHANGELOG - Version history
• TODO - Current tasks