@stan-chen/simple-cli 0.2.1

package/README.md

@@ -0,0 +1,287 @@
+# Simple-CLI ⚡
+
+> **The terminal-native AI coding assistant that shapes itself to your task.**
+
+[![npm version](https://img.shields.io/npm/v/@stan-chen/simple-cli)](https://www.npmjs.com/package/@stan-chen/simple-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Simple-CLI is a **lean, autonomous AI agent** that lives in your terminal. Unlike bloated IDEs, it's built for speed, horizontal scalability, and intelligent task execution.
+
+```bash
+# Interactive mode (chat loop)
+simple
+
+# One-shot execution
+simple "Add TypeScript to this project"
+
+# OpenClaw agent mode (auto-schedules background tasks)
+simple --claw "Delete trash emails every hour"
+```
+
+---
+
+## Why Simple-CLI?
+
+⚡ **Terminal-First** - No Electron, no overhead, pure speed  
+� **Autonomous Execution** - Multi-step reasoning with tool usage  
+🌊 **Swarm Mode** - Horizontally scale with distributed orchestration  
+🔌 **Multi-Provider** - OpenAI, Anthropic, LiteLLM - switch instantly  
+
+**Advanced (OpenClaw Integration):**  
+🧬 JIT Agent Generation - Task-specific personas via LLM  
+🧠 Autonomous Memory - Persistent context across sessions  
+👻 Ghost Mode - Background task scheduling  
+
+---
+
+## Instant Setup
+
+```bash
+# Install
+npm install -g @stan-chen/simple-cli
+
+# Configure
+export OPENAI_API_KEY="sk-..."
+
+# Start coding
+simple
+```
+
+**That's it.** It launches an interactive terminal session where you can:
+- Ask questions about your codebase
+- Request code changes
+- Run commands and see results
+- Let the agent iterate autonomously
+
+**Optional:** Use `simple --claw "intent"` for OpenClaw JIT mode.
+
+---
+
+## Three Ways to Use
+
+### 1. Interactive Mode
+```bash
+simple
+```
+Launch a chat session where you can ask questions, request changes, and see the agent iterate through multi-step tasks autonomously.
+
+### 2. One-Shot Execution
+```bash
+simple "Convert this Express app to Fastify"
+```
+Execute a single task and exit. Perfect for scripting or quick one-off commands.
+
+### 3. OpenClaw Agent Mode
+```bash
+simple --claw "Delete trash emails every hour"
+```
+Runs in OpenClaw-compatible environments with full access to skills, memory, and scheduling. The agent can:
+- Generate specialized personas (JIT)
+- Use OpenClaw skills from `skills/` directory
+- **Automatically schedule recurring tasks** (e.g., "every hour" → creates ghost task)
+- Persist memory across sessions
+
+When you use `--claw`, the agent intelligently determines if your task should run:
+- **Once** (immediate execution)
+- **Recurring** (auto-creates scheduled background task)
+
+---
+
+## Advanced: OpenClaw Integration
+
+Want specialized agents? Enable OpenClaw features with `--claw`.
+
+### 🎯 Task-Optimized Agents
+
+```bash
+simple --claw "Migrate Express to Fastify"
+```
+
+This doesn't just "chat" - it **generates a specialized AI persona** via LLM:
+- Expert migration strategist
+- Framework-specific constraints
+- Best practices for the exact task
+
+Then you work with *that* agent, not a generic assistant.
+
+### 🧠 Persistent Memory
+
+Your agent builds knowledge over time:
+```
+.simple/workdir/memory/
+├── notes/        # Session summaries
+├── reflections/  # What it learned
+├── logs/         # Full execution history
+└── graph/        # Knowledge connections
+```
+
+When you return, it **remembers**. Logs auto-prune and archive.
+
+### 👻 Background Execution
+
+```bash
+# Schedule a recurring security check
+npx tsx tools/claw.ts run clawGhost \
+  action=schedule \
+  intent="Scan for CVEs" \
+  cron="0 9 * * 1"  # Every Monday 9am
+```
+
+Uses **real OS schedulers** (Windows Task Scheduler / crontab) - not polling loops.
+
+### 🌊 Swarm for Scale
+
+```bash
+simple --swarm tasks.json --concurrency 5
+```
+
+Distribute tasks across isolated Git worktrees:
+- File-level locking
+- Conflict-free merges
+- Observable task queue
+- Works on local machines or CI/CD
+
+---
+
+## Core Features
+
+| Feature | Description |
+|---------|-------------|
+| **Multi-Provider** | OpenAI, Anthropic, LiteLLM - switch with `--moe` |
+| **MCP Integration** | Model Context Protocol for external data sources |
+| **Skills System** | Extensible via `SKILL.md` manifests |
+| **Git Worktree Isolation** | Swarm agents work in separate branches |
+| **Auto-Pruning Memory** | Keeps last 50 logs, archives the rest |
+| **YOLO Mode** | `--yolo` for unattended execution |
+
+---
+
+## Real-World Examples
+
+### Native Usage (Modes 1 & 2)
+
+```bash
+# Interactive exploration
+simple
+→ "What database does this app use?"
+→ "Add input validation to the user registration endpoint"
+
+# One-shot tasks
+simple "Add TypeScript strict mode and fix all errors"
+simple "Generate OpenAPI docs from my Express routes"
+simple "Refactor to use async/await instead of callbacks"
+```
+
+### OpenClaw Mode (Mode 3)
+
+```bash
+# Immediate execution with specialized agent
+simple --claw "Audit this React app for security vulnerabilities"
+simple --claw "Migrate from Vue 2 to Vue 3"
+
+# Auto-scheduled recurring tasks
+simple --claw "Check for npm vulnerabilities every day at 9am"
+simple --claw "Delete old log files every week"
+simple --claw "Run integration tests hourly"
+```
+
+When you provide time-based language ("every hour", "daily", etc.), the `--claw` mode **automatically:**
+1. Generates a specialized agent persona for the task
+2. Creates a scheduled background task (Ghost Mode)
+3. Registers it with your OS scheduler (crontab / Task Scheduler)
+
+---
+
+## Architecture
+
+**Zero Core Disruption** - Everything is modular:
+
+```
+simple-cli/
+├── src/          # Core agent logic
+├── tools/        # Discoverable tool primitives
+├── skills/       # OpenClaw-compatible skill packs
+│   ├── claw-jit/     # JIT persona generation
+│   ├── claw-brain/   # Memory management
+│   └── claw-ghost/   # Task scheduling
+└── .simple/      # Your workspace state
+    ├── AGENT.md      # Generated persona
+    └── workdir/      # Memory & artifacts
+```
+
+Built with the **Adapter Pattern** - add features without touching core.
+
+---
+
+## Advanced
+
+### Environment Variables
+```bash
+OPENAI_API_KEY=sk-...          # Primary LLM
+CLAW_MODEL=gpt-4               # Model selection
+LITELLM_BASE_URL=...           # Proxy support
+DEBUG=true                     # Verbose logging
+```
+
+### MOE (Mixture of Experts)
+```bash
+simple --moe  # Routes tasks to tier-appropriate models
+```
+
+### Swarm Configuration
+```json
+{
+  "tasks": [
+    {"file": "src/auth.ts", "instruction": "Add 2FA"},
+    {"file": "src/api.ts", "instruction": "Add rate limiting"}
+  ],
+  "concurrency": 3
+}
+```
+
+---
+
+## Documentation
+
+- 📖 [Full Docs](docs/index.md) - Architecture, workflows, customization
+- 🧬 [OpenClaw Integration](docs/claw-integration.md) - JIT, Memory, Ghost Mode
+- 🌊 [Swarm Guide](docs/swarm.md) - Distributed task orchestration
+- 🛠️ [Custom Skills](docs/custom-skills.md) - Build your own
+
+---
+
+## Contributing
+
+PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Core Principles:**
+- **No bloat** - Every feature must justify its existence
+- **Agent-first** - Tools serve the agent, not the UI
+- **Horizontal scale** - Features should work in swarm mode
+- **Zero lock-in** - Portable configs, standard formats
+
+---
+
+## License
+
+MIT © [Stan Chen](https://github.com/stancsz)
+
+---
+
+## Acknowledgments
+
+Built with inspiration from:
+- **Gemini CLI** - Multi-provider architecture
+- **OpenClaw** - Skill system design
+- **Cursor/Aider** - Agentic coding patterns
+
+Powered by:
+- [@clack/prompts](https://github.com/natemoo-re/clack) - Beautiful TUI
+- [LiteLLM](https://github.com/BerriAI/litellm) - Universal LLM proxy
+
+---
+
+<p align="center">
+  <strong>Stop configuring. Start building.</strong><br>
+  <code>simple "Your next big idea"</code>
+</p>

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Simple-CLI - Premium TUI agentic coding assistant
+ * Powered by @clack/prompts.
+ */
+import 'dotenv/config';

package/dist/cli.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * Simple-CLI - Premium TUI agentic coding assistant
+ * Powered by @clack/prompts.
+ */
+import 'dotenv/config';
+import { text, confirm as clackConfirm, isCancel, select } from '@clack/prompts';
+import pc from 'picocolors';
+import { getContextManager } from './context.js';
+import { createProvider } from './providers/index.js';
+import { createMultiProvider } from './providers/multi.js';
+import { routeTask, loadTierConfig } from './router.js';
+import { executeCommand } from './commands.js';
+import { getMCPManager } from './mcp/manager.js';
+import { listSkills, setActiveSkill, getActiveSkill } from './skills.js';
+import { statSync } from 'fs';
+import { resolve } from 'path';
+import { runSwarm, parseSwarmArgs, printSwarmHelp } from './commands/swarm.js';
+import { jsonrepair } from 'jsonrepair';
+// CLI flags
+const YOLO_MODE = process.argv.includes('--yolo');
+const MOE_MODE = process.argv.includes('--moe');
+const SWARM_MODE = process.argv.includes('--swarm');
+const CLAW_MODE = process.argv.includes('--claw') || process.argv.includes('-claw');
+const DEBUG = process.argv.includes('--debug') || process.env.DEBUG === 'true';
+const VERSION = '0.2.0';
+// Handle --claw mode (JIT Agent Generation)
+if (CLAW_MODE) {
+    const { execSync } = await import('child_process');
+    const args = process.argv.slice(2).filter(a => !a.startsWith('-'));
+    const intent = args.join(' ') || 'unspecified task';
+    console.log(pc.cyan('🧬 Initiating JIT Agent Generation...'));
+    console.log(pc.dim(`Intent: "${intent}"`));
+    try {
+        const output = execSync(`npx tsx tools/claw.ts run clawJit intent="${intent}"`, {
+            cwd: process.cwd(),
+            encoding: 'utf-8',
+            stdio: 'inherit'
+        });
+        console.log(pc.green('\n✅ JIT Agent ready. Run `simple` to begin.'));
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(pc.red('❌ Failed to initialize Claw mode:'), error);
+        process.exit(1);
+    }
+}
+// Handle --swarm mode
+if (SWARM_MODE) {
+    if (process.argv.includes('--help')) {
+        printSwarmHelp();
+        process.exit(0);
+    }
+    const swarmOptions = parseSwarmArgs(process.argv.slice(2));
+    swarmOptions.yolo = swarmOptions.yolo || YOLO_MODE;
+    runSwarm(swarmOptions).catch(err => {
+        console.error('Swarm error:', err);
+        process.exit(1);
+    });
+}
+else {
+    main().catch(console.error);
+}
+function parseResponse(response) {
+    const thought = response.match(/<thought>([\s\S]*?)<\/thought>/)?.[1]?.trim() || '';
+    const jsonMatch = response.match(/\{[\s\S]*"tool"[\s\S]*\}/);
+    let action = { tool: 'none', message: '', args: {} };
+    if (jsonMatch) {
+        try {
+            action = JSON.parse(jsonrepair(jsonMatch[0]));
+        }
+        catch { /* skip */ }
+    }
+    return { thought, action };
+}
+async function confirm(tool, args, ctx) {
+    if (YOLO_MODE)
+        return true;
+    const t = ctx.getTools().get(tool);
+    if (!t || t.permission === 'read')
+        return true;
+    const confirmed = await clackConfirm({
+        message: `Allow ${pc.cyan(tool)} with args ${pc.dim(JSON.stringify(args))}?`,
+        initialValue: true,
+    });
+    return !isCancel(confirmed) && confirmed;
+}
+async function executeTool(name, args, ctx) {
+    const tool = ctx.getTools().get(name);
+    if (!tool)
+        return `Error: Tool "${name}" not found`;
+    try {
+        const result = await tool.execute(args);
+        return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    }
+    catch (error) {
+        return `Error: ${error instanceof Error ? error.message : error}`;
+    }
+}
+async function main() {
+    console.clear();
+    const args = process.argv.slice(2).filter(arg => !arg.startsWith('-'));
+    let targetDir = process.cwd();
+    if (args.length > 0) {
+        try {
+            if (statSync(args[0]).isDirectory()) {
+                targetDir = resolve(args[0]);
+                process.chdir(targetDir);
+                // Reload .env from the new directory
+                const { config } = await import('dotenv');
+                config();
+                args.shift();
+            }
+        }
+        catch { /* ignored */ }
+    }
+    console.log(`\n ${pc.bgCyan(pc.black(' SIMPLE-CLI '))} ${pc.dim(`v${VERSION}`)} ${pc.green('●')} ${pc.cyan(targetDir)}\n`);
+    console.log(`${pc.dim('○')} Initializing...`);
+    const ctx = getContextManager(targetDir);
+    await ctx.initialize();
+    console.log(`${pc.green('●')} Ready.`);
+    const mcpManager = getMCPManager();
+    try {
+        const configs = await mcpManager.loadConfig();
+        if (configs.length > 0)
+            await mcpManager.connectAll(configs);
+    }
+    catch (error) {
+        if (DEBUG)
+            console.error('MCP init error:', error);
+    }
+    const tierConfigs = MOE_MODE ? loadTierConfig() : null;
+    const multiProvider = tierConfigs ? createMultiProvider(tierConfigs) : null;
+    const singleProvider = !MOE_MODE ? createProvider() : null;
+    const generate = async (input) => {
+        const history = ctx.getHistory();
+        const fullPrompt = await ctx.buildSystemPrompt();
+        if (MOE_MODE && multiProvider && tierConfigs) {
+            const routing = await routeTask(input, async (prompt) => {
+                return multiProvider.generateWithTier(1, prompt, [{ role: 'user', content: input }]);
+            });
+            if (DEBUG)
+                console.log(pc.dim(`[Routing] Tier: ${routing.tier}`));
+            return multiProvider.generateWithTier(routing.tier, fullPrompt, history.map(m => ({ role: m.role, content: m.content })));
+        }
+        return singleProvider.generateResponse(fullPrompt, history.map(m => ({ role: m.role, content: m.content })));
+    };
+    let isFirstPrompt = true;
+    while (true) {
+        const skill = getActiveSkill();
+        let input;
+        // Support initial prompt from command line
+        if (isFirstPrompt && args.length > 0) {
+            input = args.join(' ');
+            console.log(`\n${pc.magenta('➤')} ${pc.bold(input)}`);
+        }
+        else {
+            input = await text({
+                message: pc.dim(`[@${skill.name}]`) + ' Chat with Simple-CLI',
+                placeholder: 'Ask anything or use /help',
+                validate(value) {
+                    if (value.trim().length === 0)
+                        return 'Input required';
+                }
+            });
+        }
+        isFirstPrompt = false;
+        if (isCancel(input)) {
+            console.log(`\n${pc.dim('—')} Goodbye!`);
+            mcpManager.disconnectAll();
+            process.exit(0);
+        }
+        const trimmedInput = input.trim();
+        // Slash command
+        if (trimmedInput.startsWith('/')) {
+            try {
+                await executeCommand(trimmedInput, {
+                    cwd: ctx.getCwd(),
+                    activeFiles: ctx.getState().activeFiles,
+                    readOnlyFiles: ctx.getState().readOnlyFiles,
+                    history: ctx.getHistory(),
+                    io: {
+                        output: (m) => console.log(`\n${pc.dim('○')} ${m}`),
+                        error: (m) => console.log(`\n${pc.red('✖')} ${m}`),
+                        confirm: async (m) => {
+                            const c = await clackConfirm({ message: m });
+                            return !isCancel(c) && c;
+                        },
+                        prompt: async (m) => {
+                            const p = await text({ message: m });
+                            return isCancel(p) ? '' : p;
+                        }
+                    }
+                });
+            }
+            catch (err) {
+                console.log(`\n${pc.red('✖')} ${pc.red(String(err))}`);
+            }
+            continue;
+        }
+        // Skill switching
+        if (trimmedInput.startsWith('@')) {
+            const skillName = trimmedInput.slice(1).trim();
+            if (skillName === 'list') {
+                const skills = listSkills();
+                const selected = await select({
+                    message: 'Select a skill',
+                    options: skills.map(s => ({ label: `@${s.name} - ${s.description}`, value: s.name }))
+                });
+                if (!isCancel(selected)) {
+                    const newSkill = setActiveSkill(selected);
+                    if (newSkill)
+                        ctx.setSkill(newSkill);
+                }
+            }
+            else {
+                const newSkill = setActiveSkill(skillName);
+                if (newSkill) {
+                    ctx.setSkill(newSkill);
+                    console.log(`\n${pc.cyan('★')} Switched to @${newSkill.name}`);
+                }
+                else {
+                    console.log(`\n${pc.red('✖')} Skill @${skillName} not found.`);
+                }
+            }
+            continue;
+        }
+        ctx.addMessage('user', trimmedInput);
+        let steps = 0;
+        while (steps < 15) {
+            const response = await generate(trimmedInput);
+            const { thought, action } = parseResponse(response);
+            if (thought)
+                console.log(`\n${pc.dim('💭')} ${pc.cyan(thought)}`);
+            if (action.tool !== 'none') {
+                if (await confirm(action.tool, action.args || {}, ctx)) {
+                    console.log(`${pc.yellow('⚙')} ${pc.dim(`Executing ${action.tool}...`)}`);
+                    const result = await executeTool(action.tool, action.args || {}, ctx);
+                    console.log(`${pc.green('✔')} ${pc.dim(result.length > 500 ? result.slice(0, 500) + '...' : result)}`);
+                    ctx.addMessage('assistant', response);
+                    ctx.addMessage('user', `Tool result: ${result}`);
+                    steps++;
+                }
+                else {
+                    console.log(`${pc.yellow('⚠')} Skipped.`);
+                    ctx.addMessage('assistant', response);
+                    break;
+                }
+            }
+            else {
+                const msg = action.message || response.replace(/<thought>[\s\S]*?<\/thought>/, '').trim();
+                if (msg)
+                    console.log(`\n${pc.magenta('✦')} ${msg}`);
+                ctx.addMessage('assistant', response);
+                break;
+            }
+        }
+    }
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class Add extends Command {
+    static description: string;
+    static args: {
+        files: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/add.js

@@ -0,0 +1,50 @@
+import { Command, Args } from '@oclif/core';
+import * as ui from '../lib/ui.js';
+import { getContextManager } from '../context.js';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+export default class Add extends Command {
+    static description = 'Add files to the chat context';
+    static args = {
+        files: Args.string({
+            description: 'Files to add (supports glob patterns)',
+            required: true,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> add src/index.ts',
+        '<%= config.bin %> add "src/**/*.ts"',
+        '<%= config.bin %> add package.json tsconfig.json',
+    ];
+    async run() {
+        const { args, argv } = await this.parse(Add);
+        const ctx = getContextManager();
+        // Handle multiple files from argv
+        const files = argv;
+        let added = 0;
+        for (const file of files) {
+            const fullPath = resolve(process.cwd(), file);
+            if (file.includes('*')) {
+                // Handle glob pattern
+                const { execute } = await import('../tools/glob.js');
+                const result = await execute({ pattern: file, cwd: process.cwd(), maxResults: 1000, includeDirectories: false });
+                for (const match of result.matches) {
+                    if (ctx.addFile(match)) {
+                        ui.success(`Added ${match}`);
+                        added++;
+                    }
+                }
+            }
+            else if (existsSync(fullPath)) {
+                if (ctx.addFile(file)) {
+                    ui.success(`Added ${file}`);
+                    added++;
+                }
+            }
+            else {
+                ui.error(`File not found: ${file}`);
+            }
+        }
+        ui.log(`Added ${added} file(s) to context`);
+    }
+}

package/dist/commands/git/commit.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+import 'dotenv/config';
+export default class GitCommit extends Command {
+    static description: string;
+    static flags: {
+        message: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        ai: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}