0xkobold 0.0.1

package/HEARTBEAT.md

@@ -0,0 +1,45 @@
+# Heartbeat Checklist
+
+<!--
+This file controls what the agent checks during periodic heartbeats.
+Keep it short and actionable. If this file is empty or only contains headers,
+heartbeats will be skipped to save tokens.
+
+The agent can read this file using the /heartbeat now command or via
+scheduled checks (if HEARTBEAT_ENABLED is set in environment).
+
+If nothing needs attention, the agent should reply with HEARTBEAT_OK.
+If something needs attention, the agent describes the issue.
+-->
+
+## Regular Checks
+
+- [ ] Review any pending tasks flagged in the workspace
+- [ ] Check for blocked items needing human input
+- [ ] Verify no critical system alerts
+
+## Context-Aware (only check when relevant)
+
+- [ ] Sessions that haven't been updated recently  
+- [ ] Scheduled tasks or reminders
+- [ ] Follow-ups from previous conversations
+
+## Response Protocol
+
+| Situation | Response |
+|-----------|----------|
+| Nothing needs attention | Reply: `HEARTBEAT_OK` |
+| Minor item noted | Brief description (no HEARTBEAT_OK) |
+| Urgent issue | Alert message (no HEARTBEAT_OK) |
+
+## Environment Variables
+
+- `HEARTBEAT_ENABLED` - Set to "false" to disable (default: true)
+- `HEARTBEAT_EVERY` - Interval like "30m", "1h", "2h" (default: 30m)
+- `HEARTBEAT_ACK_MAX_CHARS` - Max length of ack message (default: 300)
+
+## Commands
+
+- `/heartbeat` - Show status
+- `/heartbeat now` - Trigger immediate check
+- `/heartbeat-init` - Create this template file

package/README.md

@@ -0,0 +1,197 @@
+# 0xKobold
+
+```
+                         ..
+            .                                        ..
+                 . ,^   .                   .   .....          ......
+            ,^ ... :: .  .                   ...     ,;.    ...
+           .lI^ I.`I,.. ;;..             . `l}^ ^:;+td]^..      ^:!!i .
+           . ,:^I^I< . :+,..             ..l+tI`!?o@f,     .,~fWQft?<..
+        `:. ^<l>,!I>^`<!^              .. `?_-11COQYI:;l!l+1o@#[l
+         !<`l.ii,~l^iI-,`!I..   .. ...   ^l>??}JOoUUZ1]-fYXB@fl    ,+i..
+     . `.:<+:<ll>~l>+-<:~!^    .      I_>_?<+?}Bb+M8%oOf}-_+_!~~+[CQJ:..
+     `:,lI,:Ii!<:`!iii>_+^ :!^  ^``^,l+?<_}+fJ?1ItJ1<>?[?JX1YdOOodtl  ..
+    . li:^~Il, :Il`::,:i!,I>I`^l_~--<i_<>?+~?_-CY}~i+-?~]fO@@@@@Ml
+     ..,!``I,!]JZXJ{]I,,~~;,  I[_<-t}1doCdfdQCOB%oJ{+?{ddMO@@@#@o>` .:-< .
+      .``l;;{QW%###WQZ+;>>I ...<YfZ{]}Xb!IQ@@8%W@@QJ{[-JJZ@@@@@@%dZbMX[,..
+     . II ,I]bo%8%%MQd?>;  .    ;li   . ,Z@@@@#@MI]~ZUOX}YB@@@@@8oQY};
+      . ^>^.^~fbXXdZf_,, Il .         I~d@@#MOIY>l[ZoW@@@@@@@@@UIMO{.   .
+        `I!<` ,lllll :,i;,^`    ...~+<d#oJQQbIIJdUB@@@@@@@#%OU8WW@@81+,`
+       .,i[l:i!, `:I<-l<-, ^^`  ..:]ZodXIdbC1i1Z#@@@@@@%%BWWoO%@@@@%bQf[^.
+       .J-I ~I!.iCU->-1_<`ii>~:....:_1}It}!.::+tX%#@%MbMBQ%@@@@@@%%WbY]+-~`.
+        XWOUMO{,Z@B-;1B]:I_->i^      ...   `;;JOB#QB#M8@@@@@@8OOOQdZ{~i!i!:.
+       ..iJB@@M[1@%Y<X@o][]]>:III,^,    ....,Z@@@@@@@@@@@@@@8#WOMoZI~~~~+I..
+           `~M@8X#@8Zf#@BUWb1{1?]1}]<!^ ...:b@@@@@@@@@@@@@8BW#dXZf[?-+l:`..
+         ..  :JB@@@@%%@@@B#@%W%OQ8BMQbU> ..>M%@@@@@@@@@@@#8WBMZII]_I:^
+           ..  ^?1YbMWO#@@@@@@@@@@@@@@OZ-` d@#@@@@@@@@#%W8##OoXZXQCi^ ...
+             ..     .`.:!~-CXd%@@@@@@@8oQ}}%@@@@@@@@@@@BWWBWMMdbf[->>^..
+               .....          :{@@@@@@@OYUCQ8@@@@@@@@8BB8WMQModU?++:!I..
+                    ..........  _@@B8%@#QMdYJO@@@@%BB%obO%obbXZ{?-~l,;..
+                              .. {ooQB%o@%OO-{Z@%oOooWOXZYYII}?_~iiI.`
+                              . ^+IoQWQbOQXdJbfU#BdUZYJI[{[--l>:`
+                                `><+-]1??_~>++~!]J{}~>i>>;!;`     ..
+                                                   `         . ..
+                                 ........ ......... .........
+```
+
+> *"Your digital familiar - a personal AI assistant that learns, evolves, and helps you code 24/7"*
+
+## Hybrid Architecture
+
+Best of both worlds:
+- **Bun + Elysia** for blazing fast gateway
+- **@mariozechner/pi-agent-core** for proven agent loop
+- **Event bus** for decoupled architecture
+- **Hot-reload skills** - just edit .ts files
+- **Approval queue** for safety
+- **Multi-provider LLM** (Ollama default, Anthropic supported)
+- **Subagents** for parallel work
+
+## Installation
+
+### Via NPM (Recommended)
+
+```bash
+# Install globally
+npm install -g 0xkobold
+
+# Or use with npx
+npx 0xkobold init
+npx 0xkobold start
+```
+
+### From Source
+
+```bash
+# Clone and install
+git clone https://github.com/yourusername/0xkobold.git
+cd 0xkobold
+bun install
+
+# Start Ollama (in another terminal)
+ollama run kimi-k2.5:cloud
+
+# Start the server
+bun run start
+```
+
+## Project Structure
+
+```
+0xkobold/
+├── src/
+│   ├── agent/          # Pi Agent Core adapter with subagent support
+│   ├── approval/       # Approval queue for risky operations
+│   ├── channels/       # Discord integration
+│   ├── config/         # Zod config system
+│   ├── discord/        # Discord bot
+│   ├── event-bus/      # Decoupled event system
+│   ├── gateway/        # Elysia WebSocket gateway
+│   ├── llm/            # Ollama + Anthropic providers
+│   ├── memory/         # JSON persistence
+│   ├── skills/         # Hot-reload skill system
+│   └── index.ts        # Main entry
+├── skills/             # Your custom skills (hot-reloaded)
+└── package.json
+```
+
+## Creating Skills
+
+Skills are plain TypeScript files in the `skills/` folder:
+
+```typescript
+// skills/hello.ts
+import type { Skill } from '../src/skills/types';
+
+export const helloSkill: Skill = {
+  name: 'hello',
+  description: 'Say hello to someone',
+  risk: 'safe',
+
+  toolDefinition: {
+    type: 'function',
+    function: {
+      name: 'hello',
+      description: 'Say hello to someone',
+      parameters: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Name to greet' },
+        },
+        required: ['name'],
+      },
+    },
+  },
+
+  async execute(args) {
+    return { message: `Hello, ${args.name}!` };
+  },
+};
+
+export default helloSkill;
+```
+
+The skill is automatically hot-reloaded when you save!
+
+## Safety
+
+Risk levels:
+- `safe` - No approval needed (math, string operations)
+- `medium` - Confirmation for write operations (file write, web requests)
+- `high` - Explicit approval for dangerous operations (shell, delete)
+
+## Subagents
+
+Spawn child agents for parallel work:
+
+```typescript
+const result = await agent.spawn('Research this topic');
+```
+
+The `spawn_subagent` skill is built-in and lets agents create child agents automatically.
+
+## Commands
+
+```bash
+bun run start     # Start server
+bun run tui       # Start TUI
+bun run cli       # CLI commands
+```
+
+## Configuration
+
+Config is stored in `~/.0xkobold/config.json5`:
+
+```json5
+{
+  agents: {
+    default: {
+      model: 'ollama/kimi-k2.5:cloud',
+      capabilities: ['chat', 'code'],
+    },
+  },
+  gateway: {
+    enabled: true,
+    port: 18789,
+  },
+  discord: {
+    enabled: false,
+    token: '${DISCORD_BOT_TOKEN}',
+  },
+}
+```
+
+## Architecture Differences from OpenClaw
+
+| Aspect | OpenClaw | 0xKobold |
+|--------|----------|----------|
+| **Gateway** | Bun.serve | Elysia.js (3x faster) |
+| **Orchestration** | Tight coupling | Event bus (decoupled) |
+| **Agent Loop** | Custom | @mariozechner/pi-agent-core |
+| **Skills** | Compiled | Hot-reload .ts files |
+| **Approval** | Basic | Risk-based queue |
+| **Dependencies** | Many | Minimal (~10) |
+
+## License
+
+MIT

package/USAGE.md

@@ -0,0 +1,191 @@
+# 0xKobold Usage Guide
+
+## Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/yourusername/0xKobolds.git
+cd 0xKobolds
+
+# Install dependencies
+bun install
+
+# Build the project
+bun run build
+
+# Link globally (recommended)
+bun link
+
+# Or install globally
+npm install -g .
+```
+
+## Usage Modes
+
+### Global Mode (Default)
+
+When you run `0xkobold` from anywhere, it uses the global configuration:
+
+```bash
+# Start TUI
+0xkobold
+
+# Or explicitly
+0xkobold tui
+```
+
+**In Global Mode:**
+- Extensions load from the installed 0xKobold package (dist folder)
+- Config: `~/.config/kobold/kobold.json` (or `~/.0xkobold/`)
+- Sessions: `~/.0xkobold/sessions/`
+- Skills: `~/.0xkobold/skills/`
+
+### Local Mode (Per-Project)
+
+Use `--local` flag to develop within a specific project:
+
+```bash
+# Navigate to your project
+cd ~/my-project
+
+# Start in local mode
+0xkobold --local
+
+# Or use the explicit local command
+0xkobold local
+```
+
+**In Local Mode:**
+- Extensions still load from the installed 0xKobold package (so features work)
+- Config: `./kobold.json` (creates if doesn't exist)
+- Sessions: `./.kobold/sessions/`
+- Skills: `./skills/` (falls back to global)
+- Memory: `./.kobold/memory.db`
+
+## Project Setup (Local Mode)
+
+Create a `kobold.json` in your project root:
+
+```json
+{
+  "meta": {
+    "version": "1.0.0",
+    "description": "My Project"
+  },
+  "agents": {
+    "defaults": {
+      "model": "ollama/kimi-k2.5:cloud",
+      "heartbeat": {
+        "enabled": true,
+        "every": "30m"
+      }
+    }
+  }
+}
+```
+
+Create a `HEARTBEAT.md` for periodic check-ins:
+
+```markdown
+# Project Checklist
+
+- [ ] Review pending tasks
+- [ ] Check for blocked items
+- [ ] Update documentation
+```
+
+## Extension System
+
+Extensions are bundled with the package and auto-load:
+
+| Category | Extensions |
+|----------|-----------|
+| Infrastructure | ollama-provider, session-bridge |
+| Core | heartbeat, mode-manager, task-manager, context-pruning |
+| Multi-Channel | discord-channel, multi-channel |
+| Safety | protected-paths, confirm-destructive, git-checkpoint |
+| Integrations | mcp, gateway, websearch |
+
+## Troubleshooting
+
+### Extensions Not Loading
+
+If you see "No models available" or extensions fail to load:
+
+```bash
+# Rebuild the project
+bun run build
+
+# Re-link if using bun link
+bun unlink
+bun link
+```
+
+### Local Mode Not Working
+
+```bash
+# Check if local mode is active
+echo $KOBOLD_LOCAL_MODE  # should print 'true' in local mode
+
+# Verify kobold.json exists in CWD
+ls -la kobold.json
+
+# Check which config is being loaded
+0xkobold config file
+```
+
+### Debug Extension Paths
+
+The TUI will print whether it's running in:
+- `Production (from dist)` - global install, uses .js extensions
+- `Development (from source)` - dev mode, uses .ts extensions
+- `LOCAL mode` - project-specific development
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KOBOLD_CONFIG_PATH` | Override config file location |
+| `KOBOLD_HOME` | Override base directory (default: ~/.config/kobold) |
+| `KOBOLD_LOCAL_MODE` | Set to 'true' for local mode (auto-set by --local) |
+| `PI_CODING_AGENT_DIR` | Base dir for pi-coding-agent (default: ~/.0xkobold) |
+
+## CLI Commands
+
+```bash
+# Global commands
+0xkobold status          # Check service status
+0xkobold stop            # Stop daemon
+0xkobold logs             # View logs
+
+# Discord
+0xkobold discord status  # Check Discord connection
+0xkobold discord test    # Send test message
+
+# Config
+0xkobold config file     # Show config path
+0xkobold config init     # Create default config
+
+# Local development
+0xkobold local            # Start in local mode
+0xkobold --local          # Same as above
+```
+
+## Development
+
+When developing 0xKobold itself:
+
+```bash
+cd ~/Documents/code/0xKobolds
+
+# Run from source (dev mode)
+bun run tui
+
+# Watch and rebuild
+bun run dev
+
+# Build for production
+bun run build
+```
+
+In dev mode, extensions load directly from `src/` as `.ts` files.

package/dist/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "0xkobold",
+    "version": "0.0.1",
+    "description": "Your digital familiar - a personal AI assistant that learns and evolves",
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "type": "module",
+    "bin": {
+        "0xkobold": "./dist/src/cli/index.js"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/src/index.js",
+            "types": "./dist/src/index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "start": "bun run src/index.ts",
+        "cli": "bun run src/cli/index.ts",
+        "tui": "bun run src/index.ts",
+        "init": "bun run src/cli/index.ts init",
+        "test": "bun test",
+        "update": "bun run src/cli/index.ts update",
+        "update:check": "bun run src/cli/index.ts update check",
+        "update:install": "bun run src/cli/index.ts update install",
+        "update:framework": "bun run src/cli/index.ts update framework",
+        "setup-hooks": "bash scripts/install-hooks.sh",
+        "prepublishOnly": "bun run build"
+    },
+    "keywords": ["ai", "assistant", "cli", "agent", "kobold"],
+    "author": "0xKobold Team",
+    "license": "MIT",
+    "dependencies": {
+        "@mariozechner/pi-agent-core": "0.56.2",
+        "@mariozechner/pi-coding-agent": "0.56.2",
+        "@mariozechner/pi-tui": "0.56.2",
+        "ajv": "^8.18.0",
+        "blessed": "^0.1.81",
+        "commander": "^11.1.0",
+        "discord.js": "^14.25.1",
+        "glob": "^10.5.0",
+        "json5": "^2.2.3",
+        "react": "^19.2.4",
+        "sharp": "^0.33.5",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@types/blessed": "^0.1.27",
+        "@types/json5": "^2.2.0",
+        "@types/node": "^20.19.35",
+        "bun-types": "latest",
+        "typescript": "^5.9.3",
+        "@types/bun": "latest"
+    },
+    "engines": {
+        "node": ">=18.0.0",
+        "bun": ">=1.0.0"
+    },
+    "packageManager": "bun@1.3.7",
+    "private": false,
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE",
+        "package.json",
+        "USAGE.md",
+        "HEARTBEAT.md",
+        "skills/",
+        ".agents/skills/"
+    ],
+    "publishConfig": {
+        "access": "public"
+    }
+}