Installation¶

Kaisho runs as a Python package. You need Python 3.12 or newer.

From Source (Recommended for Development)¶

Clone the repository and install in editable mode:

git clone https://github.com/ridingbytes/kaisho.git
cd kaisho
pip install -e .

Verify the installation:

kai --help

You should see the list of available commands.

If you prefer containers, run the full stack with one command:

docker compose up --build

This starts the backend on port 8765 with the frontend bundled in. Your data persists in a Docker volume.

To use a local directory for data instead:

# docker-compose.override.yml
services:
  kaisho:
    volumes:
      - ./my-data:/app/data

Download the latest release from GitHub Releases. The desktop app bundles the Python backend as a sidecar process -- no separate installation needed.

The frontend is a separate Vite project. To work on it:

cd frontend
pnpm install
pnpm dev

This starts the Vite dev server on localhost:5173, proxying API calls to the backend on localhost:8765.

Kaisho's Python dependencies install automatically:

Package	Purpose
FastAPI + Uvicorn	HTTP server
Click	CLI framework
Pydantic	Data validation and settings
APScheduler	Cron job scheduling
SQLAlchemy	SQL storage backend
PyYAML	Configuration files
pypdf	PDF text extraction

Optional system dependency for better PDF extraction:

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt install poppler-utils

Once installed, head to Quick Start to create your first profile and start tracking time.