@aman_asmuei/aman-agent 0.31.0 → 0.33.0

package/README.md

@@ -17,17 +17,17 @@
    
   <a href="https://github.com/amanasmuei/aman-agent/actions"><img src="https://img.shields.io/github/actions/workflow/status/amanasmuei/aman-agent/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI status" /></a>
   &nbsp;
-  <img src="https://img.shields.io/badge/tests-429_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="429 tests passing" />
+  <img src="https://img.shields.io/badge/tests-531_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="531 tests passing" />
   &nbsp;
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 20+" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+" />
   &nbsp;
   <img src="https://img.shields.io/badge/typescript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="Strict TypeScript" />
   &nbsp;
-  <img src="https://img.shields.io/badge/bundle-340_KB-informational?style=flat-square" alt="Bundle size: 340 KB" />
+  <img src="https://img.shields.io/badge/bundle-384_KB-informational?style=flat-square" alt="Bundle size: 384 KB" />
   &nbsp;
   <img src="https://img.shields.io/badge/LLMs-6_providers-8a2be2?style=flat-square" alt="6 LLM providers" />
   &nbsp;
@@ -39,7 +39,9 @@
 </p>
 
 <p align="center">
+  <a href="#whats-new-in-v0330"><kbd> What's New </kbd></a>
   <a href="#quick-start"><kbd> Quick Start </kbd></a>
+  <a href="#project-dev-mode-recommended"><kbd> Dev Mode </kbd></a>
   <a href="#architecture-at-a-glance"><kbd> Architecture </kbd></a>
   <a href="#features"><kbd> Features </kbd></a>
   <a href="#commands"><kbd> Commands </kbd></a>
@@ -50,7 +52,7 @@
 
 <p align="center">
   <sub>
-    <b>Try it in 10 seconds →</b>&nbsp;&nbsp;<code>npx @aman_asmuei/aman-agent</code>
+    <b>Install in 10 seconds →</b>&nbsp;&nbsp;<code>curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash</code>
   </sub>
 </p>
 
@@ -59,12 +61,13 @@
 <details>
 <summary><strong>Table of Contents</strong></summary>
 
-- [What's New](#whats-new-in-v0300)
+- [What's New](#whats-new-in-v0330)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
 - [Architecture at a Glance](#architecture-at-a-glance)
 - [Quick Start](#quick-start)
 - [Usage Guide](#usage-guide)
+  - [Project Dev Mode](#project-dev-mode-recommended)
   - [Your First Conversation](#your-first-conversation)
   - [How Memory Works](#how-memory-works)
   - [Files & Images](#working-with-files--images)
@@ -94,42 +97,69 @@
 
 ---
 
-## What's New in v0.31.0
+## What's New in v0.33.0
 
-> **Multi-agent (A2A) via MCP server mode.**<br/>
-> Multiple `aman-agent` instances on the same machine can now discover each other via a local registry and delegate tasks to each other over the MCP protocol. No new wire format, no broker, no new runtime daemon.
+> **One command. Full context. Zero setup.**
 
-<table>
-<tr>
-<td width="33%" valign="top">
+### `aman-agent dev` — Your New Way to Start Coding
 
-**`aman-agent serve`**
+```bash
+cd ~/projects/amantrade && aman-agent dev
+```
 
-Run any profile as a local MCP server. Registers in `~/.aman-agent/registry.json` (mode `0600`), exposes `agent.info`, `agent.delegate`, and `agent.send` tools over localhost HTTP with bearer auth.
+Open any project, and aman-agent **automatically detects your stack**, **recalls your past decisions from memory**, and **generates a project-specific CLAUDE.md** — then launches Claude Code with everything loaded. No more re-explaining yourself.
 
-</td>
-<td width="33%" valign="top">
+```
+$ aman-agent dev ~/projects/amantrade
 
-**`/delegate @coder <task>`**
+  Detected: Go (Fiber) + Postgresql + Docker + Github-actions
+  Recalled: 8 memories (4 decisions, 3 corrections, 1 convention)
+  ✓ CLAUDE.md written (template mode)
 
-From any other `aman-agent`, delegate to a running serve instance by handle. The `@`-prefix routes through `delegateRemote` which dials via `StreamableHTTPClientTransport` using the bearer from the registry.
+  Launching Claude Code...
+```
 
-</td>
-<td width="33%" valign="top">
+| Flag | What it does |
+|:---|:---|
+| `--smart` | Use your configured LLM to synthesize a smarter CLAUDE.md |
+| `--no-launch` | Generate CLAUDE.md only, don't start Claude Code |
+| `--diff` | Preview what would change without writing |
+| `--force` | Regenerate even if CLAUDE.md is fresh |
 
-**`/agents list|info|ping`**
+Works with **multiple projects** simultaneously — each terminal gets its own `aman-agent dev`, all sharing the same memory database. Decisions from one project flow into the next.
 
-Discover, inspect, and latency-check every agent currently running on this machine. `/agents list` merges local registry entries with remotes (local wins on name collision).
+---
 
-</td>
-</tr>
-</table>
+<details>
+<summary><strong>v0.32.0 — Install anywhere, zero prerequisites</strong></summary>
 
-See the [Multi-agent (A2A)](#multi-agent-a2a) section below for the full walkthrough.
+### Install on any machine — no Node.js required
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash
+```
+
+Works on **Linux** (x64, arm64, armv7l), **macOS** (x64, Apple Silicon), **Raspberry Pi**, **VPS**, and **servers**. Vendors Node.js 22 LTS invisibly. No sudo needed.
+
+| Feature | Details |
+|:---|:---|
+| **Consolidated config** | All state now lives under `~/.aman-agent/` — one directory to backup, sync, or `scp` to a new machine. Existing users are auto-migrated on first run. |
+| **Docker support** | `docker run -it -e ANTHROPIC_API_KEY=sk-... ghcr.io/amanasmuei/aman-agent` — multi-arch image (amd64 + arm64). |
+| **`aman-agent setup`** | Full configuration wizard — provider, identity, and presets. |
+| **`aman-agent update`** | Self-update, works with both vendored and npm installs. |
+| **`aman-agent uninstall`** | Clean removal of all data and config. |
+| **Headless mode** | Auto-detects LLM provider from env vars. Clean error when no TTY (systemd, Docker, CI). |
+
+</details>
 
 <details>
 <summary><strong>Highlights from earlier releases</strong></summary>
 
+**v0.31 — Multi-agent (A2A) via MCP server mode**
+- `aman-agent serve` runs any profile as a local MCP server
+- `/delegate @coder <task>` for cross-agent delegation
+- `/agents list|info|ping` for discovery and health checks
+
 **v0.30 — Agent hardening**
 - Delegation confirmation prompts (no more silent sub-agents)
 - Persistent background task state surviving crashes
@@ -247,10 +277,11 @@ flowchart LR
 | `skill-engine.ts` + `crystallization.ts` | Auto-triggers domain skills from context; promotes post-mortem lessons into reusable, versioned skills | `src/skill-engine.ts`, `src/crystallization.ts` |
 | `user-model.ts` + `personality.ts` | Cross-session trust (EMA), sentiment baseline, burnout risk, time-of-day tone shifts, wellbeing nudges | `src/user-model.ts`, `src/personality.ts` |
 | `observation.ts` + `postmortem.ts` | Passive session telemetry + LLM-generated structured post-mortems on session end | `src/observation.ts`, `src/postmortem.ts` |
+| `dev/` | Project stack detection, context assembly, CLAUDE.md generation — powers `aman-agent dev` | `src/dev/` |
 | `llm/` | 6 pluggable providers — Anthropic, OpenAI, Ollama, GitHub Copilot, OpenAI-compatible, Claude Code CLI | `src/llm/` |
 | `mcp/` | MCP v1.27 client with stdio transport and auto-reconnect | `src/mcp/` |
 
-**Stateless by default.** All state lives in `~/.acore`, `~/.arules`, `~/.aflow`, `~/.askill`, `~/.aeval`, and `~/.amem` — portable, inspectable markdown + a local SQLite file. Nothing leaves your machine except what you send to your chosen LLM.
+**Stateless by default.** All state lives in `~/.aman-agent/` — identity, rules, workflows, skills, eval, and memory in one portable directory. Nothing leaves your machine except what you send to your chosen LLM.
 
 </details>
 
@@ -258,14 +289,27 @@ flowchart LR
 
 ## Quick Start
 
-### 1. Run
+### 1. Install
 
 ```bash
-# Run directly (always latest)
-npx @aman_asmuei/aman-agent
+# One-liner install (no Node.js required) — Linux, macOS, Raspberry Pi
+curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/install.sh | bash
 
-# Or install globally
+# Or via npm (if you already have Node.js 18+)
 npm install -g @aman_asmuei/aman-agent
+
+# Or via Docker
+docker run -it -e ANTHROPIC_API_KEY=sk-... ghcr.io/amanasmuei/aman-agent
+```
+
+### 2. Run
+
+```bash
+# Start a conversation
+aman-agent
+
+# Or jump straight into a project with full context
+aman-agent dev ~/projects/my-app
 ```
 
 **Zero config if you already have an API key in your environment:**
@@ -327,6 +371,70 @@ aman-agent --budget 12000
 A step-by-step walkthrough of how to use aman-agent day-to-day. Click any section below to expand.
 
 <details open>
+<summary><strong>Project Dev Mode (recommended)</strong></summary>
+
+### Project Dev Mode
+
+The fastest way to start working on any project. One command sets up everything:
+
+```bash
+aman-agent dev
+```
+
+**What happens:**
+
+1. **Stack Detection** — Scans your project directory for `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, `docker-compose.yml`, `.github/workflows/`, and more
+2. **Memory Recall** — Queries your amem database for past decisions, corrections, and conventions related to this project and stack
+3. **Context Assembly** — Pulls your identity (acore), guardrails (arules), and developer preferences into a structured CLAUDE.md
+4. **Auto-Launch** — Launches Claude Code in the project directory with full context loaded
+
+```
+$ aman-agent dev ~/projects/amantrade
+
+  Detected: Go (Fiber) + Postgresql + Docker + Github-actions
+  Recalled: 8 memories (4 decisions, 3 corrections, 1 convention)
+  ✓ CLAUDE.md written (template mode)
+
+  Launching Claude Code...
+```
+
+**Smart mode** — Use your LLM to synthesize a more tailored CLAUDE.md:
+
+```bash
+aman-agent dev --smart
+```
+
+The LLM merges related corrections into single convention statements and removes redundancy. Falls back to template mode automatically if the LLM call fails.
+
+**Multi-project workflow** — Each terminal is independent:
+
+```bash
+# Terminal 1
+aman-agent dev ~/projects/amantrade
+
+# Terminal 2
+aman-agent dev ~/projects/aman-mcp
+
+# Terminal 3
+aman-agent dev ~/projects/new-api
+```
+
+All three share the same amem database. A decision you make in one project is available to the others on next run.
+
+**Staleness detection** — If you've made new decisions since the last CLAUDE.md generation, `aman-agent dev` auto-updates it and shows you what changed:
+
+```
+✓ CLAUDE.md updated (3 changes)
+  + Added: zerolog convention (from correction 2026-04-10)
+  + Added: rate limiting at gateway level (from decision 2026-04-11)
+  - Removed: slog preference (superseded by zerolog correction)
+```
+
+If the CLAUDE.md is still fresh, it skips regeneration and launches Claude Code immediately.
+
+</details>
+
+<details>
 <summary><strong>Your First Conversation</strong></summary>
 
 ### Your First Conversation
@@ -919,25 +1027,32 @@ Here's what a typical day looks like with aman-agent:
 
 ```
 Morning:
-  $ cd ~/project && aman-agent
-  → Loads project context, active plan, memories
+  $ aman-agent dev ~/projects/amantrade
+  → Detects stack: Go (Fiber) + PostgreSQL + Docker
+  → Recalls 12 memories (decisions, conventions, corrections)
+  → Generates project-specific CLAUDE.md
+  → Launches Claude Code — full context loaded, zero re-explaining
   → "Welcome back. You're on step 3 of Auth API."
-  → Work on your plan, skills auto-activate as needed
-  → /plan done after each step, commit your work
+
+  # Working on a second project in parallel?
+  $ aman-agent dev ~/projects/aman-mcp    # new terminal
+  → Same memory database, different project context
+  → Decisions from amantrade are available here too
 
 Afternoon:
+  → Work on your plan, skills auto-activate as needed
+  → /plan done after each step, commit your work
   → Personality shifts to steady pace
-  → Skills level up as you demonstrate mastery
-  → Knowledge library suggests snippets when relevant
 
 Evening:
   → /quit or Ctrl+C
   → Session auto-saved to memory
-  → Project context.md updated
   → Plan progress persisted
   → Optional quick session rating
 
 Next morning:
+  $ aman-agent dev    # in any project
+  → CLAUDE.md auto-updates if new memories exist
   → Everything picks up where you left off
 ```
 
@@ -1237,6 +1352,20 @@ sequenceDiagram
 
 ## Commands
 
+### CLI Commands
+
+| Command | Description |
+|:---|:---|
+| `aman-agent` | Start interactive chat session |
+| `aman-agent dev [path]` | Scan project, generate CLAUDE.md, launch Claude Code `[--smart\|--no-launch\|--force\|--diff]` |
+| `aman-agent init` | Set up your AI companion with a guided wizard |
+| `aman-agent serve` | Run as a local MCP server for agent delegation `[--name\|--profile]` |
+| `aman-agent setup` | Full reconfiguration wizard |
+| `aman-agent update` | Self-update to latest version |
+| `aman-agent uninstall` | Clean removal of all data and config |
+
+### Slash Commands (inside a session)
+
 | Command | Description |
 |:---|:---|
 | `/help` | Show available commands |

package/dist/delegate.js

@@ -9,22 +9,22 @@ var __export = (target, all) => {
 };
 
 // src/logger.ts
-import fs3 from "fs";
-import path3 from "path";
+import fs4 from "fs";
+import path4 from "path";
 import os3 from "os";
 function ensureDir() {
-  if (!fs3.existsSync(LOG_DIR)) {
-    fs3.mkdirSync(LOG_DIR, { recursive: true });
+  if (!fs4.existsSync(LOG_DIR)) {
+    fs4.mkdirSync(LOG_DIR, { recursive: true });
   }
 }
 function maybeRotate() {
   try {
-    if (!fs3.existsSync(LOG_PATH)) return;
-    const stat = fs3.statSync(LOG_PATH);
+    if (!fs4.existsSync(LOG_PATH)) return;
+    const stat = fs4.statSync(LOG_PATH);
     if (stat.size >= MAX_LOG_SIZE) {
       const backupPath = LOG_PATH + ".1";
-      if (fs3.existsSync(backupPath)) fs3.unlinkSync(backupPath);
-      fs3.renameSync(LOG_PATH, backupPath);
+      if (fs4.existsSync(backupPath)) fs4.unlinkSync(backupPath);
+      fs4.renameSync(LOG_PATH, backupPath);
     }
   } catch {
   }
@@ -42,7 +42,7 @@ function write(level, module, message, data) {
     if (data !== void 0) {
       entry.data = data instanceof Error ? data.message : String(data);
     }
-    fs3.appendFileSync(LOG_PATH, JSON.stringify(entry) + "\n");
+    fs4.appendFileSync(LOG_PATH, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
@@ -50,8 +50,8 @@ var LOG_DIR, LOG_PATH, MAX_LOG_SIZE, log;
 var init_logger = __esm({
   "src/logger.ts"() {
     "use strict";
-    LOG_DIR = path3.join(os3.homedir(), ".aman-agent");
-    LOG_PATH = path3.join(LOG_DIR, "debug.log");
+    LOG_DIR = path4.join(os3.homedir(), ".aman-agent");
+    LOG_PATH = path4.join(LOG_DIR, "debug.log");
     MAX_LOG_SIZE = 1048576;
     log = {
       debug: (module, message, data) => write("debug", module, message, data),
@@ -62,21 +62,21 @@ var init_logger = __esm({
 });
 
 // src/server/registry.ts
-import fs10 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path11 from "path";
 import os9 from "os";
 function amanAgentHome() {
-  return process.env.AMAN_AGENT_HOME || path10.join(os9.homedir(), ".aman-agent");
+  return process.env.AMAN_AGENT_HOME || path11.join(os9.homedir(), ".aman-agent");
 }
 function registryPath() {
-  return path10.join(amanAgentHome(), "registry.json");
+  return path11.join(amanAgentHome(), "registry.json");
 }
 async function ensureHome() {
-  await fs10.mkdir(amanAgentHome(), { recursive: true });
+  await fs11.mkdir(amanAgentHome(), { recursive: true });
 }
 async function readRaw() {
   try {
-    const buf = await fs10.readFile(registryPath(), "utf-8");
+    const buf = await fs11.readFile(registryPath(), "utf-8");
     const parsed = JSON.parse(buf);
     return Array.isArray(parsed) ? parsed : [];
   } catch (err) {
@@ -90,10 +90,10 @@ async function readRaw() {
 async function writeAtomic(entries) {
   await ensureHome();
   const tmp = registryPath() + ".tmp";
-  await fs10.writeFile(tmp, JSON.stringify(entries, null, 2), { mode: 384 });
-  await fs10.rename(tmp, registryPath());
+  await fs11.writeFile(tmp, JSON.stringify(entries, null, 2), { mode: 384 });
+  await fs11.rename(tmp, registryPath());
   try {
-    await fs10.chmod(registryPath(), 384);
+    await fs11.chmod(registryPath(), 384);
   } catch {
   }
 }
@@ -264,8 +264,8 @@ var init_delegate_remote = __esm({
 import pc2 from "picocolors";
 
 // src/prompt.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 import os2 from "os";
 
 // src/token-budget.ts
@@ -322,14 +322,26 @@ function buildBudgetedPrompt(components, maxTokens = 8e3) {
 }
 
 // src/user-identity.ts
+import fs2 from "fs";
+import path2 from "path";
+
+// src/config.ts
 import fs from "fs";
 import path from "path";
 import os from "os";
-var USER_FILE = path.join(os.homedir(), ".acore", "user.md");
+function homeDir() {
+  return process.env.AMAN_HOME || process.env.AMAN_AGENT_HOME || path.join(os.homedir(), ".aman-agent");
+}
+function identityDir() {
+  return path.join(homeDir(), "identity");
+}
+
+// src/user-identity.ts
+var USER_FILE = path2.join(identityDir(), "user.md");
 function loadUserIdentity() {
-  if (!fs.existsSync(USER_FILE)) return null;
+  if (!fs2.existsSync(USER_FILE)) return null;
   try {
-    const content = fs.readFileSync(USER_FILE, "utf-8");
+    const content = fs2.readFileSync(USER_FILE, "utf-8");
     const get = (key) => {
       const match = content.match(new RegExp(`^- ${key}:\\s*(.+)$`, "m"));
       return match?.[1]?.trim() ?? "";
@@ -419,19 +431,19 @@ var ECOSYSTEM_FILES = [
 ];
 function resolveLayerPath(entry, home, profile) {
   if (profile && entry.profileOverridable) {
-    const profilePath = path2.join(home, ".acore", "profiles", profile, entry.file);
-    if (fs2.existsSync(profilePath)) return profilePath;
+    const profilePath = path3.join(home, ".acore", "profiles", profile, entry.file);
+    if (fs3.existsSync(profilePath)) return profilePath;
     if (entry.name === "guardrails") {
-      const altPath = path2.join(home, ".acore", "profiles", profile, "rules.md");
-      if (fs2.existsSync(altPath)) return altPath;
+      const altPath = path3.join(home, ".acore", "profiles", profile, "rules.md");
+      if (fs3.existsSync(altPath)) return altPath;
     }
     if (entry.name === "skills") {
-      const altPath = path2.join(home, ".acore", "profiles", profile, "skills.md");
-      if (fs2.existsSync(altPath)) return altPath;
+      const altPath = path3.join(home, ".acore", "profiles", profile, "skills.md");
+      if (fs3.existsSync(altPath)) return altPath;
     }
   }
-  const globalPath = path2.join(home, entry.dir, entry.file);
-  if (fs2.existsSync(globalPath)) return globalPath;
+  const globalPath = path3.join(home, entry.dir, entry.file);
+  if (fs3.existsSync(globalPath)) return globalPath;
   return null;
 }
 function assembleSystemPrompt(maxTokens, profile) {
@@ -440,7 +452,7 @@ function assembleSystemPrompt(maxTokens, profile) {
   for (const entry of ECOSYSTEM_FILES) {
     const filePath = resolveLayerPath(entry, home, profile);
     if (filePath) {
-      const content = fs2.readFileSync(filePath, "utf-8").trim();
+      const content = fs3.readFileSync(filePath, "utf-8").trim();
       components.push({
         name: entry.name,
         content,
@@ -448,9 +460,9 @@ function assembleSystemPrompt(maxTokens, profile) {
       });
     }
   }
-  const contextPath = path2.join(process.cwd(), ".acore", "context.md");
-  if (fs2.existsSync(contextPath)) {
-    const content = fs2.readFileSync(contextPath, "utf-8").trim();
+  const contextPath = path3.join(process.cwd(), ".acore", "context.md");
+  if (fs3.existsSync(contextPath)) {
+    const content = fs3.readFileSync(contextPath, "utf-8").trim();
     components.push({
       name: "context",
       content,
@@ -502,8 +514,8 @@ init_logger();
 init_logger();
 import pc from "picocolors";
 import * as p from "@clack/prompts";
-import fs9 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path10 from "path";
 import os8 from "os";
 
 // src/personality.ts
@@ -534,9 +546,9 @@ import {
   importFromTeam,
   syncToCopilot
 } from "@aman_asmuei/amem-core";
-import path4 from "path";
+import path5 from "path";
 import os4 from "os";
-import fs4 from "fs";
+import fs5 from "fs";
 var db = null;
 var currentProject = "global";
 function getDb() {
@@ -557,13 +569,13 @@ async function memoryRecall(query, opts) {
 }
 
 // src/postmortem.ts
-import fs6 from "fs/promises";
-import path6 from "path";
+import fs7 from "fs/promises";
+import path7 from "path";
 import os6 from "os";
 
 // src/observation.ts
-import fs5 from "fs/promises";
-import path5 from "path";
+import fs6 from "fs/promises";
+import path6 from "path";
 import os5 from "os";
 
 // src/postmortem.ts
@@ -571,12 +583,12 @@ init_logger();
 
 // src/crystallization.ts
 init_logger();
-import fs7 from "fs/promises";
-import path7 from "path";
-
-// src/user-model.ts
 import fs8 from "fs/promises";
 import path8 from "path";
+
+// src/user-model.ts
+import fs9 from "fs/promises";
+import path9 from "path";
 import os7 from "os";
 
 // src/hooks.ts