@praveencs/agent 0.8.0 → 0.8.1

package/docs/articles/01-vision-architecture.md

@@ -7,8 +7,9 @@ This is the promise of **Autonomous Agents**. Unlike chatbots, agents have:
 2.  **Memory** (persistence across sessions)
 3.  **Skills** (integrations with real-world tools)
 4.  **Autonomy** (looping execution without constant prompts)
+5.  **Extensibility** (plugins, hooks, and commands to grow capabilities)
 
-In this 5-part series, we will break down exactly how we built `@praveencs/agent`, a powerful, open-source autonomous agent runtime.
+In this 7-part series, we will break down exactly how we built `@praveencs/agent`, a powerful, open-source autonomous agent runtime.
 
 ## 🏗️ The Core Architecture
 
@@ -33,6 +34,16 @@ A developer who forgets the codebase every morning is useless. Our agent needs *
 The secret sauce is the loop. A chatbot waits for input. An agent runs in a loop.
 - **Role**: A background process that constantly checks for pending tasks, file changes, or new goals.
 
+### 5. The Nervous System (Hooks & Plugins)
+As of **v0.8.0**, our agent has a full extensibility layer:
+- **Lifecycle Hooks**: Intercept execution at any point (`before:tool`, `after:plan`, etc.).
+- **Lightweight Commands**: Markdown-based goal templates—no code needed.
+- **Plugin System**: Install community bundles that add skills, commands, and hooks.
+- **Multi-CLI Tools**: Delegate tasks to Cursor, Codex, Gemini, or Claude CLIs.
+
+### 6. The Voice (Interactive CLI)
+The agent now has a **conversational interface**. Type `agent` with no arguments to enter an interactive REPL with slash commands, tab completion, and multi-turn context.
+
 ## 🛠️ Tech Stack
 
 We're building this in **TypeScript** (Node.js) because:
@@ -49,4 +60,13 @@ We're building this in **TypeScript** (Node.js) because:
 
 In **Part 2**, we will dive into the code for **The Brain**. We'll write the `GoalDecomposer` class that turns vague requests into structured project plans.
 
+### 📚 Full Series
+1. **Architecture & Vision** (This Article)
+2. **The Brain (Goal Decomposition)**
+3. **The Body (Skill Execution)**
+4. **The Memory (Persistence)**
+5. **Self-Improvement (Auto-Fixer)**
+6. **Plugin Ecosystem (Hooks, Commands, Multi-CLI)**
+7. **Interactive CLI**
+
 Stay tuned!

package/docs/articles/05-self-improvement.md

@@ -66,15 +66,12 @@ The LLM reads the errors ("not a git repository") and decides to add a check:
 ### 3. Apply & Reload
 The agent overwrites `prompt.md` with the new version and reloads the skill instantly. The next execution uses the fixed logic.
 
-## 🚀 Conclusion
+## 🚀 But Wait, There's More
 
-We have built a system that:
-1.  **Decomposes** vague goals into tasks.
-2.  **Executes** tasks using defined skills.
-3.  **Remembers** context and learnings.
-4.  **Monitors** itself and **Fixes** its own tools.
+In **v0.8.0**, we took everything further. The agent is now extensible and conversational.
 
-This loop—Plan, Do, Check, Act—is the foundation of autonomy.
+In **Part 6**, we'll cover the **Plugin Ecosystem**—hooks that intercept execution, lightweight commands, and multi-CLI orchestration.
+In **Part 7**, we'll build the **Interactive CLI**—a Claude Code-style conversational experience.
 
 ### 📚 Series Recap
 
@@ -83,6 +80,8 @@ This loop—Plan, Do, Check, Act—is the foundation of autonomy.
 - **Part 3**: The Body (Skill Execution)
 - **Part 4**: The Memory (Persistence)
 - **Part 5**: Self-Improvement (Auto-Fixer)
+- **Part 6**: Plugin Ecosystem (Hooks, Commands, Multi-CLI)
+- **Part 7**: Interactive CLI
 
 You can explore the full source code and contribute at [GitHub](https://github.com/praveencs87/agent).
 

package/docs/articles/06-plugin-ecosystem.md

@@ -0,0 +1,195 @@
+# The Plugin Ecosystem: Hooks, Commands & Extensibility (Part 6)
+
+In **Parts 1-5**, we built an agent with a brain, body, memory, and self-healing. But it was a closed system.
+
+In **v0.8.0**, we opened it up. Now anyone can extend the agent with **Plugins**, **Hooks**, and **Commands**—without touching core code.
+
+## 🪝 Lifecycle Hooks
+
+Hooks let you inject custom logic at every execution point. Think of them as Git hooks, but for your agent.
+
+### The Events
+
+| Event | When it fires |
+|-------|--------------|
+| `before:tool` | Before any tool executes |
+| `after:tool` | After any tool completes |
+| `before:plan` | Before a plan starts |
+| `after:step` | After each plan step |
+| `after:plan` | After a plan finishes |
+| `before:skill` / `after:skill` | Around skill execution |
+| `after:decompose` | After goal decomposition |
+| `session:start` / `session:end` | At session boundaries |
+
+### Example: Auto-Format on Write
+
+Create `.agent/hooks/hooks.json`:
+```json
+{
+  "hooks": {
+    "after:tool": [
+      {
+        "match": "fs.write",
+        "command": "npx prettier --write {{path}}",
+        "blocking": false
+      }
+    ],
+    "before:plan": [
+      {
+        "command": "./scripts/validate-env.sh",
+        "blocking": true
+      }
+    ]
+  }
+}
+```
+
+Every time the agent writes a file, Prettier auto-formats it. Before every plan runs, your environment is validated.
+
+### Template Variables
+
+Hook commands support `{{name}}`, `{{event}}`, `{{cwd}}`, `{{path}}`, and `{{runId}}` placeholders. Environment variables like `AGENT_HOOK_EVENT` are also injected.
+
+### CLI
+
+```bash
+agent hooks list              # Show all registered hooks
+agent hooks add after:tool "npx prettier --write {{path}}" --match fs.write
+agent hooks events            # Reference for all available events
+```
+
+---
+
+## ⚡ Lightweight Commands
+
+Skills require a `skill.json`, an entrypoint, and permission declarations. But sometimes you just want a quick recipe.
+
+**Commands** are markdown files with YAML frontmatter. No boilerplate.
+
+### Example: `deploy-staging.md`
+
+Create `.agent/commands/deploy-staging.md`:
+```markdown
+---
+name: deploy-staging
+description: Deploy current branch to staging
+tools: [cmd.run, git.status, git.diff]
+---
+# Deploy to Staging
+
+You are deploying the current branch to staging.
+
+Steps:
+1. Run `npm test` to verify all tests pass
+2. Run `npm run build` to create the production bundle
+3. Run `git push origin HEAD:staging` to trigger deployment
+4. Verify the deployment succeeded
+```
+
+### How It Works
+
+When you run `agent run deploy-staging` or type `/deploy-staging` in interactive mode:
+1. The runtime checks: Is there a **Skill** named `deploy-staging`? → No.
+2. Is there a **Command** named `deploy-staging`? → **Yes!**
+3. The command's markdown body becomes the LLM system prompt.
+4. Only the whitelisted tools (`cmd.run`, `git.status`, `git.diff`) are available.
+
+This gives you **scoped, repeatable tasks without any code**.
+
+### CLI
+
+```bash
+agent commands list           # Show all available commands
+agent run deploy-staging      # Run a command
+agent run /deploy-staging     # Explicit slash-command syntax
+```
+
+---
+
+## 🔧 Multi-CLI Orchestration
+
+Sometimes, the best tool for a job isn't our agent—it's Cursor, Codex, or Claude CLI.
+
+In v0.8.0, we added **first-class AI CLI wrappers** as tools. The LLM orchestrator can delegate sub-tasks to specialized CLIs:
+
+| Tool | Wraps | Best For |
+|------|-------|----------|
+| `cli.cursor` | Cursor CLI | Multi-file refactoring with codebase context |
+| `cli.codex` | OpenAI Codex | Code generation with sandbox execution |
+| `cli.gemini` | Gemini CLI | Large-context analysis and reasoning |
+| `cli.claude` | Claude CLI | Careful code review and generation |
+
+### How It Works
+
+These are standard `ToolDefinition` registrations—the LLM sees them alongside `fs.read`, `cmd.run`, and `git.diff`. When the task requires deep codebase understanding or parallel execution, the LLM can choose:
+
+```
+User: "Refactor the auth module to use JWT"
+Agent LLM: "This needs multi-file refactoring with deep context."
+→ Calls cli.cursor({ prompt: "Refactor auth to JWT...", files: ["src/auth/**"] })
+→ Cursor CLI executes with native codebase indexing
+→ Result returned to our agent for verification
+```
+
+Configure availability in `agent.config.json`:
+```json
+{
+  "cliTools": {
+    "cursor": { "binary": "cursor", "available": true },
+    "claude": { "binary": "claude", "available": true }
+  }
+}
+```
+
+---
+
+## 🔌 The Plugin System
+
+A **Plugin** bundles skills, commands, hooks, and tools into a single installable package.
+
+### Plugin Structure
+
+```
+my-plugin/
+├── .agent-plugin/
+│   └── plugin.json          # Manifest
+├── skills/
+│   └── security-scan/
+│       ├── skill.json
+│       └── prompt.md
+├── commands/
+│   └── audit.md
+└── hooks/
+    └── hooks.json
+```
+
+### Manifest (`plugin.json`)
+
+```json
+{
+  "name": "enterprise-security",
+  "version": "1.0.0",
+  "description": "Security scanning and compliance",
+  "skills": ["skills/"],
+  "commands": ["commands/"],
+  "hooks": "hooks/hooks.json"
+}
+```
+
+### CLI
+
+```bash
+agent plugins install ./my-plugin    # Install from local path
+agent plugins list                   # Show installed plugins
+agent plugins remove my-plugin      # Uninstall
+```
+
+When a plugin is installed, its skills, commands, and hooks are automatically loaded on every `agent` run.
+
+---
+
+## 🚀 What's Next?
+
+The plugin ecosystem opens the door to community contributions. Imagine installing `agent plugins install security-scanner` and instantly getting OWASP scanning as a hook on every build.
+
+In **Part 7**, we'll cover the new **Interactive CLI**—the Claude Code-style conversational experience.

package/docs/articles/07-interactive-cli.md

@@ -0,0 +1,172 @@
+# The Interactive CLI: A Claude Code-Style Experience (Part 7)
+
+In **Part 6**, we gave the agent extensibility. In **Part 7**, we give it a personality.
+
+Most CLI tools are fire-and-forget: you type a command, get output, done. But modern AI agents deserve a **conversational interface**—one where you stay in a flow, the agent remembers context, and you can guide it naturally.
+
+## 🤖 The REPL
+
+When you type `agent` with no subcommand, you enter **Interactive Mode**:
+
+```
+$ agent
+
+  ╭────────────────────────────────────────────────╮
+  │  🤖 Agent Runtime v0.8.0                       │
+  │    Project: my-app                              │
+  │    Model: gpt-4o │ 3 skills │ 2 commands        │
+  ╰────────────────────────────────────────────────╯
+
+  Type a goal, a /command, or /help for help.
+
+  > Add input validation to the signup form
+  ⠋ Thinking...
+  ⚡ fs.read(src/pages/signup.tsx) ✓
+  ⚡ fs.write(src/pages/signup.tsx) ✓
+  ⚡ cmd.run(npm test) ✓
+
+  Added Zod validation schema for email and password fields.
+  Tests pass.
+
+  ────────────────────────────────────────────────────────
+  ✓ Done (8.2s)
+
+  > Now add rate limiting to the API endpoint
+  ⠋ Thinking...
+```
+
+Notice the second prompt: **the agent remembers** the first task. It knows you're working on the signup form and can connect the two requests.
+
+## 🔑 Key Features
+
+### 1. Multi-Turn Conversation
+
+Unlike `agent run "do X"` (which is one-shot), the REPL maintains conversation history across turns. The `ConversationManager` (`src/cli/conversation.ts`) tracks all messages:
+
+```typescript
+conversation.addUser("Add validation");
+// → LLM sees full history including previous turns
+const messages = conversation.getMessages();
+```
+
+When context gets too long, use `/compact` to summarize and trim:
+```
+  > /compact
+  Conversation compacted. Context freed.
+```
+
+### 2. Slash Commands
+
+Type `/` to access built-in commands:
+
+| Command | What it does |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/skills` | List installed skills with status |
+| `/commands` | List available lightweight commands |
+| `/hooks` | Show registered lifecycle hooks |
+| `/model` | Display current model and providers |
+| `/compact` | Summarize and trim conversation context |
+| `/clear` | Clear the terminal screen |
+| `/exit` | Exit interactive mode |
+
+Your custom `.agent/commands/*.md` files are also available as slash commands! If you have `deploy-staging.md`, you can type `/deploy-staging`.
+
+### 3. Tab Completion
+
+Press `Tab` after `/` to see all available slash commands. The REPL uses readline's `completer` for instant autocompletion:
+
+```
+  > /sk<TAB>
+  > /skills
+```
+
+### 4. Inline Tool Execution
+
+When the agent calls tools, you see them in real-time with status badges:
+
+```
+  ⚡ fs.read(src/auth/handler.ts) ✓         # Success
+  ⚡ cmd.run(npm test) ✗ Test failed        # Failure with reason
+  ⚡ cli.cursor(refactor auth...) ✓          # Delegated to external CLI
+```
+
+### 5. Rich Welcome Banner
+
+The bordered banner shows at-a-glance info:
+- Current project name (from `package.json`)
+- Active LLM model
+- Number of loaded skills and commands
+
+## 🏗️ Architecture
+
+```
+bin/agent.ts
+  └── No subcommand?
+      └── startREPL() ← src/cli/repl.ts
+          ├── Bootstrap (config, tools, skills, commands, hooks)
+          ├── renderBanner()
+          └── readline loop
+              ├── /slash-command → SlashCommandRegistry
+              ├── /user-command → CommandLoader → LLM loop (scoped tools)
+              └── natural language → ConversationManager → LLM loop (all tools)
+```
+
+All existing subcommands (`agent run`, `agent plan`, `agent skills`) continue to work exactly as before. The REPL is an *additional* entry point, not a replacement.
+
+## 💻 Implementation Highlights
+
+### Spinner Integration
+
+We use `ora` for smooth loading states:
+```typescript
+const spinner = new Spinner();
+spinner.start('Thinking...');
+// ... LLM call ...
+spinner.stop();
+```
+
+### Tool Call Display
+
+The `renderToolCall` function shows tool execution inline:
+```typescript
+renderToolCall('fs.read', { path: 'src/app.ts' }, 'running');
+// Output: ⚡ fs.read({"path":"src/app.ts"})
+// Then on completion:
+renderToolCall('fs.read', args, 'success');
+// Output: ✓
+```
+
+### Backward Compatibility
+
+The entry point (`bin/agent.ts`) detects whether a subcommand was provided:
+```typescript
+const hasSubcommand = args.length > 0 && !args[0].startsWith('-');
+if (hasSubcommand) {
+    program.parse(process.argv);  // Traditional CLI
+} else {
+    startREPL();  // Interactive mode
+}
+```
+
+## 🚀 What's Next?
+
+The interactive CLI opens up new possibilities:
+- **Streaming responses** — Show LLM output character-by-character
+- **Checkpointing** — Rewind codebase to a previous state within a session
+- **Project Memory** — Automatic `.agent.md` files for project-specific context
+- **Multi-agent mode** — Spawn sub-agents for parallel tasks within the REPL
+
+---
+
+### 📚 Full Series
+
+1. **Architecture & Vision**
+2. **The Brain (Goal Decomposition)**
+3. **The Body (Skill Execution)**
+4. **The Memory (Persistence)**
+5. **Self-Improvement (Auto-Fixer)**
+6. **Plugin Ecosystem (Hooks, Commands, Multi-CLI)**
+7. **Interactive CLI (This Article)**
+
+Explore the source code at [GitHub](https://github.com/praveencs87/agent) or install with `npm i -g @praveencs/agent`.

package/docs/comparisons/openclaw.md

@@ -1,21 +1,23 @@
 # Comparison: @praveencs/agent vs OpenClaw
 
-This document compares `@praveencs/agent` (this project) with [OpenClaw](https://github.com/openclaw/openclaw), a popular open-source AI operating system.
+This document compares `@praveencs/agent` v0.8.0 (this project) with [OpenClaw](https://github.com/openclaw/openclaw), a popular open-source AI operating system.
 
 ## 1. Core Philosophy
 
 | Feature | @praveencs/agent | OpenClaw |
 |---|---|---|
 | **Primary Goal** | **Autonomous Task Execution.** Designed to be a headless "digital employee" that plans and builds software in the background. | **AI Operating System.** Designed to be a "24/7 Jarvis" that integrates with chat apps (Discord, Telegram) and manages your digital life. |
-| **Interaction** | **CLI-First.** You give it a goal, and it works silently. | **Chat-First.** You talk to it via various messaging platforms. |
+| **Interaction** | **CLI-First + Interactive REPL.** Subcommands for automation, plus a conversational mode with slash commands. | **Chat-First.** You talk to it via various messaging platforms. |
 | **Persona** | A Junior Developer / Project Manager. | A Personal Assistant / OS Interface. |
 
 ## 2. Architecture
 
 ### @praveencs/agent
 - **Monolithic CLI/Daemon**: A single TypeScript application that runs locally.
+- **Interactive REPL**: Conversational mode with multi-turn context (v0.8.0).
 - **Daemon Loop**: A background process that polls a queue of tasks.
 - **Planner-Executor Split**: Explicit "Brain" (Goal Decomposition) and "Body" (Task Execution) separation.
+- **Plugin System**: Extensible via hooks, commands, and plugin bundles (v0.8.0).
 - **Database**: Uses `better-sqlite3` for high-performance, structured local storage.
 
 ### OpenClaw
@@ -27,11 +29,22 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 
 | | @praveencs/agent | OpenClaw |
 |---|---|---|
-| **Skill Definition** | **Prompt-as-Code.** Skills are simple `.md` files with natural language instructions. | **Plugin System.** Code-based plugins to extend functionality. |
-| **Execution** | **Shell-Native.** Executes command-line tools natively (git, docker, npm). | **Sandbox-Native.** Heavily focuses on browser automation and secure sandboxing. |
+| **Skill Definition** | **Prompt-as-Code.** Skills are `.md` files + Commands are lightweight goal templates. | **Plugin System.** Code-based plugins to extend functionality. |
+| **Execution** | **Shell-Native + Multi-CLI.** Executes command-line tools natively AND delegates to Cursor/Codex/Gemini/Claude CLIs. | **Sandbox-Native.** Heavily focuses on browser automation and secure sandboxing. |
+| **Extensibility** | **Hooks + Plugins.** Lifecycle hooks at every execution point, distributable plugin bundles. | **Plugin-based.** Extends via code plugins. |
 | **Self-Improvement** | **Built-in Auto-Fixer.** Monitors success rates and rewrites broken skills automatically. | **Manual/Plugin.** Relies on users or plugin updates. |
 
-## 4. Memory Implementation
+## 4. CLI Experience
+
+| | @praveencs/agent v0.8.0 | OpenClaw |
+|---|---|---|
+| **Interactive Mode** | ✅ Conversational REPL with multi-turn context | ❌ Chat-app dependent |
+| **Slash Commands** | ✅ `/help`, `/skills`, `/commands`, `/hooks`, `/model`, custom user commands | N/A |
+| **Tab Completion** | ✅ Built-in autocomplete | N/A |
+| **Lifecycle Hooks** | ✅ 10 event types with template variables | ❌ |
+| **Multi-CLI Orchestration** | ✅ Cursor, Codex, Gemini, Claude wrappers | ❌ |
+
+## 5. Memory Implementation
 
 ### @praveencs/agent
 - **Hybrid Storage**: Uses **SQLite** for structured data (tasks, metrics) and **Vector/FTS5** layers for semantic search.
@@ -41,11 +54,13 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 - **File-System Storage**: Stores conversations and memories as Markdown files.
 - **Why?**: "Unix philosophy" - easy to read/edit by humans, no database dependencies.
 
-## 5. Use Case Recommendation
+## 6. Use Case Recommendation
 
 **Choose @praveencs/agent if:**
 - You want an AI to **write code, manage servers, or automate dev workflows**.
-- You prefer a command-line interface.
+- You want an **interactive conversational CLI** experience.
+- You need a **plugin ecosystem** to extend capabilities.
+- You want to **orchestrate multiple AI CLIs** (Cursor, Claude, etc.).
 - You need structured planning and long-term project management.
 - You want a system that improves itself over time.
 
@@ -57,4 +72,4 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 
 ## Summary
 
-While OpenClaw builds a bridge between AI and *Communication Channels*, `@praveencs/agent` builds a bridge between AI and *Work Execution*. We are focused on the "Agent as a Worker" paradigm, whereas OpenClaw focuses on "Agent as an Interface".
+While OpenClaw builds a bridge between AI and *Communication Channels*, `@praveencs/agent` builds a bridge between AI and *Work Execution*. With v0.8.0, we've added extensibility (plugins, hooks, commands) and a modern interactive CLI, making it the most developer-centric autonomous agent available.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@praveencs/agent",
-    "version": "0.8.0",
+    "version": "0.8.1",
     "files": [
         "dist",
         "bin",