killBottleneck

English | Čeština
Website · Documentation · Changelog · Licence

🧪 Public beta. killBottleneck is feature-complete and in beta — the cloud and the self-hosted version alike; it is one and the same app. What we are testing here is the self-hosted side: installation, reverse proxies, your own SMTP, upgrades. Install it (Quick start below), try to break it, and tell us what happened: bugs → Issues, ideas → Discussions. v1.0 ships when the beta goes quiet.

A visual picture of your projects, your company and its processes — goal maps that people and AI agents work on together, entirely on your own server: your data never leaves the company. Open in the spirit of open source, just without the right to resell it as a hosted service — see License.

Nothing here phones home. On a default install the server sends no request anywhere, and the app loads nothing from a third-party CDN — fonts included, they are served from your own instance. Everything that could leave your network is something you switch on:

There is no telemetry, no analytics and no licence check.

Quick start

All you need is Docker. Then:

cp .env.example .env    # optional — the defaults are fine
docker compose up -d

killBottleneck runs at http://SERVER-IP:8090. Colleagues on the local network just open it in a browser.

The first user to register automatically becomes the administrator. Everyone else can register themselves, or the administrator invites them from Administration (this creates an account with a temporary password to hand over).

What it does without AI

A full goal map editor (nodes, edges, statuses, notes), multiple maps per user, comments on goals, sharing maps with colleagues (read / edit), public maps, export to image/PDF.

The “My day” panel (both the home page and the Tasks page): a clickable overview of overdue / today / within a week / blocking others, computed live from your data; name days next to the date; a portrait PNG export for mobile — both full (with task names) and anonymous (names redacted, for social media). Over HTTPS you also get Share… (your phone's native Web Share dialog, no third-party service involved).

Time tracking: a ⏱ timer in the top bar (one click starts an “empty” measurement — the project/client/goal is assigned while it runs or afterwards), a timer on every task and every goal in a map (measuring never changes a status — it is purely supplementary), a left-hand “Time tracking” panel with the records (from–to, retroactive assignment), a “Time worked” dialog in the user menu (today/this week, broken down by project and client), a client registry (project→client, so time adds up per client too), and auto-stop for forgotten timers after 12 h. Inbox behaviour: an unassigned measurement stopped with a note (e.g. “call with the client”) also saves itself as an idea in your stash.

On a phone

The same instance, opened on a phone, switches to a simplified view: today's tasks, tick them off, add one, and read messages — no map canvas to fight with on a small screen. You can switch back to the full view at any time, and the app can be added to the home screen (over HTTPS) so it behaves like a native one.

More in the Simplified view guide.

AI features (optional)

The AI advisor (draft a map from a goal, expand branches, chat about a map, AI project summary, suggest tasks from a goal, a map from text/voice) is switched on in .env via KB_AI_PROVIDER:

• openai — any OpenAI-compatible API: OpenAI, OpenRouter, Groq, Mistral, Together, or your own vLLM / LM Studio / llama.cpp / liteLLM proxy. Set KB_AI_URL=https://openrouter.ai/api/v1 (the base address, usually ending in /v1), KB_AI_TOKEN=<your API key> and KB_AI_MODEL=<exact model name>. Dictation works through the same service; your provider bills you for the requests.
• api — a remote AI service compatible with the killBottleneck API contract: enter the address and token you got from your provider. No GPU of your own and no maintenance.
• ollama — your own local model: install Ollama, pull a model (ollama pull gpt-oss:20b) and set KB_AI_URL=http://IP:11434 + KB_AI_MODEL=gpt-oss:20b. Everything runs on your side, no data leaves your network. (Basic prompts; voice transcription is not included.)
• custom — your own endpoint honouring the same API contract (the contract is written down here).

When AI is used, map data is sent to the endpoint you chose; with none (the default) nothing ever leaves your server.

Daily AI encouragement (a line in the My day panel): 1–2 sentences prioritising “what blocks others → overdue → today”, with the occasional proverb. It is generated in the morning by a cron job (KB_SUMMARY_HOUR, default 6) only for accounts that signed in within the last KB_SUMMARY_ACTIVE_DAYS days (default 14, 0 = everyone); for the rest it is generated when they open the app. Optionally a separate (smaller/faster) model just for the summaries: KB_SUMMARY_PROVIDER/URL/MODEL/TOKEN — without them the general AI configuration above is used. The panel works in full without AI, just without this one line. The AI never enumerates task lists (those are computed from your data and clickable) and task names are sanitised before they go into the prompt.

AI assistant over MCP (Claude Desktop, Claude Code, …)

killBottleneck ships with a built-in MCP server (mcp/): connect your AI assistant to your own instance and maps get built conversationally — “make a map out of these meeting notes”, bulk edits, ticking off what's done. It works the same for self-hosted and hosted instances, only the address differs.

1. In the app: user menu → API keys → a new key with the Read and write scope (Read only is enough for read access). The token is shown only once. Recommended: give the key an expiry and revoke it once you stop using it.

2. Nothing to install — the server is on npm as killbottleneck-mcp, so npx fetches it on first use. (Prefer running it from this repository? cd mcp && npm install and use node /absolute/path/mcp/index.js instead of the npx command below.)

3. Register it with your assistant:

   Claude Code:

   Terminal

   Copy

   claude mcp add killbottleneck \
     -e KB_URL=http://SERVER-IP:8090 \
     -e KB_API_KEY=kb_user_... \
     -- npx -y killbottleneck-mcp
   

   Claude Desktop (claude_desktop_config.json → mcpServers):

   config.json

   Copy

   {
     "mcpServers": {
       "killbottleneck": {
         "command": "npx",
         "args": ["-y", "killbottleneck-mcp"],
         "env": {
           "KB_URL": "http://SERVER-IP:8090",
           "KB_API_KEY": "kb_user_..."
         }
       }
     }
   }
   

Tools (17): list_maps, get_map, create_map, add_nodes, update_node, delete_node, list_people, get_portfolio, get_org_structure and the rule tools (create_rule, list_rules, update_rule, delete_rule, list_rule_runs, list_rule_templates, save_rule_template, delete_rule_template). A goal with an assignee or a deadline IS a task — there are no separate task records. Assigning an owner through the API shares the map with that person as a collaborator, so the work shows up in their My Day (the response lists who was shared with).

Read the full README on GitHub →