Home

Welcome to the kim wiki! fix this remove claude

KIM — Keep In Mind 🧠

Lightweight cross-platform reminder daemon for developers. No UI. Config-driven. Runs in the background.

---

Table of Contents

• Overview
• How It Works
• Installation
• Uninstallation
• CLI Reference
• Configuration
• Slack Integration
• Building from Source
• Releasing Binaries
• Troubleshooting
• Roadmap

---

Overview

KIM is a developer-focused reminder daemon that runs quietly in the background and fires desktop notifications at configured intervals. It is built entirely on the Python standard library — no pip dependencies required — and supports Linux, macOS, and Windows out of the box.

Key design principles:

• No GUI, no Electron, no bloat
• Single config file (~/.kim/config.json)
• Autostart on login via native OS mechanisms
• Each reminder runs in its own thread

---

How It Works

Platform	Autostart Mechanism	Notification Method
Linux	systemd user service	notify-send
macOS	launchd agent	osascript
Windows	Task Scheduler	PowerShell toast

---

Slack Integration

KIM can send reminders to a Slack channel in addition to desktop notifications.

Add Slack config

{
  "reminders": [...],
  "sound": true,
  "slack": {
    "enabled": true,
    "webhook_url": "https://hooks.slack.com/services/...",
    "bot_token": "xoxb-...",
    "channel": "#general"
  }
}

Authentication methods

Webhook (simpler): Create an incoming webhook at https://api.slack.com/messaging/webhooks and paste the URL into webhook_url.

Bot Token (more control): Create a Slack app, add the chat:write scope, install it to your workspace, and paste the bot token into bot_token.

You only need one method — use whichever fits your setup.

Test your Slack setup

kim slack --test

Apply changes

kim stop && kim start

---

Building from Source

KIM uses PyInstaller to produce self-contained binaries. Since PyInstaller cannot cross-compile, each platform's binary must be built on the matching OS.

Build locally

pip install pyinstaller
pyinstaller --onefile --name kim kim.py
# Output: ./dist/kim  (or ./dist/kim.exe on Windows)

Build all platforms via GitHub Actions

Add .github/workflows/build.yml to your repo:

name: Build & Attach Binaries
on:
workflow_dispatch:
inputs:
tag:
description: "Release tag to attach binaries to (e.g. v1.0.0)"
required: true
default: "v1.0.0"
permissions:
contents: write
jobs:
build:
strategy:
matrix:
include:
- os: ubuntu-latest
artifact: kim-linux
- os: macos-latest
artifact: kim-macos
- os: windows-latest
artifact: kim-windows.exe
runs-on: ${{ matrix.os }}

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-python@v5
    with:
      python-version: "3.11"

  - name: Install PyInstaller
    run: pip install pyinstaller

  - name: Build binary
    run: pyinstaller --onefile --name ${{ matrix.artifact }} kim.py

  - name: Upload to release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: gh release upload ${{ inputs.tag }} dist/${{ matrix.artifact }} --clobber

To trigger: go to Actions → Build & Attach Binaries → Run workflow, enter your tag (e.g. v1.0.0), and click Run. All three binaries will be built in parallel and uploaded to the release.

Important: The permissions: contents: write block is required. Without it, the default GitHub token cannot upload release assets and the workflow will fail with HTTP 403.

---

Releasing Binaries

Steps for a new release

1. Create and push a tag:

   git tag v1.0.0
   git push origin v1.0.0
   

2. Create a GitHub Release for the tag (via GitHub UI or gh release create v1.0.0).

3. Trigger the Build & Attach Binaries workflow from the Actions tab with the matching tag.

4. Once complete, the release will have three assets: kim-linux, kim-macos, kim-windows.exe.

---

Troubleshooting

Daemon won't start

Check the log file for errors:

kim logs

Make sure there isn't already a stale PID file:

rm ~/.kim/kim.pid
kim start

Notifications not appearing on macOS

Grant notification permissions to Terminal (or whichever app you run KIM from) in System Settings → Notifications.

Notifications not appearing on Linux

Ensure notify-send is installed:

sudo apt install libnotify-bin   # Debian/Ubuntu
sudo dnf install libnotify       # Fedora

Config changes not taking effect

KIM reads config only on startup. Always restart after editing:

kim stop && kim start

Validate your config

kim validate

---

Roadmap

• One-shot reminders (kim remind "standup" in 10m)
• Per-reminder cron-style scheduling (not just fixed intervals)
• Plugin system for custom notification channels
• Additional webhook integrations (Teams, Discord, etc.)

---

Start small. Keep it in mind.

# KIM — Keep In Mind 🧠

Lightweight cross-platform reminder daemon for developers. No UI. Config-driven. Runs in the background.

---

Table of Contents

• [Overview](#overview)
• [How It Works](#how-it-works)
• [Installation](#installation)
• [Uninstallation](#uninstallation)
• [CLI Reference](#cli-reference)
• [Configuration](#configuration)
• [Slack Integration](#slack-integration)
• [Building from Source](#building-from-source)
• [Releasing Binaries](#releasing-binaries)
• [Troubleshooting](#troubleshooting)
• [Roadmap](#roadmap)

---

Overview

KIM is a developer-focused reminder daemon that runs quietly in the background and fires desktop notifications at configured intervals. It is built entirely on the Python standard library — no pip dependencies required — and supports Linux, macOS, and Windows out of the box.

Key design principles:

• No GUI, no Electron, no bloat
• Single config file (~/.kim/config.json)
• Autostart on login via native OS mechanisms
• Each reminder runs in its own thread

---

How It Works

Platform	Autostart Mechanism	Notification Method
Linux	systemd user service	notify-send
macOS	launchd agent	osascript
Windows	Task Scheduler	PowerShell toast

• The daemon tracks its process ID at ~/.kim/kim.pid
• Logs are written to ~/.kim/kim.log
• Each reminder runs independently in its own thread, so one slow/failed reminder never blocks others

---

Installation

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/pratikwayal01/kim/main/install.sh | bash

Windows (PowerShell as Administrator)

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/pratikwayal01/kim/main/install.ps1 | iex"

The installer will:

1. Copy kim to ~/.local/bin/ (Linux/macOS) or a PATH-accessible location (Windows)
2. Register an autostart entry so KIM launches on login
3. Start the daemon immediately

Note: On macOS, you may be prompted to allow notifications for Terminal or osascript the first time a reminder fires.

---

Uninstallation

Using the built-in command (recommended)

kim uninstall

Manual uninstall — Linux

systemctl --user disable --now kim.service
rm ~/.config/systemd/user/kim.service
rm -rf ~/.kim ~/.local/bin/kim

Manual uninstall — macOS

launchctl unload ~/Library/LaunchAgents/io.kim.reminder.plist
rm ~/Library/LaunchAgents/io.kim.reminder.plist
rm -rf ~/.kim ~/.local/bin/kim

Manual uninstall — Windows

Unregister-ScheduledTask -TaskName KimReminder -Confirm:$false
Remove-Item -Recurse "$env:USERPROFILE\.kim"

---

CLI Reference

Command	Description
kim start	Start the daemon
kim stop	Stop the daemon
kim status	Show running reminders and daemon status
kim list	List all reminders from config
kim logs	Tail the log file
kim edit	Open config in $EDITOR
kim add	Add a new reminder
kim remove	Remove a reminder
kim enable	Enable a reminder
kim disable	Disable a reminder
kim update	Update a reminder
kim interactive	Enter interactive mode
kim self-update	Check for and install the latest version
kim uninstall	Remove KIM completely from the system
kim export	Export reminders to a file
kim import	Import reminders from a file
kim validate	Validate the config file
kim slack	Manage Slack notification settings
kim completion	Generate shell completions

After editing the config, always restart the daemon to apply changes:

kim stop && kim start

---

Configuration

KIM is controlled entirely by ~/.kim/config.json. You can edit it directly (kim edit) or manage it through CLI commands.

Example config

{
  "reminders": [
    {
      "name": "eye-break",
      "interval_minutes": 30,
      "title": "👁️ Eye Break",
      "message": "Look 20 feet away for 20 seconds. Blink slowly.",
      "urgency": "critical",
      "enabled": true
    },
    {
      "name": "water",
      "interval_minutes": 60,
      "title": "💧 Drink Water",
      "message": "Stay hydrated.",
      "urgency": "normal",
      "enabled": true
    }
  ],
  "sound": true
}

Field reference

Field	Type	Values	Description
name	string	any	Unique identifier for the reminder
interval_minutes	number or string	e.g. 30, "30m", "1h", "1d"	How often the reminder fires
title	string	any	Notification heading
message	string	any	Notification body text
urgency	string	low / normal / critical	Controls notification priority level
enabled	boolean	true / false	Toggle a reminder without deleting it
sound	boolean	true / false	(top-level) Play sound with notifications globally

---

Slack Integration

KIM can send reminders to a Slack channel in addition to desktop notifications.

Add Slack config

{
  "reminders": [...],
  "sound": true,
  "slack": {
    "enabled": true,
    "webhook_url": "https://hooks.slack.com/services/...",
    "bot_token": "xoxb-...",
    "channel": "#general"
  }
}

Authentication methods

Webhook (simpler): Create an incoming webhook at https://api.slack.com/messaging/webhooks and paste the URL into webhook_url.

Bot Token (more control): Create a Slack app, add the chat:write scope, install it to your workspace, and paste the bot token into bot_token.

You only need one method — use whichever fits your setup.

Test your Slack setup

kim slack --test

Apply changes

kim stop && kim start

---

Building from Source

KIM uses [PyInstaller](https://pyinstaller.org) to produce self-contained binaries. Since PyInstaller cannot cross-compile, each platform's binary must be built on the matching OS.

Build locally

pip install pyinstaller
pyinstaller --onefile --name kim kim.py
# Output: ./dist/kim  (or ./dist/kim.exe on Windows)

Build all platforms via GitHub Actions

Add .github/workflows/build.yml to your repo:

name: Build & Attach Binaries

on:
  workflow_dispatch:
    inputs:
      tag:
        description: "Release tag to attach binaries to (e.g. v1.0.0)"
        required: true
        default: "v1.0.0"

permissions:
  contents: write

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            artifact: kim-linux
          - os: macos-latest
            artifact: kim-macos
          - os: windows-latest
            artifact: kim-windows.exe

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install PyInstaller
        run: pip install pyinstaller

      - name: Build binary
        run: pyinstaller --onefile --name ${{ matrix.artifact }} kim.py

      - name: Upload to release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release upload ${{ inputs.tag }} dist/${{ matrix.artifact }} --clobber

To trigger: go to Actions → Build & Attach Binaries → Run workflow, enter your tag (e.g. v1.0.0), and click Run. All three binaries will be built in parallel and uploaded to the release.

Important: The permissions: contents: write block is required. Without it, the default GitHub token cannot upload release assets and the workflow will fail with HTTP 403.

---

Releasing Binaries

Steps for a new release

1. Create and push a tag:

   git tag v1.0.0
   git push origin v1.0.0

2. Create a GitHub Release for the tag (via GitHub UI or gh release create v1.0.0).

3. Trigger the Build & Attach Binaries workflow from the Actions tab with the matching tag.

4. Once complete, the release will have three assets: kim-linux, kim-macos, kim-windows.exe.

---

Troubleshooting

Daemon won't start

Check the log file for errors:

kim logs

Make sure there isn't already a stale PID file:

rm ~/.kim/kim.pid
kim start

Notifications not appearing on macOS

Grant notification permissions to Terminal (or whichever app you run KIM from) in System Settings → Notifications.

Notifications not appearing on Linux

Ensure notify-send is installed:

sudo apt install libnotify-bin   # Debian/Ubuntu
sudo dnf install libnotify       # Fedora

Config changes not taking effect

KIM reads config only on startup. Always restart after editing:

kim stop && kim start

Validate your config

kim validate

---

Roadmap

• One-shot reminders (kim remind "standup" in 10m)
• Per-reminder cron-style scheduling (not just fixed intervals)
• Plugin system for custom notification channels
• Additional webhook integrations (Teams, Discord, etc.)

---