The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add NanoClaw agent REPL — persistent session-aware CLI for ECC
andydiaz122853c64d7c1b2
diff --git a/commands/claw.md b/commands/claw.mdnew file mode 100644index 000000000..c07392d57--- /dev/null+++ b/commands/claw.md@@ -0,0 +1,79 @@+---+description: Start the NanoClaw agent REPL — a persistent, session-aware AI assistant powered by the claude CLI.+---++# Claw Command++Start an interactive AI agent session that persists conversation history to disk and optionally loads ECC skill context.++## Usage++```bash+node scripts/claw.js+```++Or via npm:++```bash+npm run claw+```++## Environment Variables++| Variable | Default | Description |+|----------|---------|-------------|+| `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |+| `CLAW_SKILLS` | *(empty)* | Comma-separated skill names to load as system context |++## REPL Commands++Inside the REPL, type these commands directly at the prompt:++```+/clear Clear current session history+/history Print full conversation history+/sessions List all saved sessions+/help Show available commands+exit Quit the REPL+```++## How It Works++1. Reads `CLAW_SESSION` env var to select a named session (default: `default`)+2. Loads conversation history from `~/.claude/claw/{session}.md`+3. Optionally loads ECC skill context from `CLAW_SKILLS` env var+4. Enters a blocking prompt loop — each user message is sent to `claude -p` with full history+5. Responses are appended to the session file for persistence across restarts++## Session Storage++Sessions are stored as Markdown files in `~/.claude/claw/`:++```+~/.claude/claw/default.md+~/.claude/claw/my-project.md+```++Each turn is formatted as:++```markdown+### [2025-01-15T10:30:00.000Z] User+What does this function do?+---+### [2025-01-15T10:30:05.000Z] Assistant+This function calculates...+---+```++## Examples++```bash+# Start default session+node scripts/claw.js++# Named session+CLAW_SESSION=my-project node scripts/claw.js++# With skill context+CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js+```diff --git a/package-lock.json b/package-lock.jsonindex db3ddf530..5b4ca4061 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,14 +1,25 @@{- "name": "everything-claude-code",+ "name": "ecc-universal",+ "version": "1.4.1","lockfileVersion": 3,"requires": true,"packages": {"": {+ "name": "ecc-universal",+ "version": "1.4.1",+ "hasInstallScript": true,+ "license": "MIT",+ "bin": {+ "ecc-install": "install.sh"+ },"devDependencies": {"@eslint/js": "^9.39.2","eslint": "^9.39.2","globals": "^17.1.0","markdownlint-cli": "^0.47.0"+ },+ "engines": {+ "node": ">=18"}},"node_modules/@eslint-community/eslint-utils": {diff --git a/package.json b/package.jsonindex 00940810e..e58f63e77 100644--- a/package.json+++ b/package.json@@ -61,6 +61,7 @@"scripts/ci/","scripts/hooks/","scripts/lib/",+ "scripts/claw.js","scripts/setup-package-manager.js","scripts/skill-create-output.js","skills/",@@ -75,6 +76,7 @@"scripts": {"postinstall": "echo '\\n ecc-universal installed!\\n Run: npx ecc-install typescript\\n Docs: https://github.com/affaan-m/everything-claude-code\\n'","lint": "eslint . && markdownlint '**/*.md' --ignore node_modules",+ "claw": "node scripts/claw.js","test": "node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node tests/run-all.js"},"devDependencies": {diff --git a/scripts/claw.js b/scripts/claw.jsnew file mode 100644index 000000000..aab9df496--- /dev/null+++ b/scripts/claw.js@@ -0,0 +1,264 @@+#!/usr/bin/env node+/**+ * NanoClaw — Barebones Agent REPL for Everything Claude Code+ *+ * A persistent, session-aware AI agent loop that delegates to `claude -p`.+ * Zero external dependencies. Markdown-as-database. Synchronous REPL.+ *+ * Usage:+ * node scripts/claw.js+ * CLAW_SESSION=my-project node scripts/claw.js+ * CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js+ */++'use strict';++const fs = require('fs');+const path = require('path');+const os = require('os');+const { spawnSync } = require('child_process');+const readline = require('readline');++// ─── Session name validation ────────────────────────────────────────────────++const SESSION_NAME_RE = /^[a-zA-Z0-9][-a-zA-Z0-9]*$/;++function isValidSessionName(name) {+ return typeof name === 'string' && name.length > 0 && SESSION_NAME_RE.test(name);+}++// ─── Storage Adapter (Markdown-as-Database) ─────────────────────────────────++function getClawDir() {+ return path.join(os.homedir(), '.claude', 'claw');+}++function getSessionPath(name) {+ return path.join(getClawDir(), name + '.md');+}++function listSessions(dir) {+ const clawDir = dir || getClawDir();+ if (!fs.existsSync(clawDir)) {+ return [];+ }+ return fs.readdirSync(clawDir)+ .filter(f => f.endsWith('.md'))+ .map(f => f.replace(/\.md$/, ''));+}++function loadHistory(filePath) {+ try {+ return fs.readFileSync(filePath, 'utf8');+ } catch (_err) {+ return '';+ }+}++function appendTurn(filePath, role, content, timestamp) {+ const ts = timestamp || new Date().toISOString();+ const entry = `### [${ts}] ${role}\n${content}\n---\n`;+ const dir = path.dirname(filePath);+ fs.mkdirSync(dir, { recursive: true });+ fs.appendFileSync(filePath, entry, 'utf8');+}++// ─── Context & Delegation Pipeline ──────────────────────────────────────────++function loadECCContext(skillList) {+ const raw = skillList !== undefined ? skillList : (process.env.CLAW_SKILLS || '');+ if (!raw.trim()) {+ return '';+ }++ const names = raw.split(',').map(s => s.trim()).filter(Boolean);+ const chunks = [];++ for (const name of names) {+ const skillPath = path.join(process.cwd(), 'skills', name, 'SKILL.md');+ try {+ const content = fs.readFileSync(skillPath, 'utf8');+ chunks.push(content);+ } catch (_err) {+ // Gracefully skip missing skills+ }+ }++ return chunks.join('\n\n');+}++function buildPrompt(systemPrompt, history, userMessage) {+ const parts = [];+ if (systemPrompt) {+ parts.push('=== SYSTEM CONTEXT ===\n' + systemPrompt + '\n');+ }+ if (history) {+ parts.push('=== CONVERSATION HISTORY ===\n' + history + '\n');+ }+ parts.push('=== USER MESSAGE ===\n' + userMessage);+ return parts.join('\n');+}++function askClaude(systemPrompt, history, userMessage) {+ const fullPrompt = buildPrompt(systemPrompt, history, userMessage);++ const result = spawnSync('claude', ['-p', fullPrompt], {+ encoding: 'utf8',+ stdio: ['pipe', 'pipe', 'pipe'],+ env: { ...process.env, CLAUDECODE: '' },+ timeout: 300000 // 5 minute timeout+ });++ if (result.error) {+ return '[Error: ' + result.error.message + ']';+ }++ if (result.status !== 0 && result.stderr) {+ return '[Error: claude exited with code ' + result.status + ': ' + result.stderr.trim() + ']';+ }++ return (result.stdout || '').trim();+}++// ─── REPL Commands ──────────────────────────────────────────────────────────++function handleClear(sessionPath) {+ fs.mkdirSync(path.dirname(sessionPath), { recursive: true });+ fs.writeFileSync(sessionPath, '', 'utf8');+ console.log('Session cleared.');+}++function handleHistory(sessionPath) {+ const history = loadHistory(sessionPath);+ if (!history) {+ console.log('(no history)');+ } else {+ console.log(history);+ }+}++function handleSessions(dir) {+ const sessions = listSessions(dir);+ if (sessions.length === 0) {+ console.log('(no sessions)');+ } else {+ console.log('Sessions:');+ for (const s of sessions) {+ console.log(' - ' + s);+ }+ }+}++function handleHelp() {+ console.log('NanoClaw REPL Commands:');+ console.log(' /clear Clear current session history');+ console.log(' /history Print full conversation history');+ console.log(' /sessions List all saved sessions');+ console.log(' /help Show this help message');+ console.log(' exit Quit the REPL');+}++// ─── Main REPL ──────────────────────────────────────────────────────────────++function main() {+ const sessionName = process.env.CLAW_SESSION || 'default';++ if (!isValidSessionName(sessionName)) {+ console.error('Error: Invalid session name "' + sessionName + '". Use alphanumeric characters and hyphens only.');+ process.exit(1);+ }++ const clawDir = getClawDir();+ fs.mkdirSync(clawDir, { recursive: true });++ const sessionPath = getSessionPath(sessionName);+ const eccContext = loadECCContext();++ const skillCount = (process.env.CLAW_SKILLS || '').split(',').filter(s => s.trim()).length;++ console.log('NanoClaw v1.0 — Session: ' + sessionName);+ if (skillCount > 0) {+ console.log('Loaded ' + skillCount + ' skill(s) as context.');+ }+ console.log('Type /help for commands, exit to quit.\n');++ const rl = readline.createInterface({+ input: process.stdin,+ output: process.stdout+ });++ const prompt = () => {+ rl.question('claw> ', (input) => {+ const line = input.trim();++ if (!line) {+ prompt();+ return;+ }++ if (line === 'exit') {+ console.log('Goodbye.');+ rl.close();+ return;+ }++ if (line === '/clear') {+ handleClear(sessionPath);+ prompt();+ return;+ }++ if (line === '/history') {+ handleHistory(sessionPath);+ prompt();+ return;+ }++ if (line === '/sessions') {+ handleSessions();+ prompt();+ return;+ }++ if (line === '/help') {+ handleHelp();+ prompt();+ return;+ }++ // Regular message — send to Claude+ appendTurn(sessionPath, 'User', line);+ const history = loadHistory(sessionPath);+ const response = askClaude(eccContext, history, line);+ console.log('\n' + response + '\n');+ appendTurn(sessionPath, 'Assistant', response);++ prompt();+ });+ };++ prompt();+}++// ─── Exports & CLI Entry ────────────────────────────────────────────────────++module.exports = {+ getClawDir,+ getSessionPath,+ listSessions,+ loadHistory,+ appendTurn,+ loadECCContext,+ askClaude,+ buildPrompt,+ isValidSessionName,+ handleClear,+ handleHistory,+ handleSessions,+ handleHelp,+ main+};++if (require.main === module) {+ main();+}diff --git a/tests/run-all.js b/tests/run-all.jsindex b161ad4d2..e1d081449 100644--- a/tests/run-all.js+++ b/tests/run-all.js@@ -20,6 +20,7 @@ const testFiles = ['hooks/suggest-compact.test.js','integration/hooks.test.js','ci/validators.test.js',+ 'scripts/claw.test.js','scripts/setup-package-manager.test.js','scripts/skill-create-output.test.js'];diff --git a/tests/scripts/claw.test.js b/tests/scripts/claw.test.jsnew file mode 100644index 000000000..7695ad11c--- /dev/null+++ b/tests/scripts/claw.test.js@@ -0,0 +1,237 @@+/**+ * Tests for scripts/claw.js+ *+ * Tests the NanoClaw agent REPL module — storage, context, delegation, meta.+ *+ * Run with: node tests/scripts/claw.test.js+ */++const assert = require('assert');+const path = require('path');+const fs = require('fs');+const os = require('os');++const {+ getClawDir,+ getSessionPath,+ listSessions,+ loadHistory,+ appendTurn,+ loadECCContext,+ buildPrompt,+ askClaude,+ isValidSessionName,+ handleClear+} = require(path.join(__dirname, '..', '..', 'scripts', 'claw.js'));++// Test helper — matches ECC's custom test pattern+function test(name, fn) {+ try {+ fn();+ console.log(` \u2713 ${name}`);+ return true;+ } catch (err) {+ console.log(` \u2717 ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function makeTmpDir() {+ return fs.mkdtempSync(path.join(os.tmpdir(), 'claw-test-'));+}++function runTests() {+ console.log('\n=== Testing claw.js ===\n');++ let passed = 0;+ let failed = 0;++ // ── Storage tests (6) ──────────────────────────────────────────────────++ console.log('Storage:');++ if (test('getClawDir() returns path ending in .claude/claw', () => {+ const dir = getClawDir();+ assert.ok(dir.endsWith(path.join('.claude', 'claw')),+ `Expected path ending in .claude/claw, got: ${dir}`);+ })) passed++; else failed++;++ if (test('getSessionPath("foo") returns correct .md path', () => {+ const p = getSessionPath('foo');+ assert.ok(p.endsWith(path.join('.claude', 'claw', 'foo.md')),+ `Expected path ending in .claude/claw/foo.md, got: ${p}`);+ })) passed++; else failed++;++ if (test('listSessions() returns empty array for empty dir', () => {+ const tmpDir = makeTmpDir();+ try {+ const sessions = listSessions(tmpDir);+ assert.deepStrictEqual(sessions, []);+ } finally {+ fs.rmSync(tmpDir, { recursive: true, force: true });+ }+ })) passed++; else failed++;++ if (test('listSessions() finds .md files and strips extension', () => {+ const tmpDir = makeTmpDir();+ try {+ fs.writeFileSync(path.join(tmpDir, 'alpha.md'), 'test');+ fs.writeFileSync(path.join(tmpDir, 'beta.md'), 'test');+ fs.writeFileSync(path.join(tmpDir, 'not-a-session.txt'), 'test');+ const sessions = listSessions(tmpDir);+ assert.ok(sessions.includes('alpha'), 'Should find alpha');+ assert.ok(sessions.includes('beta'), 'Should find beta');+ assert.strictEqual(sessions.length, 2, 'Should only find .md files');+ } finally {+ fs.rmSync(tmpDir, { recursive: true, force: true });+ }+ })) passed++; else failed++;++ if (test('loadHistory() returns "" for non-existent file', () => {+ const result = loadHistory('/tmp/claw-test-nonexistent-' + Date.now() + '.md');+ assert.strictEqual(result, '');+ })) passed++; else failed++;++ if (test('appendTurn() writes correct markdown format', () => {+ const tmpDir = makeTmpDir();+ const filePath = path.join(tmpDir, 'test.md');+ try {+ appendTurn(filePath, 'User', 'Hello world', '2025-01-15T10:00:00.000Z');+ const content = fs.readFileSync(filePath, 'utf8');+ assert.ok(content.includes('### [2025-01-15T10:00:00.000Z] User'),+ 'Should include timestamp and role header');+ assert.ok(content.includes('Hello world'), 'Should include content');+ assert.ok(content.includes('---'), 'Should include separator');+ } finally {+ fs.rmSync(tmpDir, { recursive: true, force: true });+ }+ })) passed++; else failed++;++ // ── Context tests (3) ─────────────────────────────────────────────────++ console.log('\nContext:');++ if (test('loadECCContext() returns "" when no skills specified', () => {+ const result = loadECCContext('');+ assert.strictEqual(result, '');+ })) passed++; else failed++;++ if (test('loadECCContext() skips missing skill directories gracefully', () => {+ const result = loadECCContext('nonexistent-skill-xyz');+ assert.strictEqual(result, '');+ })) passed++; else failed++;++ if (test('loadECCContext() concatenates multiple skill files', () => {+ // Use real skills from the ECC repo if they exist+ const skillsDir = path.join(process.cwd(), 'skills');+ if (!fs.existsSync(skillsDir)) {+ console.log(' (skipped — no skills/ directory in CWD)');+ return;+ }+ const available = fs.readdirSync(skillsDir).filter(d => {+ const skillFile = path.join(skillsDir, d, 'SKILL.md');+ return fs.existsSync(skillFile);+ });+ if (available.length < 2) {+ console.log(' (skipped — need 2+ skills with SKILL.md)');+ return;+ }+ const twoSkills = available.slice(0, 2).join(',');+ const result = loadECCContext(twoSkills);+ assert.ok(result.length > 0, 'Should return non-empty context');+ // Should contain content from both skills+ for (const name of available.slice(0, 2)) {+ const skillContent = fs.readFileSync(+ path.join(skillsDir, name, 'SKILL.md'), 'utf8'+ );+ // Check that at least part of each skill is present+ const firstLine = skillContent.split('\n').find(l => l.trim().length > 10);+ if (firstLine) {+ assert.ok(result.includes(firstLine.trim()),+ `Should include content from skill ${name}`);+ }+ }+ })) passed++; else failed++;++ // ── Delegation tests (2) ──────────────────────────────────────────────++ console.log('\nDelegation:');++ if (test('buildPrompt() constructs correct prompt structure', () => {+ const prompt = buildPrompt('system info', 'chat history', 'user question');+ assert.ok(prompt.includes('=== SYSTEM CONTEXT ==='), 'Should have system section');+ assert.ok(prompt.includes('system info'), 'Should include system prompt');+ assert.ok(prompt.includes('=== CONVERSATION HISTORY ==='), 'Should have history section');+ assert.ok(prompt.includes('chat history'), 'Should include history');+ assert.ok(prompt.includes('=== USER MESSAGE ==='), 'Should have user section');+ assert.ok(prompt.includes('user question'), 'Should include user message');+ // Sections should be in order+ const sysIdx = prompt.indexOf('SYSTEM CONTEXT');+ const histIdx = prompt.indexOf('CONVERSATION HISTORY');+ const userIdx = prompt.indexOf('USER MESSAGE');+ assert.ok(sysIdx < histIdx, 'System should come before history');+ assert.ok(histIdx < userIdx, 'History should come before user message');+ })) passed++; else failed++;++ if (test('askClaude() handles subprocess error gracefully', () => {+ // Use a non-existent command to trigger an error+ const result = askClaude('sys', 'hist', 'msg');+ // Should return an error string, not throw+ assert.strictEqual(typeof result, 'string', 'Should return a string');+ // If claude is not installed, we get an error message+ // If claude IS installed, we get an actual response — both are valid+ assert.ok(result.length > 0, 'Should return non-empty result');+ })) passed++; else failed++;++ // ── REPL/Meta tests (3) ───────────────────────────────────────────────++ console.log('\nREPL/Meta:');++ if (test('module exports all required functions', () => {+ const claw = require(path.join(__dirname, '..', '..', 'scripts', 'claw.js'));+ const required = [+ 'getClawDir', 'getSessionPath', 'listSessions', 'loadHistory',+ 'appendTurn', 'loadECCContext', 'askClaude', 'main'+ ];+ for (const fn of required) {+ assert.strictEqual(typeof claw[fn], 'function',+ `Should export function ${fn}`);+ }+ })) passed++; else failed++;++ if (test('/clear truncates session file', () => {+ const tmpDir = makeTmpDir();+ const filePath = path.join(tmpDir, 'session.md');+ try {+ fs.writeFileSync(filePath, 'some existing history content');+ assert.ok(fs.readFileSync(filePath, 'utf8').length > 0, 'File should have content before clear');+ handleClear(filePath);+ const after = fs.readFileSync(filePath, 'utf8');+ assert.strictEqual(after, '', 'File should be empty after clear');+ } finally {+ fs.rmSync(tmpDir, { recursive: true, force: true });+ }+ })) passed++; else failed++;++ if (test('isValidSessionName rejects invalid characters', () => {+ assert.strictEqual(isValidSessionName('my-project'), true);+ assert.strictEqual(isValidSessionName('default'), true);+ assert.strictEqual(isValidSessionName('test123'), true);+ assert.strictEqual(isValidSessionName('a'), true);+ assert.strictEqual(isValidSessionName(''), false);+ assert.strictEqual(isValidSessionName('has spaces'), false);+ assert.strictEqual(isValidSessionName('has/slash'), false);+ assert.strictEqual(isValidSessionName('../traversal'), false);+ assert.strictEqual(isValidSessionName('-starts-dash'), false);+ assert.strictEqual(isValidSessionName(null), false);+ assert.strictEqual(isValidSessionName(undefined), false);+ })) passed++; else failed++;++ // ── Summary ───────────────────────────────────────────────────────────++ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+ process.exit(failed > 0 ? 1 : 0);+}++runTests();