Katasumi (隅) - Your Corner Companion for Keyboard Shortcuts

Katasumi (カタスミ / 隅) - meaning "in the corner" - is an AI-powered keyboard shortcut discovery tool that stays quietly in the background, ready to help whenever you need it.

Like a helpful friend waiting in the corner of your workspace, Katasumi provides instant access to keyboard shortcuts across terminal and desktop applications, supporting you without getting in the way.

Personal note: I wrote this app for myself, since I try to be extremely keyboard centric in all my workflows, I wanted to get better at finding and learning shortcuts for all the apps I use. The problem is that there are many, they change often, and they all have different shortcuts documented on various web sites. So this tool is to help consolidate and simplify the day-to-day search required.

A lot of this is still a work in progress, a lot is "vibe-coded" but with a lot of supervision from me and its just now moving into more of a UAT phase where I am doing all the testing. I hope someone else will find it useful and helpful and want to contribute. If you do please drop me a note as a GH issue and I will work on getting you free access for now.

📑 Table of Contents

• Philosophy
• Features
• AI Setup for Free Users
  • Getting Your API Key
  • Configuration Methods
  • Configuration Examples
  • Troubleshooting
  • Security Best Practices
• Architecture
• Getting Started
  • Quick Install (TUI)
  • Running in Quake Mode
• Database Strategy
• Documentation
• Development
• Contributing
  • Development Environment Setup
  • Development Workflow
  • Testing & Running
• License

🎯 Philosophy

The name "katasumi" embodies our design philosophy:

• Always There: Like something resting in the corner, always accessible but never intrusive
• Background Support: Provides help exactly when you need it, then gets out of your way
• Quiet Helper: Runs unobtrusively, blending into your workflow
• Reliable Companion: Dependable support for your daily productivity

✨ Features

Terminal Interface (TUI)

• 🚀 Lightning-fast fuzzy search for keyboard shortcuts
• 📦 Works 100% offline with bundled shortcuts database
• 🎨 Multiple search modes: App-First, Full-Phrase, and Detail View
• 💾 Local caching of custom shortcuts
• 🤖 AI-powered scraping for long-tail applications (optional)

Web Interface

• 🌐 Accessible from any browser
• 🔍 Shared database of curated shortcuts
• 💎 Premium tier with managed API keys for AI searches
• 📱 Responsive design for desktop and mobile

Premium vs Free Tier

Premium Features (require account + subscription):

• 🔄 Multi-device sync for shortcuts and collections
• 🤖 Built-in AI search (no API key needed)
• ☁️ Cloud storage for user shortcuts
• 🎯 Unlimited AI queries

Free Features (no account needed):

• 🔍 Full keyword search functionality
• 💻 Local-only TUI usage
• 🤖 AI search with your own API key
• 📝 Local shortcut creation and editing

🤖 AI Setup for Free Users

Free tier users can access AI-powered shortcut search by configuring their personal API key. Premium users enjoy built-in AI with no setup required.

💰 Cost Estimate: Typical usage costs $0.50-$2/month with a personal API key, depending on your search frequency.

Getting Your API Key

Choose one of these AI providers:

| Provider | Get API Key | Pricing | |----------|-------------|---------| | OpenAI | platform.openai.com/api-keys | View Pricing | | Anthropic (Claude) | console.anthropic.com/settings/keys | View Pricing | | OpenRouter | openrouter.ai/keys | View Pricing | | Ollama | Run locally | Free (runs on your machine) |

Configuration Methods

Method 1: Config File (Recommended)

1. Create the configuration directory:

   mkdir -p ~/.katasumi

2. Create ~/.katasumi/config.json:

   {
     "ai": {
       "provider": "openai",
       "apiKey": "sk-your-api-key-here",
       "model": "gpt-4"
     }
   }

3. Launch Katasumi and press F4 or 'a' to toggle AI search mode

Method 2: Environment Variables

Set environment variables before running Katasumi:

export KATASUMI_AI_PROVIDER=openai
export KATASUMI_AI_KEY=sk-your-api-key-here
export KATASUMI_AI_MODEL=gpt-4

# Optional: Custom API endpoint
export KATASUMI_AI_BASE_URL=https://api.openai.com/v1

Then launch Katasumi as usual:

katasumi

Method 3: TUI Command (Interactive)

Launch Katasumi and use the config command:

katasumi config set ai.provider openai
katasumi config set ai.apiKey sk-your-api-key-here
katasumi config set ai.model gpt-4

Configuration Examples

OpenAI (GPT-4)

{
  "ai": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-4",
    "baseUrl": "https://api.openai.com/v1"
  }
}

Anthropic (Claude)

{
  "ai": {
    "provider": "anthropic",
    "apiKey": "sk-ant-...",
    "model": "claude-3-opus-20240229"
  }
}

OpenRouter (Multiple Models)

{
  "ai": {
    "provider": "openrouter",
    "apiKey": "sk-or-...",
    "model": "anthropic/claude-3-opus",
    "baseUrl": "https://openrouter.ai/api/v1"
  }
}

Ollama (Local)

{
  "ai": {
    "provider": "ollama",
    "model": "llama2",
    "baseUrl": "http://localhost:11434/v1"
  }
}

Note: Ollama runs locally and doesn't require an API key

Using AI in the TUI

1. Launch Katasumi: katasumi
2. Toggle AI Mode: Press F4 or 'a' key
3. Search with AI: Type natural language queries like:
   • "shortcuts for commenting code in vim"
   • "how to split window in tmux"
   • "vscode keyboard shortcuts for debugging"

Web Interface Usage

For API requests to /api/ai, include your API key:

fetch('/api/ai', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: "vim shortcuts for navigation",
    userApiKey: "sk-...",
    aiProvider: "openai"
  })
})

Troubleshooting

"Invalid API Key" Error

• Check your API key is correct and active
• Verify provider matches your API key type (OpenAI keys don't work with Anthropic, etc.)
• Check account billing - ensure your provider account has billing enabled

"Rate Limit Exceeded" Error

• Wait a few minutes and try again
• Upgrade your API plan with your provider
• Reduce query frequency or switch to a different provider

AI Toggle Not Working

• Verify configuration exists at ~/.katasumi/config.json
• Check permissions: chmod 600 ~/.katasumi/config.json
• Validate JSON syntax using jq . ~/.katasumi/config.json

Ollama Connection Issues

• Start Ollama: ollama serve
• Pull a model: ollama pull llama2
• Check baseUrl points to http://localhost:11434/v1

🔒 Security Best Practices

⚠️ Important Security Notes:

• Never commit config.json to version control
• Never share your API keys publicly or in screenshots
• Use environment variables in CI/CD pipelines instead of config files
• Rotate keys regularly if you suspect they've been exposed
• Set spending limits in your AI provider account settings
• Use read-only keys if your provider offers them

Premium vs Free AI Features

| Feature | Free (Your API Key) | Premium (Built-in) | |---------|---------------------|-------------------| | AI Search | ✅ Yes | ✅ Yes | | Configuration Required | ✅ Yes | ❌ No | | API Key Management | 👤 You manage | 🏢 We manage | | Cost | 💵 You pay provider | 💎 Included in subscription | | Query Limits | Provider-dependent | ♾️ Unlimited | | Setup Time | ~5 minutes | ⚡ Instant |

🏗️ Architecture

Katasumi uses a monorepo structure with shared core logic:

katasumi/
├── packages/
│   ├── core/              # Shared search & scraping logic
│   ├── tui/               # Terminal interface
│   └── web/               # Web interface (React/Next.js)
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

Tech Stack

Core (Shared)

• TypeScript
• Prisma ORM (SQLite + PostgreSQL schemas live in core)
• Keyword search + Optional AI (OpenAI/Claude/Ollama)

TUI

• SQLite for local storage
• Zero-config setup
• Fast local queries (<10ms)

Web

• Next.js (React) + Vercel
• PostgreSQL (Supabase/Vercel Postgres)
• Tailwind CSS

🚀 Getting Started

Quick Install (TUI)

Install Katasumi globally for instant access from any terminal:

npm install -g @katasumi/tui

Then launch it with:

katasumi

Note: Global installation is not yet available as the package has not been published to npm. For development and contribution setup, see the Contributing section below.

Running Unobtrusively

Katasumi is designed to stay out of your way. The best way to achieve this is to run it in "quake mode" — a dropdown terminal that slides in from the top of the screen on a global hotkey, just like the console in the original Quake game. Press the hotkey once to summon Katasumi, press it again to send it back to the corner. This perfectly embodies the 隅 philosophy.

Quake Mode Setup by Terminal

Windows Terminal (Windows) (Recommended for Windows users)

Windows Terminal has built-in quake mode support:

1. Press Win + ` (backtick) to open Windows Terminal in quake mode — it drops down from the top of the screen instantly.
2. Set Katasumi as your default profile so it launches automatically:
   • Open Windows Terminal settings (Ctrl+,)
   • Under Startup → Default profile, select the profile you use for Katasumi
   • Or add a dedicated Katasumi profile with katasumi as the command
3. Now Win + ` drops Katasumi in from the top whenever you need it.

Tip: You can pin the quake-mode window to a specific monitor in Windows Terminal settings under Appearance → Launch size → Quake mode.

iTerm2 (macOS)

1. Open iTerm2 Preferences → Keys → Hotkey
2. Enable "Show/hide all windows with a system-wide hotkey" and set your preferred key (e.g., `⌘ + ``)
3. Create a dedicated profile for Katasumi:
   • Go to Profiles → + → name it "Katasumi"
   • Under General → Command, set it to katasumi
   • Under Window → Style, choose Full-Width Top of Screen for the classic quake look
4. Assign the hotkey to the Katasumi profile under Keys → Hotkey Window

Guake (Linux/GNOME)

# Install Guake
sudo apt install guake      # Debian/Ubuntu
sudo dnf install guake      # Fedora

# Launch and configure
guake &
guake-prefs  # Open preferences

In preferences, set the command to katasumi under Shell → Default interpreter and configure your preferred hotkey (default is F12).

Yakuake (Linux/KDE)

sudo apt install yakuake    # Debian/Ubuntu
sudo dnf install yakuake    # Fedora

Yakuake defaults to F12 as the toggle hotkey. Set the default shell command to katasumi in Settings → Configure Yakuake → Behavior.

tmux (Any terminal)

For a portable approach that works anywhere:

# Add to ~/.bashrc or ~/.zshrc
alias ks='tmux new-session -A -s katasumi katasumi'

Then bind ks to a global hotkey in your desktop environment for a similar effect.

Tips for the Best Experience

• TUI Mode: Assign a global keyboard shortcut to launch Katasumi instantly
• Background Process: Run the TUI in a tmux/screen session for persistent access
• Web Bookmarklet: Save the web version as a bookmarklet for quick browser access

📊 Database Strategy

Katasumi uses a hybrid approach:

• Bundled Core DB: Ships with shortcuts for popular apps (vim, tmux, VSCode, etc.)
• Local Cache: Stores your custom and scraped shortcuts
• On-Demand Scraping: AI-powered scraping for long-tail applications
• Community Contributions: Core database enhanced by community via GitHub

📚 Documentation

For detailed documentation, see:

• API Documentation - Complete TypeDoc-generated API reference for the core package
• KEYBOARD_SHORTCUTS.md - Comprehensive keyboard navigation guide and implementation details
• ADMIN.md - Administrator guide for user provisioning and premium account management
• DEVELOPMENT_PRIORITIES.md - Development roadmap and priorities
• katasumi-plan.md - Detailed project planning

🛠️ Development

This project is currently in early development. We use a monorepo structure with Turborepo for efficient builds and development.

Tech Stack

• TypeScript - Type-safe code across all packages
• Prisma - Database ORM with SQLite and PostgreSQL support
• Ink - React for terminal UIs (TUI)
• Next.js - React framework for web application
• Turborepo - Monorepo build system

🤝 Contributing

We welcome contributions from developers of all skill levels! Whether you're fixing a bug, adding a feature, improving documentation, or suggesting ideas, your help is appreciated.

Quick Links:

• CONTRIBUTING.md - Comprehensive contribution guide
• DEVELOPMENT.md - Detailed development setup and troubleshooting
• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions and share ideas

Development Environment Setup

Prerequisites

• Node.js 18+ and npm (or pnpm)
• Docker and Docker Compose (recommended)
• OR PostgreSQL 14+ (if not using Docker)

Quick Setup (Automated)

For the fastest setup, use our automated script:

git clone https://github.com/ClearsiteConsultants/katasumi.git
cd katasumi
./quick-setup.sh

This script will:

• Start PostgreSQL via Docker (if available)
• Copy environment configuration files
• Install dependencies
• Build and seed both SQLite (TUI) and PostgreSQL (Web) databases

Manual Setup

1. Clone and install:

   git clone https://github.com/ClearsiteConsultants/katasumi.git
   cd katasumi
   pnpm install

2. Start PostgreSQL:

   docker-compose up -d  # Using Docker
   # OR see DEVELOPMENT.md for manual PostgreSQL installation

3. Configure environment:

   cp packages/core/.env.example packages/core/.env
   cp packages/web/.env.example packages/web/.env.local

4. Build and seed databases:

   pnpm run setup:tui  # SQLite for TUI
      
   # PostgreSQL for Web
   cd packages/core
   DATABASE_URL="postgres://katasumi:dev_password@localhost:5432/katasumi_dev" DB_TYPE="postgres" pnpm run migrate
   DATABASE_URL="postgres://katasumi:dev_password@localhost:5432/katasumi_dev" pnpm run seed
   cd ../..

5. Start development:

   pnpm run dev  # Starts both TUI and Web

For detailed instructions and troubleshooting, see DEVELOPMENT.md.

Development Workflow

Working on different packages:

# Core package (shared logic)
pnpm run build --workspace=@katasumi/core

# TUI (terminal interface)
pnpm run dev --workspace=@katasumi/tui
pnpm run start:tui  # Test the TUI

# Web (Next.js app)
pnpm run dev --workspace=@katasumi/web
# Visit http://localhost:3000

Database operations:

pnpm run migrate:status      # Check migration status
pnpm run migrate:rollback    # Rollback last migration
pnpm run seed                # Re-seed database
pnpm run build-db            # Rebuild TUI database

PostgreSQL schema and migrations live in packages/core/prisma/schema.postgres.prisma and packages/core/migrations.

Testing & Running

Run tests:

pnpm test                              # All tests
pnpm test --workspace=@katasumi/core  # Specific package
pnpm test -- --watch                   # Watch mode

Type checking:

pnpm run typecheck                         # All packages
pnpm run typecheck --workspace=@katasumi/core  # Specific package

Test applications:

pnpm run start:tui   # Test TUI interactively
pnpm run start:web   # Start web app (http://localhost:3000)

How to Contribute

1. Fork the repository to your GitHub account
2. Clone your fork locally
3. Create a branch for your changes: git checkout -b feature/my-feature
4. Make your changes with clear, atomic commits
5. Test thoroughly - run pnpm test and pnpm run typecheck
6. Push to your fork: git push origin feature/my-feature
7. Open a Pull Request with a clear description

Before submitting:

• ✅ All tests pass (pnpm test)
• ✅ Code is properly typed (pnpm run typecheck)
• ✅ Documentation is updated if needed
• ✅ Commit messages follow Conventional Commits

For more details, see CONTRIBUTING.md.

📝 License

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

Copyright (c) 2026 Josh Pitkin

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Katasumi - Always there in your corner, ready to help. 隅