kaihuman docs

Every app, file format and command, on one page each. The same text ships as the @lifosy/docspack package, so a coding agent can query it offline with docspack ask.

• Lifosy Lifosy is a personal life OS: notes, todos, habits, dashboards, bookmarks and a knowledge base, all stored as plain files in a GitHub repository you own. The product faces users under the name kaihuman (web app at https://app.kaihuman.com), while the code, packages and binaries use the name Lifosy (@lifosy/*, lifosy-palette). The monorepo lifosy/monorepo holds a web console, a terminal CLI, a browser extension, a desktop command palette, an MCP server and the landing pages.
• Developing in the monorepo The Lifosy code lives in one Turborepo monorepo with pnpm workspaces (apps/* and packages/*, from pnpm-workspace.yaml). TypeScript apps use Vite, Biome for lint and format, and Vitest for tests; the CLI and the desktop palette backend are Rust. This page covers the prerequisites, the root commands, per-app commands, CI deployment to Cloudflare Pages, versioning, documentation conventions and how the @lifosy/docspack documentation package is built.
• Terminal CLI The terminal CLI is a Rust program in apps/cli whose binary is called cli (crate cli, version 0.1.0, npm workspace name @lifosy/cli). Run with no arguments, it opens an interactive terminal UI built with ratatui and crossterm for notes, knowledge captures, repo selection, a file browser and editor, a dashboard view and an AI prompt. It also has two subcommands: cli server starts a local AI proxy over HTTP, and cli capture writes a knowledge note to .kh/raw/ with an offline spool. It signs in with GitHub through the web console and works on one active GitHub repository at a time.
• Desktop quick capture Desktop quick capture puts a thought into the knowledge base inbox .kh/raw/ from a global hotkey, without opening a terminal. There are two implementations. The shipped one is a Bash overlay script, apps/cli/scripts/kh-capture, bound to Super+K in Hyprland, which pipes the text into cli capture. The experimental one is apps/kh-capture-native, a small native-sdk (Zig core) window that pushes to GitHub directly and is meant for Super+Shift+K. Both reuse the terminal CLI's login and active repo.
• Web console The web console is the main Lifosy (kaihuman) web app, in apps/console (package @lifosy/app-console). It is a Preact + Vite + Tailwind CSS single-page app, installable as a PWA, that reads and writes plain files in your own GitHub repository through the GitHub API. Most UI lives in packages/ui (@lifosy/ui) and the stores and GitHub service live in packages/core (@lifosy/core); the console wires them to routes. It is deployed to Cloudflare Pages and served at app.kaihuman.com.
• Console widgets Widgets are the interactive views the web console (apps/console) shows for repo files with a known file suffix, such as .todos.md or .bookmarks.json. Each widget is a Preact component in packages/ui/src/LifeOS/Organisms/Widgets/, and each change it makes is committed to your GitHub repo at once. Files are placed as tiles on a dashboard through .kh/.dashboard.config.json; the shared parsers for most formats live in packages/formats.
• Console views The web console's main layout, MainApp in packages/ui/src/LifeOS/Layouts/MainApp.tsx, has views beyond the dashboard and files: a knowledge graph, commit history, a local AI chat panel, a scratch "quick dump" editor and overdue-todo push notifications. Most are opened from the centre **kaihuman** menu button in the bottom status bar, which is a drawer on desktop and the **More** sheet on mobile.
• Browser extension The Lifosy browser extension lives in apps/browser-extension (package name browser-extension). It is a Chrome Manifest V3 extension built with TypeScript, Preact, Vite, Tailwind CSS and the CRXJS Vite plugin (@crxjs/vite-plugin). It reads and writes files in your active GitHub repository through the GitHub API, using the token the Lifosy console hands it. It has a toolbar popup, a replacement New Tab start page, a context menu clip, the shared command palette on every page, and a background service worker that caches and syncs everything.
• Command palette The command palette is a keyboard launcher shared by the browser extension and the desktop app. It searches bookmarks, runs actions, searches the repository and the web, and switches into prefix modes such as >p prompts or >k conversions. The code lives in packages/palette (@lifosy/palette), plain TypeScript with no UI framework, rendered in a shadow root. Each surface answers its requests through an ActionPort: the extension's service worker, or the Rust backend of apps/desktop-palette.
• Desktop palette The desktop palette is the shared command palette as a Linux desktop overlay. A global hotkey opens it centred on the focused monitor, above tiled windows, with the keyboard in its input. It lives in apps/desktop-palette: a Tauri v2 app whose webview runs @lifosy/palette and whose Rust backend (src-tauri/) answers its requests. It targets Wayland compositors with wlr-layer-shell (Hyprland, Sway, river, niri, KDE) and also hosts the braindump window.
• Knowledge base The Lifosy knowledge base is a personal wiki kept in the .kh/ folder of the user's GitHub repository. It follows the LLM-wiki pattern: capture tools drop raw sources into .kh/raw/, and Claude Code slash commands such as /kb-ingest, /kb-ask, /kb-digest and /kb-lint compile them into cross-linked wiki pages. The console scaffolds the folder and the commands from apps/console/src/lib/kb-skills.ts, and apps/kb-mcp exposes the same folder to MCP clients.
• Knowledge base MCP server @lifosy/kb-mcp in apps/kb-mcp is a stdio MCP server that gives an LLM agent such as Claude Code access to the Lifosy knowledge base in a local repository clone. It reads the .kh/ folder (or the legacy .lifeos/ folder) and exposes six tools for searching, reading, listing and adding raw notes. It is written in TypeScript on Node.js 22+ with @modelcontextprotocol/sdk and zod, and builds to the lifosy-kb-mcp bin.
• Repo file formats Lifosy keeps all user data as plain text files in the user's own GitHub repository: Markdown for todos, logs, prompts and commands, ;-separated CSV for events, habits and time tracking, and JSON for bookmarks, read-later lists and settings. A file's suffix, such as .todos.md or .habit.csv, decides which widget opens it. Parsing and serialising live in packages/formats/src/ (@lifosy/formats), shared by the console, the browser extension and both command palettes, with a few widget formats in packages/ui/src/LifeOS/Organisms/Widgets/*Logic.ts.
• Shared packages The packages/ folder of the Lifosy monorepo holds the code shared between the apps. @lifosy/core has the GitHub service, the Preact-signal stores and crypto. @lifosy/formats parses and writes the repo file formats. @lifosy/ui has the console's Preact components and widgets, and @lifosy/config has the shared TypeScript, Biome and Tailwind configuration. All four are private pnpm workspace packages, referenced as workspace:*.
• Landing pages The kaihuman marketing site is a static Astro site styled with Tailwind CSS v4 (@tailwindcss/vite). Two versions live in the monorepo: apps/landing-page-nextgen (@lifosy/landing-page-nextgen) is the production site, and apps/landing-page (@lifosy/landing-page) is the older design, kept in the repo but no longer deployed. Both pages link to the app at https://app.kaihuman.com, the live demo at /demo, and the source at github.com/lifosy/monorepo.