@holt-os/holt 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Debashis Nayak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Holt
+
+**Everything you know, kept and connected.**
+
+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.
+
+> 🚧 **Status: early development (Phase 0).** The architecture and roadmap are locked and the CLI skeleton is here, but Holt is not yet functional end-to-end. Star/watch to follow along — contributions welcome.
+
+---
+
+## Why Holt
+
+- 🧠 **Memory you can see.** Persistent RAG memory plus a *navigable knowledge graph* of everything you feed it — not a black-box profile you have to trust.
+- 🔌 **Any LLM.** Claude, OpenAI, Gemini, or a local model — swap your brain with one line of config. No vendor lock-in.
+- 💸 **Local executes, cloud reviews.** Run a local model for the work and let a premium cloud model review only the risky, irreversible steps. Cheap and private by design.
+- 🧩 **MCP plugin pantry.** Skills, channels, providers, embeddings — everything is a plugin speaking the [Model Context Protocol](https://modelcontextprotocol.io). Extend it in any language.
+- 📚 **Standard skills.** Compatible with the [agentskills.io](https://agentskills.io) skill format — pull from the community catalog or publish your own.
+- 🖥️ **CLI-first.** Works in your terminal the moment you clone. Telegram and other channels are opt-in.
+
+## Quickstart
+
+> Not functional yet — this is the intended interface (Phase 0).
+
+```bash
+npm install -g @holt-os/holt   # or: pnpm add -g @holt-os/holt
+holt init                      # pick your brain + memory (local or cloud)
+holt chat                      # start talking
+```
+
+Add skills:
+
+```bash
+holt skill search finance
+holt skill add deep-research
+```
+
+## Configuration
+
+Copy `config.example.yml` to `config.yml` and edit. See the file for the full schema — brain/provider, memory + embeddings, output format (HTML or Markdown), orchestration, and channels.
+
+## Architecture
+
+Small strongly-typed **TypeScript core** (agent loop, brain router, memory orchestration, risky-action review gate, plugin dispatcher). *Everything else* is an MCP plugin — providers, embeddings, skills, channels. See [`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+## Roadmap
+
+Built in always-shippable phases toward a full-vision v1:
+
+0. **Skeleton** — core loop + CLI *(in progress)*
+1. **Memory** — sqlite-vec RAG + embeddings
+2. **Any-LLM** — provider plugins + output toggle
+3. **Skills** — agentskills.io catalog + installer
+4. **Knowledge graph** — navigable memory view
+5. **Orchestration** — local-executes / cloud-reviews
+6. **Channels + polish** — Telegram, docs, one-command install
+
+## Contributing
+
+Holt is built to be extended without touching the core. See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE) © Debashis Nayak

package/config.example.yml

@@ -0,0 +1,38 @@
+# Holt configuration — copy to config.yml and edit.
+# config.yml is git-ignored; never commit secrets or personal memory.
+
+# ── Brain ────────────────────────────────────────────────────────────────
+# The LLM that runs the agent. Provider-agnostic: swap freely.
+brain:
+  provider: anthropic          # anthropic | openai | gemini | local
+  model: claude-opus-4-8       # e.g. gpt-5.x | gemini-3.x | a local model tag
+  api_key_env: ANTHROPIC_API_KEY   # name of the env var holding the key
+
+# ── Orchestration ────────────────────────────────────────────────────────
+# Optional: let a local model do the work while a cloud model reviews only
+# risky/irreversible actions (file writes, deletes, shell, sending, spending).
+orchestration:
+  enabled: false
+  executor:                    # the worker (usually a local model)
+    provider: local
+    model: ""                  # e.g. a local coding model via Ollama
+  reviewer:                    # gates risky actions: approve | edit | block
+    provider: anthropic
+    model: claude-opus-4-8
+
+# ── Memory ───────────────────────────────────────────────────────────────
+memory:
+  store: sqlite-vec            # sqlite-vec (zero infra) | pgvector
+  embeddings: local            # local | openai | gemini
+  # For local embeddings, Holt uses a local model (auto-set up on first run).
+
+# ── Output ───────────────────────────────────────────────────────────────
+output:
+  format: markdown             # markdown | html
+
+# ── Channels ─────────────────────────────────────────────────────────────
+# CLI always works. Everything below is opt-in.
+channels:
+  telegram:
+    enabled: false
+    token_env: TELEGRAM_BOT_TOKEN

package/dist/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var VERSION = "0.0.1";
+var BANNER = `
+  \u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
+  \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551  \u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D
+  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2551
+  \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2551
+  \u2588\u2588\u2551  \u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551
+  \u255A\u2550\u255D  \u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D
+  Everything you know, kept and connected.
+`;
+var HELP = `${BANNER}
+Usage: holt <command> [options]
+
+Commands:
+  init            Set up your brain (LLM) and memory (local or cloud)
+  chat            Start an interactive session
+  skill <cmd>     Manage skills: search | add | remove | list | publish
+  version         Print the Holt version
+  help            Show this help
+
+Docs: https://productsdecoded.com/holt
+Repo: https://github.com/holt-os/holt
+
+Holt is in early development (Phase 0). Most commands are not wired up yet.
+`;
+function notReady(cmd) {
+  console.log(`
+  "${cmd}" is not implemented yet \u2014 Holt is in Phase 0 (skeleton).`);
+  console.log("  Follow progress: https://github.com/holt-os/holt\n");
+}
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case void 0:
+    case "help":
+    case "-h":
+    case "--help":
+      console.log(HELP);
+      break;
+    case "version":
+    case "-v":
+    case "--version":
+      console.log(`holt ${VERSION}`);
+      break;
+    case "init":
+    case "chat":
+    case "skill":
+      notReady([cmd, ...rest].join(" "));
+      break;
+    default:
+      console.log(`
+  Unknown command: "${cmd}"`);
+      console.log(`  Run "holt help" for usage.
+`);
+      process.exitCode = 1;
+  }
+}
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@holt-os/holt",
+  "version": "0.0.1",
+  "description": "An open-source personal agent OS — any LLM, private memory you can see and walk.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Debashis Nayak",
+  "homepage": "https://productsdecoded.com/holt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holt-os/holt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/holt-os/holt/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "agent-os",
+    "personal-assistant",
+    "llm",
+    "mcp",
+    "memory",
+    "rag",
+    "knowledge-graph",
+    "self-hosted",
+    "local-first",
+    "agentskills"
+  ],
+  "bin": {
+    "holt": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "config.example.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup src/cli.ts --format esm --clean",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.1.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  }
+}