clementine-agent 1.0.7 → 1.0.9

package/README.md

@@ -7,11 +7,15 @@
  ╚═════╝╚══════╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝
 ```
 
-A persistent, ever-learning personal AI assistant that runs as a background daemon on macOS.
+A persistent, ever-learning personal AI assistant that runs as a background daemon on macOS and Linux.
 Built on the [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code-sdk), Obsidian-compatible vault, and SQLite FTS5.
 
 Connects to Discord, Slack, Telegram, WhatsApp, and webhooks. Remembers everything. Runs 24/7.
 
+**Requirements:** Node.js 20+ (22 recommended) · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) authenticated · macOS or Linux.
+
+**Contents:** [How it works](#how-it-works) · [Install](#install-recommended) · [Architecture](#architecture) · [CLI](#cli-reference) · [Configuration](#configuration) · [Channels](#channels) · [Agents & Teams](#agents--teams) · [Cron](#scheduled-tasks--cron-jobs) · [Unleashed mode](#unleashed-mode) · [Self-improvement](#self-improvement) · [Vault](#vault) · [Development](#development) · [Troubleshooting](#troubleshooting)
+
 ---
 
 ## How it works
@@ -63,45 +67,55 @@ The result: Clementine gets better the more you talk to it.
 
 ---
 
-## Prerequisites
-
-- **Node.js 20-24 LTS** — `nvm install 22`
-- **Claude Code CLI** — already installed if you're reading this in Claude Code
+## Install (recommended)
 
-## Quick start
+Runtime: **Node.js 22 (recommended) or Node.js 20+**.
 
-**Option A — npm (recommended):**
 ```bash
-npm install -g clementine-agent
+npm install -g clementine-agent@latest
 clementine setup
 ```
 
-**Option B — from source (for development):**
+After setup:
+
 ```bash
-git clone https://github.com/Natebreynolds/Clementine-AI-Assistant.git clementine
-cd clementine
-bash install.sh
+clementine launch         # start as background daemon
+clementine status         # verify it's running
+clementine dashboard      # open the web command center
 ```
 
-The install script handles everything: system dependencies (redis, libomp, build tools), npm packages, TypeScript build, global CLI install, and launches the setup wizard. Safe to re-run — skips anything already installed.
+Already installed? Update in place with `clementine update`.
 
-The setup wizard auto-generates a Discord bot invite URL from your token and offers to open it in your browser — no need to visit the Developer Portal manually.
+### Troubleshooting
 
-After setup:
+**`EACCES: permission denied` on `npm install -g`.** Your Node was installed system-wide (`/usr/local/lib/...`) and npm can't write there without sudo. Fix it once, permanently:
 
 ```bash
-clementine launch         # start as background daemon
-clementine status         # verify it's running
-clementine dashboard      # open the web command center
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
+npm install -g clementine-agent@latest
 ```
 
-Already have it? Update in place:
+Or install Node via [nvm](https://github.com/nvm-sh/nvm) — user-scoped by default, no permission issues ever.
 
+**`clementine: command not found` after install succeeded.** Run `npm config get prefix` — its `/bin` directory needs to be on your `PATH`. Add `export PATH="$(npm config get prefix)/bin:$PATH"` to your shell profile.
+
+**Node version too old.** Install via nvm:
 ```bash
-clementine update
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+nvm install 22
+```
+
+### Install from source (for development)
+
+```bash
+git clone https://github.com/Natebreynolds/Clementine-AI-Assistant.git clementine
+cd clementine
+bash install.sh
 ```
 
-That's it. Clementine is now running, connected to your configured channels, and learning.
+Handles system dependencies (redis, libomp, build tools), npm packages, TypeScript build, global CLI install, and launches the setup wizard. Safe to re-run.
 
 ---
 
@@ -420,6 +434,43 @@ ENABLE_1M_CONTEXT=false    # Enable 1M token context for Sonnet (toggle in dashb
 
 Secrets can also be stored in macOS Keychain (`security find-generic-password`) — Clementine checks Keychain as a fallback for any missing `.env` value.
 
+### Tuning Clementine
+
+Clementine ships with sensible defaults. To change anything, use:
+
+```bash
+clementine config set <KEY> <value>   # writes to ~/.clementine/.env
+clementine config get <KEY>
+clementine config list                # show all overrides
+clementine restart                    # apply changes
+```
+
+Your overrides live in `~/.clementine/.env` — **they survive every `npm update -g` / `clementine update`** because they're in your data home, not the package directory.
+
+**Commonly tuned knobs:**
+
+| Key | Default | What it does |
+|-----|---------|--------------|
+| `BUDGET_CHAT_USD` | `5.00` | Max spend per interactive chat message |
+| `BUDGET_CRON_T1_USD` | `2.00` | Max spend per tier-1 cron job |
+| `BUDGET_CRON_T2_USD` | `5.00` | Max spend per tier-2 cron job |
+| `BUDGET_HEARTBEAT_USD` | `0.50` | Max spend per heartbeat tick |
+| `DEFAULT_MODEL_TIER` | `sonnet` | Default model: `haiku` / `sonnet` / `opus` |
+| `ENABLE_1M_CONTEXT` | `false` | Enable Sonnet 1M-token context (beta) |
+| `HEARTBEAT_INTERVAL_MINUTES` | `30` | How often the agent auto-checks in |
+| `HEARTBEAT_ACTIVE_START` | `8` | First hour of the active window (0–23) |
+| `HEARTBEAT_ACTIVE_END` | `22` | Last hour of the active window |
+| `TIMEZONE` | system TZ | IANA timezone string (e.g., `America/Los_Angeles`) |
+| `ALLOW_ALL_USERS` | `false` | `true` = skip owner-only gate (trust all DMs) |
+| `ASSISTANT_NAME` | `Clementine` | Display name across channels |
+
+Example — raise the chat budget to `$10` without ever touching source:
+
+```bash
+clementine config set BUDGET_CHAT_USD 10
+clementine restart
+```
+
 ---
 
 ## Models
@@ -728,15 +779,6 @@ Key system files:
 
 ---
 
-## Requirements
-
-- **Node.js 20-24 LTS** (for `--import` loader and `cpSync`)
-- **macOS** (Keychain integration, LaunchAgent — works on Linux without these)
-- **Claude Code CLI** installed and authenticated (`npm install -g @anthropic-ai/claude-code && claude login`)
-- No API key needed — authentication is handled by the Claude Code CLI
-
----
-
 ## Development
 
 ```bash

package/dist/agent/assistant.js

@@ -1966,7 +1966,10 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                                     const lower = errorText.toLowerCase();
                                     if (lower.includes('max_budget_usd') || lower.includes('budget')) {
                                         logger.warn({ sessionKey }, 'Chat query hit budget cap');
-                                        responseText = responseText || 'I hit the cost limit for this query. Try breaking it into smaller requests.';
+                                        responseText = responseText || (`I hit the $${BUDGET.chat.toFixed(2)} cost cap for this query. Options:\n` +
+                                            `• Break it into smaller requests\n` +
+                                            `• Reply "deep mode" to queue this as a background task with a bigger budget\n` +
+                                            `• Raise the cap permanently: \`clementine config set BUDGET_CHAT_USD 10\` then \`clementine restart\``);
                                     }
                                     else if (lower.includes('rate') && lower.includes('limit')) {
                                         hitRateLimit = true;

package/dist/config.d.ts

@@ -39,14 +39,14 @@ export declare const OWNER_NAME: string;
 export declare function shellEscape(s: string): string;
 export declare const MODELS: Models;
 export declare const BUDGET: {
-    readonly heartbeat: 0.5;
-    readonly cronT1: 2;
-    readonly cronT2: 5;
-    readonly chat: 5;
-    readonly unleashedPhase: undefined;
-    readonly memoryExtraction: undefined;
-    readonly summarization: undefined;
-    readonly reflection: undefined;
+    heartbeat: number;
+    cronT1: number;
+    cronT2: number;
+    chat: number;
+    unleashedPhase: undefined;
+    memoryExtraction: undefined;
+    summarization: undefined;
+    reflection: undefined;
 };
 export declare const DEFAULT_MODEL_TIER: keyof Models;
 export declare const MODEL: string;

package/dist/config.js

@@ -98,11 +98,13 @@ export const MODELS = {
     opus: 'claude-opus-4-6',
 };
 // ── Budget caps (USD per query) ──────────────────────────────────────
+// User-tunable via `clementine config set BUDGET_<NAME>_USD <value>`
+// (writes to ~/.clementine/.env, survives npm update -g).
 export const BUDGET = {
-    heartbeat: 0.50, // $0.50 per heartbeat (Haiku, cheap)
-    cronT1: 2.00, // $2 per tier-1 cron job (needs room for outlook+search)
-    cronT2: 5.00, // $5 per tier-2 cron job
-    chat: 5.00, // $5 per interactive chat message
+    heartbeat: Number(getEnv('BUDGET_HEARTBEAT_USD', '0.50')), // per heartbeat (Haiku)
+    cronT1: Number(getEnv('BUDGET_CRON_T1_USD', '2.00')), // per tier-1 cron job
+    cronT2: Number(getEnv('BUDGET_CRON_T2_USD', '5.00')), // per tier-2 cron job
+    chat: Number(getEnv('BUDGET_CHAT_USD', '5.00')), // per interactive chat
     unleashedPhase: undefined,
     memoryExtraction: undefined,
     summarization: undefined,

package/dist/tools/admin-tools.js

@@ -1137,7 +1137,7 @@ export function registerAdminTools(server) {
     // ── Source Self-Edit Tools ──────────────────────────────────────────────
     const SELF_IMPROVE_DIR = path.join(BASE_DIR, 'self-improve');
     const PENDING_SOURCE_DIR = path.join(SELF_IMPROVE_DIR, 'pending-source-changes');
-    server.tool('self_edit_source', 'Edit Clementine source code safely. Validates in a staging worktree, commits, builds, and triggers restart only if compilation succeeds. The daemon picks up the pending change and executes it.', {
+    server.tool('self_edit_source', 'Edit most Clementine TypeScript source files (for new features or bug fixes). Validates in a staging worktree, compiles, and triggers restart on success. Blocked files: `src/config.ts`, `src/gateway/security-scanner.ts`, `src/security/scanner.ts`. Do NOT use this tool to change user-tunable settings (budget caps, model tier, heartbeat interval, timezone, channel IDs, etc.) — those live in `~/.clementine/.env` and are managed by the user via `clementine config set KEY value`, which survives `clementine update` / `npm update -g`.', {
         file: z.string().describe('Path relative to src/ (e.g., "channels/discord-agent-bot.ts")'),
         content: z.string().describe('Complete new file content'),
         reason: z.string().describe('Why this change is being made'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",