0agent 1.0.41 → 1.0.43

package/README.md

@@ -2,141 +2,216 @@
 
 **A persistent, learning AI agent that runs on your machine.**
 
+> Runs a local daemon. Learns from every task. Remembers everything. Gets better over time.
+
 ```bash
 npx 0agent@latest
 ```
 
-That's it. 0agent installs, walks you through a 4-step setup, and starts a daemon that gets smarter with every task you run.
+[![npm](https://img.shields.io/npm/v/0agent?color=black&label=npm)](https://www.npmjs.com/package/0agent)
+[![license](https://img.shields.io/badge/license-Apache%202.0-black)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-black)](https://nodejs.org)
 
 ---
 
-## What it does
+## What is this?
 
-```bash
-# Sprint workflow
-0agent /office-hours "I want to build a Slack bot"
-0agent /plan-ceo-review
-0agent /plan-eng-review
-0agent /build
-0agent /review
-0agent /qa --url https://staging.myapp.com
-0agent /ship
-0agent /retro
-
-# One-off tasks
-0agent /research "Acme Corp Series B funding"
-0agent /debug "TypeError at auth.ts:47"
-0agent /test-writer src/payments/
-0agent /refactor src/api/routes.ts
-
-# Plain language
-0agent run "fix the auth bug Marcus reported"
-0agent run "research Acme Corp and draft a follow-up email to Sarah"
-
-# Entity-scoped (learns who you are)
-0agent run "pull auth metrics" --entity sarah_chen
-```
+0agent is a CLI agent that runs as a background daemon on your machine. It executes real tasks — shell commands, file operations, web search, browser automation — using your API key, and learns from every outcome via a weighted knowledge graph.
 
----
+Unlike chat-based AI tools, 0agent:
 
-## How it learns
+- **Persists** — runs in the background, remembers past sessions
+- **Learns** — every task outcome updates edge weights in a graph; plan selection improves over time
+- **Executes** — actually runs commands, writes files, searches the web, opens browsers
+- **Syncs** — optionally backs up the knowledge graph to a private GitHub repo
 
-Every time you run a task, 0agent records which strategy it chose and whether it worked. After 50 interactions, it converges to your optimal workflow — measurably, provably, via a weighted knowledge graph.
+---
 
-- Edge weights start at 0.5 (neutral)
-- Positive outcomes push them toward 1.0
-- Negative outcomes push them toward 0.0
-- After 100 traces, plan selection is noticeably better
+## Quick start
 
----
+```bash
+npx 0agent@latest
+```
 
-## Requirements
+The wizard asks for:
+1. LLM provider + API key (Anthropic, OpenAI, xAI, Gemini, or local Ollama)
+2. GitHub repo for memory backup (optional, uses `gh` CLI if installed)
+3. Workspace folder (where the agent creates files — default: `~/0agent-workspace`)
+4. Embedding provider (for semantic memory search)
 
-- **Node.js** ≥ 20
-- **API key** for Anthropic, OpenAI, or a local Ollama instance
-- **Docker** (optional but recommended — enables sandboxed subagents)
+After setup, the chat TUI opens automatically. No manual steps.
 
 ---
 
-## Install
+## Usage
+
+### Interactive chat
 
 ```bash
-# One-liner
+0agent          # open chat (starts daemon if needed)
 npx 0agent@latest
+```
 
-# Global install
-npm install -g 0agent
-0agent init
+```
+  0agent — anthropic/claude-sonnet-4-6
+  Type a task, or /help for commands.
 
-# Or via brew (coming soon)
-brew install 0agent
+  › make a website for my coffee shop and deploy it locally
+  › build a REST API in Go with auth
+  › research my competitor's pricing and draft a response strategy
 ```
 
----
+Type while the agent works — messages queue automatically and run one after another.
 
-## Local development
+### Slash skills
 
 ```bash
-git clone https://github.com/0agent-oss/0agent
-cd 0agent
-pnpm install
-pnpm build
-
-# Run the wizard
-node bin/0agent.js init
+# Software engineering
+0agent /review           # code review current branch
+0agent /build            # run build, fix errors
+0agent /qa               # generate and run tests
+0agent /debug            # debug a failing test or error
+0agent /refactor         # refactor a file or module
+0agent /test-writer      # write unit tests
+0agent /doc              # generate documentation
+
+# Planning & strategy
+0agent /office-hours "I want to build a payments feature"
+0agent /plan-eng-review
+0agent /plan-ceo-review
+0agent /retro            # weekly retrospective
+0agent /ship             # pre-release checklist
 
-# Start daemon
-node bin/0agent.js start
+# Research
+0agent /research "Acme Corp Series B"
+0agent /security-audit
+```
 
-# Check status
-node bin/0agent.js status
+### Scheduled tasks
 
-# Open dashboard
-open http://localhost:4200
 ```
+  › /schedule add "run /retro" every Friday at 5pm
+  › /schedule add "check the build" every day at 9am
+  › /schedule list
+```
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `/model` | Show or switch model |
+| `/model add anthropic sk-ant-...` | Add a provider API key |
+| `/key anthropic sk-ant-...` | Update a stored key |
+| `/status` | Daemon health + graph stats |
+| `/skills` | List available skills |
+| `/schedule` | Manage scheduled jobs |
+| `/update` | Update to latest version |
+| `/graph` | Open 3D knowledge graph |
+| `/clear` | Clear screen |
+| `Ctrl+C` | Cancel current task |
 
 ---
 
-## Architecture
+## How it learns
+
+Every task updates a weighted knowledge graph stored in `~/.0agent/graph.db`.
 
 ```
-You → 0agent CLI → Daemon (port 4200) → Knowledge Graph
-                                      → Subagents (sandboxed)
-                                      → MCP Tools (filesystem, browser, shell)
-                                      → Learning Engine (weight propagation)
+Edge weights:  0.0 ──── 0.5 ──── 1.0
+               bad    neutral   good
+
+After each task:
+  success → weight += 0.1 × learning_rate
+  failure → weight -= 0.1 × learning_rate
+  decay   → weight → 0.5 over time (forgetting)
 ```
 
-- **Knowledge graph** — weighted, multimodal. SQLite + HNSW. Persists to `~/.0agent/graph.db`
-- **Subagents** — sandboxed (Docker/Podman/process). Zero-trust capability tokens. Never write to the graph.
-- **MCP** — connects to any MCP server. Built-in: filesystem, shell, browser, memory.
-- **Skills** — 15 built-in YAML-defined skills. Add your own in `~/.0agent/skills/custom/`
-- **Self-improvement** — weekly analysis of skill gaps, workflow optimization, prompt refinement.
+After ~50 interactions, plan selection measurably improves. The graph also stores:
+- Discovered facts: URLs, ports, file paths, API endpoints (via `memory_write` tool)
+- Conversation history (last 8 exchanges injected as context)
+- Identity + personality per entity
 
 ---
 
-## Entity nesting
+## Memory sync
 
-0agent can learn individual personalities within an organization:
+0agent can back up its knowledge graph to a private GitHub repo:
 
-```yaml
-# One-time setup in config
-entity_nesting:
+```bash
+# Set up during init, or add manually to ~/.0agent/config.yaml:
+github_memory:
   enabled: true
-  visibility_policy:
-    allow_work_context: true       # company sees projects/tasks
-    allow_personality_profile: false  # company can't see communication style
+  token: ghp_...
+  owner: your-username
+  repo: 0agent-memory
 ```
 
-After 3+ interactions with Sarah, responses automatically match her style:
-- Terse? Leads with numbers, no preamble.
-- Bullet-point user? Bullets.
-- Exploratory? More context and options.
+- **Pulls** on daemon start
+- **Pushes** every 30 minutes if there are changes
+- **Final push** on daemon shutdown
+- The same repo doubles as a GitHub Codespace template for browser sessions
+
+---
+
+## What can the agent actually do?
 
-The company graph sees `[from member] Sarah used /build` — not the raw conversations.
+| Capability | How |
+|---|---|
+| Run shell commands | `shell_exec` — bash, any CLI tool |
+| Read / write files | `file_op` — read, write, list, mkdir |
+| Search the web | `web_search` — DuckDuckGo, no API key needed |
+| Scrape pages | `scrape_url` — full page text, tables, links |
+| Open browser | `browser_open` — system Chrome or default OS browser |
+| Remember facts | `memory_write` — persists to knowledge graph |
+| Schedule tasks | Natural language cron via `/schedule` |
+| Self-heal | Detects runtime errors, proposes + applies patches |
 
 ---
 
-## Config
+## Architecture
+
+```
+npx 0agent@latest
+       │
+       ▼
+  ┌─────────────────────────────────────────────────────────┐
+  │  CLI (bin/0agent.js + bin/chat.js)                      │
+  │  • Init wizard  • Chat TUI  • Slash commands            │
+  └───────────────────────┬─────────────────────────────────┘
+                          │ HTTP + WebSocket
+                          ▼
+  ┌─────────────────────────────────────────────────────────┐
+  │  Daemon (dist/daemon.mjs) — port 4200                   │
+  │                                                         │
+  │  SessionManager ── AgentExecutor ── LLMExecutor         │
+  │       │                  │               │              │
+  │       │            CapabilityRegistry    │              │
+  │       │            • shell_exec          │              │
+  │       │            • file_op             │              │
+  │       │            • web_search          │              │
+  │       │            • scrape_url          │              │
+  │       │            • browser_open        │              │
+  │       │            • memory_write        │              │
+  │       │                                  │              │
+  │  KnowledgeGraph ◄────── outcome feedback ┘              │
+  │  (SQLite + HNSW)                                        │
+  │       │                                                 │
+  │  GitHubMemorySync ── SchedulerManager ── SelfHealLoop   │
+  └─────────────────────────────────────────────────────────┘
+```
+
+**Key packages:**
+
+| Package | Description |
+|---|---|
+| `packages/core` | Knowledge graph, inference engine, storage adapters |
+| `packages/daemon` | HTTP server, session manager, agent executor, capabilities |
+| `bin/chat.js` | Claude Code-style TUI with message queue, WS events, spinner |
+| `bin/0agent.js` | CLI entry point, init wizard, daemon lifecycle |
+
+---
+
+## Configuration
 
 `~/.0agent/config.yaml` — created by `0agent init`, edit anytime:
 
@@ -144,21 +219,83 @@ The company graph sees `[from member] Sarah used /build` — not the raw convers
 llm_providers:
   - provider: anthropic
     model: claude-sonnet-4-6
-    api_key: sk-ant-...
+    api_key: sk-ant-...        # never committed to git
     is_default: true
 
+workspace:
+  path: /Users/you/0agent-workspace   # agent creates files here
+
 sandbox:
   backend: docker   # docker | podman | process | firecracker
 
-entity_nesting:
+github_memory:
   enabled: true
+  token: ghp_...
+  owner: your-username
+  repo: 0agent-memory
+
+embedding:
+  provider: nomic-ollama   # nomic-ollama | openai | none
+  model: nomic-embed-text
+  dimensions: 768
+```
 
-self_improvement:
-  schedule: weekly
+---
+
+## Local development
+
+```bash
+git clone https://github.com/cadetmaze/0agentv1
+cd 0agentv1
+pnpm install
+pnpm build
+
+# Run init wizard
+node bin/0agent.js init
+
+# Or start daemon directly
+node bin/0agent.js start
+node bin/chat.js
+
+# Bundle daemon into single file
+node scripts/bundle.mjs
+
+# Check status
+node bin/0agent.js status
+open http://localhost:4200    # 3D knowledge graph dashboard
 ```
 
+**Requirements:**
+- Node.js ≥ 20
+- pnpm (`npm install -g pnpm`)
+- API key for Anthropic, OpenAI, xAI, Gemini, or a local Ollama instance
+- Docker (optional — enables sandboxed execution)
+
+---
+
+## Roadmap
+
+- [ ] Telegram bot interface
+- [ ] MCP server support (connect to external tools)
+- [ ] Team collaboration (shared graph, sync via GitHub)
+- [ ] Mobile companion app
+- [ ] Plugin SDK for custom capabilities
+
+---
+
+## Contributing
+
+Issues and PRs welcome. This is early-stage software — things break, APIs change.
+
+1. Fork the repo
+2. `pnpm install && pnpm build`
+3. Make changes to `packages/daemon/src/` or `bin/`
+4. `node scripts/bundle.mjs` to rebuild the bundle
+5. Test with `node bin/0agent.js init`
+6. Submit a PR
+
 ---
 
 ## License
 
-Apache 2.0
+[Apache 2.0](LICENSE) — use it, fork it, build on it.

package/bin/0agent.js

@@ -369,11 +369,20 @@ ${ghToken && ghOwner ? `\ngithub_memory:\n  enabled: true\n  token: "${ghToken}"
     console.log('  ✓ Built-in skills installed');
   }
 
-  // Always kill any existing daemon so the new config (with API key) is loaded
-  try { stopDaemon(); await sleep(800); } catch {}
+  // Force-kill any running daemon so new config is loaded fresh
+  await forceStopDaemon();
 
-  console.log('\n  Starting daemon...\n');
+  // Start fresh daemon with new config
+  console.log('\n  Starting...');
   await startDaemon();
+
+  // Open chat TUI immediately — no manual steps needed
+  const chatSc = resolve(dirname(new URL(import.meta.url).pathname), 'chat.js');
+  if (existsSync(chatSc)) {
+    const { spawn: sp } = await import('node:child_process');
+    const p = sp(process.execPath, [chatSc], { stdio: 'inherit' });
+    await new Promise(r => p.on('close', r));
+  }
 }
 
 function detectSandboxes() {
@@ -391,9 +400,17 @@ function detectSandboxes() {
 // ─── Daemon lifecycle ─────────────────────────────────────────────────────
 
 async function startDaemon() {
+  // If still running (e.g. stop was called just before), wait a bit
   if (await isDaemonRunning()) {
-    console.log('  Daemon already running on port 4200. Run `0agent status`.');
-    return;
+    // Give it up to 3s to die before giving up
+    for (let i = 0; i < 6; i++) {
+      await sleep(500);
+      if (!await isDaemonRunning()) break;
+    }
+    if (await isDaemonRunning()) {
+      console.log('  Daemon already running on port 4200. Run `0agent status`.');
+      return;
+    }
   }
 
   if (!existsSync(CONFIG_PATH)) {
@@ -423,33 +440,42 @@ async function startDaemon() {
   child.unref();
 
   // Wait for daemon to be ready (poll /api/health)
-  process.stdout.write('  Starting');
   for (let i = 0; i < 30; i++) {
     await sleep(500);
-    process.stdout.write('.');
     if (await isDaemonRunning()) {
-      console.log(' ✓\n');
-      console.log(`  Daemon running on http://localhost:4200`);
-      console.log(`  Dashboard: http://localhost:4200`);
-      console.log(`  Run: 0agent run "your task"\n`);
+      process.stdout.write(`  \x1b[32m✓\x1b[0m Daemon ready\n`);
       return;
     }
   }
-  console.log('\n  Daemon did not start. Check logs: 0agent logs');
+  console.log('  Daemon did not start in time. Check: 0agent logs');
 }
 
 function stopDaemon() {
-  if (!existsSync(PID_PATH)) {
+  // Try PID file first
+  if (existsSync(PID_PATH)) {
+    const pid = parseInt(readFileSync(PID_PATH, 'utf8').trim(), 10);
+    try { process.kill(pid, 'SIGTERM'); } catch {}
+  } else {
     console.log('  No daemon PID file found. Is it running?');
-    return;
   }
-  const pid = parseInt(readFileSync(PID_PATH, 'utf8').trim(), 10);
-  try {
-    process.kill(pid, 'SIGTERM');
-    console.log(`  Sent SIGTERM to daemon (pid ${pid}). Shutting down...`);
-  } catch (e) {
-    console.log(`  Could not stop daemon: ${e instanceof Error ? e.message : e}`);
+  // Also kill by process name as a fallback
+  try { execSync('pkill -f "daemon.mjs" 2>/dev/null; true', { stdio: 'ignore' }); } catch {}
+}
+
+// Forcefully kill any running daemon regardless of PID file state.
+// Used after init to ensure fresh config is picked up.
+async function forceStopDaemon() {
+  // Kill by PID file if present
+  if (existsSync(PID_PATH)) {
+    const pid = parseInt(readFileSync(PID_PATH, 'utf8').trim(), 10);
+    try { process.kill(pid, 'SIGTERM'); } catch {}
   }
+  // Kill by process name (catches daemons started by chat.js or other means)
+  try { execSync('pkill -f "daemon.mjs" 2>/dev/null; true', { stdio: 'ignore' }); } catch {}
+  // Kill by port 4200 (last resort)
+  try { execSync('lsof -ti:4200 | xargs kill -9 2>/dev/null; true', { stdio: 'ignore' }); } catch {}
+  // Wait for port to be free
+  await sleep(1200);
 }
 
 async function showStatus() {

package/bin/chat.js

@@ -7,12 +7,41 @@
  * /model to switch. /key to add provider keys. Never forgets previous keys.
  */
 
-import { createInterface } from 'node:readline';
+import { createInterface, emitKeypressEvents, moveCursor, clearLine } from 'node:readline';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import YAML from 'yaml';
 
+// ─── Slash command registry (used for live menu + tab completion) ─────────────
+const SLASH_COMMANDS = [
+  // Skills
+  { cmd: '/review',        desc: 'Code review — bugs, style, security issues'     },
+  { cmd: '/build',         desc: 'Build project and fix compilation errors'        },
+  { cmd: '/qa',            desc: 'Generate and run tests'                          },
+  { cmd: '/debug',         desc: 'Debug a failing test or runtime error'           },
+  { cmd: '/refactor',      desc: 'Refactor a file or module'                       },
+  { cmd: '/test-writer',   desc: 'Write unit tests for your code'                  },
+  { cmd: '/doc',           desc: 'Generate documentation'                          },
+  { cmd: '/research',      desc: 'Research a topic, person, or company'            },
+  { cmd: '/retro',         desc: 'Weekly retrospective — what went well / badly'   },
+  { cmd: '/ship',          desc: 'Pre-release checklist — ready to deploy?'        },
+  { cmd: '/office-hours',  desc: 'Plan a new feature or project from scratch'      },
+  { cmd: '/plan-eng-review',desc:'Engineering planning review'                     },
+  { cmd: '/security-audit',desc: 'Security audit — find vulnerabilities'           },
+  { cmd: '/design-review', desc: 'Design review — architecture and patterns'       },
+  // Built-ins
+  { cmd: '/model',         desc: 'Show or switch the LLM model'                   },
+  { cmd: '/key',           desc: 'Update a stored API key'                         },
+  { cmd: '/status',        desc: 'Daemon health, graph stats, active sessions'     },
+  { cmd: '/skills',        desc: 'List all available skills'                       },
+  { cmd: '/schedule',      desc: 'Manage scheduled / recurring tasks'              },
+  { cmd: '/update',        desc: 'Update 0agent to the latest version'             },
+  { cmd: '/graph',         desc: 'Open 3D knowledge graph in browser'              },
+  { cmd: '/clear',         desc: 'Clear the screen'                                },
+  { cmd: '/help',          desc: 'Show this help'                                  },
+];
+
 const AGENT_DIR   = resolve(homedir(), '.0agent');
 const CONFIG_PATH = resolve(AGENT_DIR, 'config.yaml');
 const BASE_URL    = process.env['ZEROAGENT_URL'] ?? 'http://localhost:4200';
@@ -183,7 +212,7 @@ function printHeader() {
   const modelStr = provider ? `${provider.provider}/${provider.model}` : 'no model';
   console.log();
   console.log(fmt(C.bold, '  0agent') + fmt(C.dim, ` — ${modelStr}`));
-  console.log(fmt(C.dim, '  Type a task, or /help for commands. Ctrl+C to exit.\n'));
+  console.log(fmt(C.dim, '  Type a task or /command — press Tab to browse, / to see all.\n'));
 }
 
 function printInsights() {
@@ -328,6 +357,14 @@ function handleWsEvent(event) {
       if (r.files_written?.length) console.log(`\n  ${fmt(C.green, '✓')} ${r.files_written.join(', ')}`);
       if (r.tokens_used) process.stdout.write(fmt(C.dim, `\n  ${r.tokens_used} tokens · ${r.model ?? ''}\n`));
 
+      // Contextual next-step suggestions
+      const suggestions = _suggestNext(lineBuffer, r);
+      if (suggestions.length > 0 && messageQueue.length === 0) {
+        process.stdout.write(
+          `  ${fmt(C.dim, '→')} ${suggestions.map(s => fmt(C.cyan, s)).join(fmt(C.dim, '  ·  '))}\n`
+        );
+      }
+
       // Confirm server if port mentioned
       confirmServer(r, lineBuffer);
       lineBuffer = '';
@@ -381,6 +418,26 @@ function handleWsEvent(event) {
   }
 }
 
+function _suggestNext(output, result) {
+  const text = (output + ' ' + (result?.output ?? '') + ' ' + JSON.stringify(result?.files_written ?? [])).toLowerCase();
+  if (text.includes('written') || text.includes('creat') || text.includes('built') || (result?.files_written?.length > 0)) {
+    return ['/review', '/qa'];
+  }
+  if (text.includes('test') || text.includes('spec') || text.includes('pass')) {
+    return ['/ship'];
+  }
+  if (text.includes('research') || text.includes('found') || text.includes('results')) {
+    return ['/office-hours', '/doc'];
+  }
+  if (text.includes('bug') || text.includes('fix') || text.includes('error') || text.includes('debug')) {
+    return ['/qa', '/review'];
+  }
+  if (text.includes('deploy') || text.includes('server') || text.includes('running')) {
+    return ['/qa', '/ship'];
+  }
+  return [];
+}
+
 async function confirmServer(result, output) {
   const allText = [...(result.commands_run ?? []), output].join(' ');
   const portMatch = allText.match(/(?:localhost:|port\s*[=:]?\s*)(\d{4,5})/i);
@@ -751,23 +808,116 @@ async function handleCommand(input) {
   }
 }
 
+// ─── Live slash-command menu ──────────────────────────────────────────────────
+// Drawn below the prompt as the user types. Uses moveCursor to avoid cursor
+// save/restore conflicts with readline.
+let _menuLines = 0; // how many lines the current menu occupies below the cursor
+
+function _drawMenu(filter) {
+  if (pendingResolve) { _clearMenu(); return; } // don't show while session running
+
+  const items = filter === null ? [] :
+    SLASH_COMMANDS.filter(c =>
+      !filter || c.cmd.slice(1).toLowerCase().startsWith(filter.toLowerCase())
+    ).slice(0, 10);
+
+  // If nothing changed (same count), skip redraw to avoid flicker
+  if (items.length === 0) { _clearMenu(); return; }
+
+  const needed = items.length + 1; // +1 for blank line
+
+  // Move down past existing menu lines (or 0), then clear downward
+  const existingLines = _menuLines;
+  if (existingLines > 0) {
+    moveCursor(process.stdout, 0, existingLines);
+    for (let i = 0; i < existingLines; i++) {
+      clearLine(process.stdout, 0);
+      if (i < existingLines - 1) moveCursor(process.stdout, 0, -1);
+    }
+    moveCursor(process.stdout, 0, -(existingLines - 1));
+  }
+
+  // Print blank separator + menu items, tracking column 0
+  process.stdout.write('\n');
+  for (const m of items) {
+    process.stdout.write(
+      `  ${fmt(C.cyan, m.cmd.padEnd(20))} ${fmt(C.dim, m.desc)}\x1b[K\n`
+    );
+  }
+
+  // Move back up to the prompt line and restore cursor after the typed text
+  moveCursor(process.stdout, 0, -(needed));
+  // Jump to end of current line (readline already put cursor there)
+  moveCursor(process.stdout, 999, 0);
+
+  _menuLines = needed;
+}
+
+function _clearMenu() {
+  if (_menuLines === 0) return;
+  const n = _menuLines;
+  _menuLines = 0;
+  moveCursor(process.stdout, 0, n);
+  for (let i = 0; i < n; i++) {
+    clearLine(process.stdout, 0);
+    moveCursor(process.stdout, 0, -1);
+  }
+  moveCursor(process.stdout, 0, 1); // back to prompt line
+}
+
 // ─── Main REPL ────────────────────────────────────────────────────────────────
 const rl = createInterface({
   input:  process.stdin,
   output: process.stdout,
   prompt: `\n  ${fmt(C.cyan, '›')} `,
   historySize: 100,
-  completer: (line) => {
-    const commands = ['/model', '/key', '/status', '/skills', '/graph', '/clear', '/help',
-      '/schedule', '/schedule list', '/schedule add',
-      '/review', '/build', '/debug', '/qa', '/research', '/refactor', '/test-writer', '/retro'];
-    const hits = commands.filter(c => c.startsWith(line));
-    return [hits.length ? hits : commands, line];
+  completer: (line, callback) => {
+    if (!line.startsWith('/')) return callback(null, [[], line]);
+
+    const filter = line.slice(1).toLowerCase();
+    const matches = SLASH_COMMANDS.filter(c =>
+      !filter || c.cmd.slice(1).startsWith(filter)
+    );
+
+    if (matches.length === 0) return callback(null, [[], line]);
+
+    // Single match — let readline silently auto-complete
+    if (matches.length === 1) {
+      _clearMenu();
+      return callback(null, [[matches[0].cmd + ' '], line]);
+    }
+
+    // Multiple matches — print formatted menu, suppress readline's plain list
+    _clearMenu();
+    process.stdout.write('\n\n');
+    for (const m of matches.slice(0, 12)) {
+      process.stdout.write(`  ${fmt(C.cyan, m.cmd.padEnd(22))} ${fmt(C.dim, m.desc)}\n`);
+    }
+    if (matches.length > 12) {
+      process.stdout.write(`  ${fmt(C.dim, `…and ${matches.length - 12} more`)}\n`);
+    }
+    process.stdout.write('\n');
+    setImmediate(() => rl.prompt(true));
+    return callback(null, [[], line]);
   },
 });
 
-// Restore history from conversations if possible
-rl.on('history', () => {});
+// Live menu on keypress — draws below the prompt as user types
+emitKeypressEvents(process.stdin, rl);
+process.stdin.on('keypress', (_char, key) => {
+  if (key?.name === 'return' || key?.name === 'enter') {
+    _clearMenu(); // clear before readline processes the line
+    return;
+  }
+  setImmediate(() => {
+    const line = rl.line ?? '';
+    if (line.startsWith('/') && !pendingResolve) {
+      _drawMenu(line.slice(1));
+    } else {
+      _clearMenu();
+    }
+  });
+});
 
 printHeader();
 printInsights();
@@ -1075,9 +1225,21 @@ async function drainQueue() {
 }
 
 rl.on('line', async (input) => {
+  _clearMenu(); // always clear menu when a line is submitted
   const line = input.trim();
   if (!line) { rl.prompt(); return; }
 
+  // Bare `/` → show full command palette
+  if (line === '/') {
+    console.log('');
+    for (const m of SLASH_COMMANDS) {
+      console.log(`  ${fmt(C.cyan, m.cmd.padEnd(22))} ${fmt(C.dim, m.desc)}`);
+    }
+    console.log('');
+    rl.prompt();
+    return;
+  }
+
   // If a session is already running, queue the message.
   // pauseFor() stops the spinner briefly so the user can see the confirmation,
   // then resumes — prevents spinner from overwriting their typed text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0agent",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "description": "A persistent, learning AI agent that runs on your machine. An agent that learns.",
   "private": false,
   "license": "Apache-2.0",