@katasumi/tui
Advanced tools
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.
The name "katasumi" embodies our design philosophy:
Premium Features (require account + subscription):
Free Features (no account needed):
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.
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) |
Create the configuration directory:
mkdir -p ~/.katasumi
Create ~/.katasumi/config.json:
{
"ai": {
"provider": "openai",
"apiKey": "sk-your-api-key-here",
"model": "gpt-4"
}
}
Launch Katasumi and press F4 or 'a' to toggle AI search mode
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
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
{
"ai": {
"provider": "openai",
"apiKey": "sk-...",
"model": "gpt-4",
"baseUrl": "https://api.openai.com/v1"
}
}
{
"ai": {
"provider": "anthropic",
"apiKey": "sk-ant-...",
"model": "claude-3-opus-20240229"
}
}
{
"ai": {
"provider": "openrouter",
"apiKey": "sk-or-...",
"model": "anthropic/claude-3-opus",
"baseUrl": "https://openrouter.ai/api/v1"
}
}
{
"ai": {
"provider": "ollama",
"model": "llama2",
"baseUrl": "http://localhost:11434/v1"
}
}
Note: Ollama runs locally and doesn't require an API key
katasumiFor 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"
})
})
~/.katasumi/config.jsonchmod 600 ~/.katasumi/config.jsonjq . ~/.katasumi/config.jsonollama serveollama pull llama2http://localhost:11434/v1⚠️ Important Security Notes:
config.json to version control| 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 |
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
Core (Shared)
TUI
Web
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.
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.
Windows Terminal (Windows) (Recommended for Windows users)
Windows Terminal has built-in quake mode support:
Ctrl+,)katasumi as the commandTip: You can pin the quake-mode window to a specific monitor in Windows Terminal settings under Appearance → Launch size → Quake mode.
iTerm2 (macOS)
katasumiGuake (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.
Katasumi uses a hybrid approach:
For detailed documentation, see:
This project is currently in early development. We use a monorepo structure with Turborepo for efficient builds and development.
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:
For the fastest setup, use our automated script:
git clone https://github.com/ClearsiteConsultants/katasumi.git
cd katasumi
./quick-setup.sh
This script will:
Clone and install:
git clone https://github.com/ClearsiteConsultants/katasumi.git
cd katasumi
pnpm install
Start PostgreSQL:
docker-compose up -d # Using Docker
# OR see DEVELOPMENT.md for manual PostgreSQL installation
Configure environment:
cp packages/core/.env.example packages/core/.env
cp packages/web/.env.example packages/web/.env.local
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 ../..
Start development:
pnpm run dev # Starts both TUI and Web
For detailed instructions and troubleshooting, see DEVELOPMENT.md.
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.
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)
git checkout -b feature/my-featurepnpm test and pnpm run typecheckgit push origin feature/my-featureBefore submitting:
pnpm test)pnpm run typecheck)For more details, see CONTRIBUTING.md.
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. 隅
FAQs
Terminal UI for Katasumi keyboard shortcut search
The npm package @katasumi/tui receives a total of 5 weekly downloads. As such, @katasumi/tui popularity was classified as not popular.
We found that @katasumi/tui demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A compromised jscrambler npm release added a malicious preinstall hook that runs hidden native binaries on Linux, macOS, and Windows.
Research
/Security News
A malicious .NET package is typosquatting the Braintree SDK to steal live payment card data, merchant API keys, and host secrets from production apps.
Security News
/Research
Compromised Injective SDK npm version 1.20.21 exfiltrates wallet private keys and mnemonics through fake telemetry functionality.