@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.
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
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. Here are some tips for running it unobtrusively:
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 4 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
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.
Security News
Socket releases free Certified Patches for high-severity Nuxt vulnerabilities, including server-side remote code execution through server island props.