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](../../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](#license--fair-code).

![The goal map editor](assets/mapa-en.jpg)

**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](#quick-start)
- [What it does without AI](#what-it-does-without-ai) · [On a phone](#on-a-phone)
- [AI features (optional)](#ai-features-optional)
- [AI assistant over MCP](#ai-assistant-over-mcp-claude-desktop-claude-code-)
- [Who performs a step: a person, or an automation](#who-performs-a-step-a-person-or-an-automation) — includes the **webhook contract** for your own agents
- [Moving a project elsewhere (JSON export/import)](#moving-a-project-elsewhere-json-export-and-import)
- [Appearance (skins)](#appearance-skins) · [Notifications](#notifications) · [Time zone and recurring templates](#time-zone-and-recurring-templates)
- [Data and backup](#data-and-backup) · [Team](#team) · [Registration and the registration key](#registration-and-the-registration-key)
- [Sign in with Google](#sign-in-with-google-optional) · [Attachments](#attachments-on-goals-a-file-or-a-link) · [E-mail (SMTP)](#e-mail-smtp-optional)
- [HTTPS (access from outside)](#https-access-from-outside) · [Updating](#updating)
- [License — fair-code](#license--fair-code) · [Contact](#contact)

</details>

## Quick start

All you need is Docker. Then:

```bash
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](assets/muj-den-en.jpg)

**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](https://killbottleneck.com/features/lite-view).

<br clear="right">

## AI features (optional)

![Drafting a map with AI](assets/ai-navrhnout-en.jpg)

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](https://ollama.com), 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](https://killbottleneck.com/reference/custom-ai-endpoint)).

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`](https://www.npmjs.com/package/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:**
   ```bash
   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`):
   ```json
   {
     "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).

**Remote, without anything local:** every instance