killbottleneck

<p align="center"> <img src="assets/znak-velky.webp" alt="killBottleneck" width="420"> </p> <h1 align="center">killBottleneck</h1> <p align="center"> <strong>English</strong> | <a href="./README.cs.md">Čeština</a><br> <a href="https://killbottleneck.com">Website</a> · <a href="https://killbottleneck.com/guide/what-it-is">Documentation</a> · <a href="./CHANGELOG.md">Changelog</a> · <a href="#license--fair-code">Licence</a> </p>

🧪 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:

| Outbound request | When it happens | Turn it off | | --- | --- | --- | | GitHub Releases API | Version check, from the user's browser — not the server | KB_UPDATE_CHECK=0 | | The AI endpoint you configured | Only with KB_AI_PROVIDER ≠ none; your own Ollama or any endpoint you choose | KB_AI_PROVIDER=none (default) | | Google (sign-in, Drive picker) | Only when you configure KB_GOOGLE_* | leave those empty (default) |

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

<details> <summary><strong>Contents</strong> — this README is the full reference; the short version is on <a href="https://killbottleneck.com/guide/quick-start">the website</a>.</summary>

• Quick start
• What it does without AI · On a phone
• AI features (optional)
• AI assistant over MCP
• Who performs a step: a person, or an automation — includes the webhook contract for your own agents
• Moving a project elsewhere (JSON export/import)
• Appearance (skins) · Notifications · Time zone and recurring templates
• Data and backup · Team · Registration and the registration key
• Sign in with Google · Attachments · E-mail (SMTP)
• HTTPS (access from outside) · Updating
• License — fair-code · Contact

</details>

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

<img src="assets/lite-en.jpg" alt="The simplified view on a phone" width="300" align="right">

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.

<br clear="right">

AI features (optional)

The assistant lives in a side panel next to your maps. It plans your day with you (morning briefing, evening planning), sorts notes from a photo, a PDF or a voice note, drafts a whole project after a few questions, prepares a meeting, reviews your week and, for managers, runs a team meeting. It reads your maps itself; every change it proposes is a card you confirm — nothing is written behind your back. E-mails, notes and summaries it writes are kept as documents next to the chat. Besides the assistant there is the wand on a node (sub-steps, milestones, KPIs, risks), an AI project summary and the daily encouragement in My day.

AI 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>. Voice notes are transcribed by the same service when it offers a Whisper / transcribe model; 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. (Runs the wand, the summary and the encouragement; the assistant needs ollama or openai.)
• 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. (Voice notes need a speech-to-text service of your own — see below.)
• custom — your own endpoint honouring the same API contract (the contract is written down here).

The assistant uses the same model unless you give it its own (KB_CHAT_PROVIDER/URL/MODEL/TOKEN). Reading photos needs a vision model (KB_VISION_*, or tick The assistant reads images in Administration → AI). Voice notes work with any speech-to-text in the OpenAI shape (KB_TRANSCRIBE_PROVIDER=openai + KB_TRANSCRIBE_URL — speaches, whisper.cpp, OpenAI…); the recording itself is never stored. Browsers allow the microphone only over HTTPS (or localhost), and a reverse proxy in front must let request bodies of about 5 MB through (a voice note or a photo travels inside the request). More in the assistant guide.

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:

   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):

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

Tools (20): list_maps, get_map, create_map, add_nodes, update_node, delete_node, list_people, get_portfolio, get_org_structure, calendar events and timed reminders (create_event, list_events, create_reminder) 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).

Remote, without anything local: every instance also serves MCP directly at /mcp (Streamable HTTP, same keys, same tools) — claude mcp add --transport http killbottleneck https://your-instance/mcp --header "Authorization: Bearer kb_user_..."; the claude.ai connector signs in through OAuth. Details: MCP server.

Security: a key acts as its owner — it sees and edits exactly what the owner can in the app, shared and team maps included (edit/own = full write; work and read = only the status of the owner's own nodes, exactly like ticking off in the app); it never reads the account's role,