@holt-os/holt 0.14.2 → 0.15.0

package/README.md

@@ -1,21 +1,33 @@
-# Holt
+<p align="center">
+  <img src="https://raw.githubusercontent.com/holt-os/holt/main/docs/header.png" alt="Holt" width="100%">
+</p>
 
-**Everything you know, kept and connected.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/@holt-os/holt"><img src="https://img.shields.io/npm/v/@holt-os/holt?logo=npm&color=cb3837&label=npm" alt="npm version"></a>
+  <a href="https://github.com/holt-os/homebrew-tap"><img src="https://img.shields.io/badge/brew-holt--os%2Ftap%2Fholt-f5a623?logo=homebrew&logoColor=white" alt="Homebrew tap"></a>
+  <img src="https://img.shields.io/node/v/@holt-os/holt?logo=node.js&logoColor=white&color=3c873a" alt="Node version">
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-ready-4dd0e1?logo=modelcontextprotocol&logoColor=white" alt="MCP ready"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
 
-Holt is an open-source, self-hosted personal agent OS. Clone it, pick your skills, choose your brain, and it runs on *your* machine with persistent memory you can actually see and walk.
+***
 
-> A *holt* is a small wood: a sheltered place where things are kept and grow. That's the idea. A private home for your knowledge that compounds over time.
+**Holt is an open-source personal agent OS: any LLM as its brain, private memory it can see and walk, running entirely on your own machine.** Clone it, pick your skills, choose your brain. Your knowledge stays local and compounds over time.
 
-> **Status: shipping and usable today.** Working now:
->
-> - Bare `holt` launches the real interactive brain (Claude Code, Codex, or Gemini) branded as Holt, setting the folder up the first time. `holt chat` stays as a lightweight REPL for direct API brains, with mid-conversation brain switching that keeps context.
-> - Per-folder memory with semantic recall and distilled facts, ambient memory for Claude Code (`holt hook`), and opt-in memory shared across folders (`holt memory global`).
-> - A self-maintaining knowledge wiki (`holt wiki`) and an interactive knowledge graph (`holt graph`) that can also ingest your code and docs into communities.
-> - Run a task once, on a schedule, or as a named routine (`holt run` / `schedule` / `routine`), and reach it from your phone over Telegram.
-> - Draft in your own voice with anti-AI checks (`holt write`), and size your setup with `holt doctor`.
-> - Ten built-in skills plus a community registry (`holt skill search`), and an MCP server so Claude Code, Cursor, or Codex can read this folder's memory.
+> A *holt* is a small wood: a sheltered place where things are kept and grow. That is the idea. A private home for your knowledge that compounds over time.
 
----
+### Highlights
+
+- **Any brain, one assistant.** Bare `holt` launches a real interactive brain (Claude Code, Codex, or Gemini) branded as Holt, or you connect a direct API brain with your own key. Switch mid-conversation and keep the full context.
+- **Private memory you can see.** Per-folder semantic recall and distilled facts, an interactive knowledge graph (`holt graph`), and a self-maintaining wiki (`holt wiki`) over everything you tell it. Nothing leaves your machine.
+- **Ambient by default.** `holt hook` wires memory into Claude Code so it recalls and remembers with no manual step, and an MCP server exposes the same memory to Cursor and Codex.
+- **Runs your work.** Run a task once, on a schedule, or as a named routine, and reach it from your phone over Telegram.
+- **Extensible, zero-infra.** Ten built-in skills plus a git-based community registry (`holt skill search`) in the portable `SKILL.md` format.
+- **Writes in your voice.** `holt write` drafts in a style Holt learns from you, with built-in anti-AI checks.
+
+> **Status:** shipping and usable today. Every capability above works now.
+
+***
 
 ## Install
 
@@ -117,6 +129,8 @@ Holt runs the brain in the folder you launched it from, so by default the brain
 
 Grants are **in-memory and session-scoped**: nothing is written to disk, and they reset the next time you run `holt chat`. Access is **read-oriented** and only works with a **Claude Code** brain: Holt passes `--add-dir=<dir>` for each granted folder plus `--allowedTools=Read,Glob,Grep` so Claude Code can read (but not write) those files without an interactive permission prompt. With a Codex/Gemini or API brain, external file access is unavailable and Holt says so instead of adding flags. (If you need to tune the flags, they live in one place: `claudeAccessArgs` in `src/access.ts`.)
 
+***
+
 ## Memory
 
 Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and local. On each message, Holt recalls the most relevant moments from your *past* sessions in that folder and hands them to the brain, so it remembers what you told it last week.
@@ -181,7 +195,7 @@ A brain is an agent CLI installed and logged in on your machine. No API keys to
 
 ### Direct API brains
 
-A brain can also be a direct provider connection: no CLI install, your own key. Run `holt setting` and pick `[c] connect API brain`, or say yes to the API-brain question in `holt init`. Choose a provider (anthropic, openai, gemini), a model (suggestions offered, type anything), and a short name. For the key, paste a raw key (stored in `~/.holt/credentials.json`, mode 600) or give the name of an env var that holds it. Resolution order: the brain's `keyEnv`, the credentials file, then the standard env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`). API brains stream and share memory exactly like CLI brains; switch with `/brain <name>`.
+A brain can also be a direct provider connection: no CLI install, your own key. Run `holt setting` and pick `[c] connect API brain`, or say yes to the API-brain question in `holt init`. Choose a provider (anthropic, openai, gemini, kimi, grok), a model (suggestions offered, type anything), and a short name. Kimi (Moonshot) and Grok (xAI) speak the OpenAI wire format at their own endpoints; any other OpenAI-compatible endpoint (a gateway, a self-hosted server) works too via an optional `baseUrl` on the brain in `.holt/config.json`. For the key, paste a raw key (stored in `~/.holt/credentials.json`, mode 600) or give the name of an env var that holds it. Resolution order: the brain's `keyEnv`, the credentials file, then the standard env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `MOONSHOT_API_KEY`, `XAI_API_KEY`). API brains stream and share memory exactly like CLI brains; switch with `/brain <name>`.
 
 ## See your memory: `holt graph`
 
@@ -247,6 +261,8 @@ holt wiki setup               # recommend a local model for this machine's RAM
 
 Wiki pages also participate in recall: each page is embedded and indexed like a high-value fact, so `holt memory search` and chat recall can surface synthesized knowledge, not just raw turns.
 
+***
+
 ## Skills
 
 A skill is a folder with a `SKILL.md`: YAML frontmatter (`name`, `description`) plus Markdown instructions. Same convention as agentskills.io and Claude Code, so skills are portable both ways. Skills are prompt text only; Holt never executes their contents.
@@ -267,6 +283,22 @@ A source may carry a `#<subdir>` suffix (split on the first `#`) that points at
 
 In chat, run one with `/skill <name> [your input]`. Available skills are also listed to the brain each turn, so it knows what it can be asked to follow.
 
+### Skills as native commands
+
+When you `holt launch` an interactive brain, every enabled skill is also compiled into that brain's own custom-command format, so it shows up as a real slash command inside the session (in addition to Holt's own `/skill <name>`). This happens automatically for the built-ins too, and re-syncs on `holt skill add` and `holt skill remove`. It is idempotent and stays quiet on repeat launches when nothing changed.
+
+Fidelity depends on the brain:
+
+- **Claude Code (full power):** each skill folder is copied verbatim into the project's `.claude/skills/<name>/`, so multi-file skills, tool restrictions, and frontmatter are preserved one to one.
+- **Gemini CLI (best effort):** a `.gemini/commands/<name>.toml` custom command is generated from the skill's description and instructions, with your input passed through Gemini's `{{args}}`. Prompt only.
+- **Codex (best effort):** a markdown custom prompt is written to Codex's global prompts dir (`~/.codex/prompts/holt-<name>.md`, prefixed because Codex prompts are global rather than per project), with your input passed through Codex's `$ARGUMENTS`. Prompt only.
+
+It never clobbers a command or skill you authored: if a target already exists and Holt did not write it, that one is skipped with a one-line note. Holt tracks everything it generates in `./.holt/skill-commands.json`, so `holt skill remove` cleans up only Holt's own compiled commands and never touches yours. A skill that has no instructions to express (for the prompt-only brains) is skipped rather than emitted as a broken command.
+
+### holt-jobsearch
+
+A full skill suite built on Holt that runs an entire job search: build your profile, score a role on fit, tailor your resume, write the cover letter, prep for interviews, read your inbox for replies, draft follow-ups, and track the pipeline. The core runs with zero API keys; search, inbox, and follow-up are opt-in connectors. It drafts everything and leaves you the submit button. Find it at [holt-os/holt-jobsearch](https://github.com/holt-os/holt-jobsearch), or `holt skill search job` to install the pieces from the registry.
+
 ### Built-in skills
 
 Holt ships with a small, curated set of general-purpose skills, available in every folder with no setup. They are read-only (`holt skill remove` will not delete them); to change one, create a workspace or global skill with the same name and it takes over.
@@ -372,6 +404,8 @@ To uninstall, run `holt hook remove` (add `--project` if you installed with `--p
 
 Replies print as markdown. `/output html` (or `markdown`) switches the save format and persists it. `/save [name]` writes the last reply to the current folder: `.md`, or a small self-contained dark-theme `.html` page.
 
+***
+
 ## Run tasks, schedule them, reach them from your phone
 
 Beyond interactive chat, Holt can run a task once, on a timer, or from Telegram. The selected brain does the task; your memory is recalled into it automatically.
@@ -506,6 +540,8 @@ By default a second pass checks the draft against the rubric and fixes any tells
 
 With no profile yet, `holt write` still works using a plain, natural voice.
 
+***
+
 ## Commands
 
 ```
@@ -520,6 +556,11 @@ holt routine         named, reusable, scheduled jobs: add | run | list | show |
 holt telegram        chat with Holt from your phone: telegram [setup]
 holt notify [msg]    push a message to your phone over Telegram (stdin-friendly)
 holt doctor          check this machine and recommend how best to run Holt here
+                     ("holt doctor --fix" also repairs the common problems it finds:
+                      starts Ollama, pulls the embed model, mends a damaged config)
+holt tour            a 2-minute guided first run: ask, teach one fact, watch it remember
+holt update          get the latest Holt in one word (npm or Homebrew, auto-detected)
+holt reset           start this folder over (typed confirmation; your files untouched)
 holt voice           teach Holt your writing voice: add <file> | show | edit | clear
 holt write <what>    draft content in your voice with anti-AI checks (--type, --out, --fast)
 holt graph           see your memory as an interactive knowledge graph
@@ -561,6 +602,8 @@ Built in always-shippable phases toward a full-vision v1:
 
 Holt is built to be extended without touching the core. See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
+***
+
 ## License
 
 [MIT](./LICENSE) © Debashis Nayak