@mndrk/agx 1.4.4 → 1.4.9

package/README.md

@@ -1,174 +1,184 @@
 # agx
 
-Unified AI Agent CLI with persistent memory. Wraps Claude, Gemini, and Ollama with automatic state management via [mem](https://github.com/ramarlina/memx).
+Task orchestrator for autonomous AI agents. Uses `mem` for persistent memory across sessions.
 
 ```bash
 npm install -g @mndrk/agx
 ```
 
-## Quick Start
-
-```bash
-# Simple prompt
-agx claude -p "explain this code"
+## Core Concept: Wake-Work-Sleep Cycle
 
-# Use default provider
-agx -p "what does this function do?"
+Agents have **no memory** between sessions. All continuity comes from `mem`:
 
-# With persistent memory (auto-detected)
-agx claude -p "continue working on the todo app"
-
-# Autonomous mode - creates task and works until done
-agx claude --autonomous -p "Build a todo app with React"
+```
+WAKE → Load state → WORK → Save state → SLEEP → repeat
 ```
 
-## Memory Integration
+This enables truly autonomous operation across multiple sessions.
 
-agx integrates with [mem](https://github.com/ramarlina/memx) for persistent state across sessions:
+## Quick Start
 
 ```bash
-# If ~/.mem has a task mapped to cwd, context is auto-loaded
-cd ~/Projects/my-app
-agx claude -p "continue"   # Knows where it left off
+# Create and run a task
+agx new "Build a REST API with auth"
+agx run build-rest-api
+
+# Or one command for full autonomous mode
+agx -a -p "Build a REST API with auth"
+# ✓ Created task: build-rest-api
+# ✓ Daemon started
+# ✓ Working...
+```
+
+## Task Management
 
-# Create task with explicit criteria
-agx claude --task todo-app \
-  --criteria "CRUD working" \
-  --criteria "Tests passing" \
-  --criteria "Deployed to Vercel" \
-  -p "Build a todo app"
+```bash
+agx new "<goal>"       # Create task
+agx run [task]         # Run task (loads context, wakes agent)
+agx tasks              # Interactive TUI - browse all tasks
+agx status             # Current task status
+agx context [task]     # View task context
+agx pause [task]       # Pause task
+agx remove [task]      # Delete task (alias: rm, delete)
+agx tail [task]        # Live tail logs
 ```
 
-## Output Markers
+### Interactive Tasks Browser
 
-Agents control state via markers in their output:
+`agx tasks` opens a TUI showing all tasks with status, progress, and last run time.
 
-```
-[checkpoint: Hero section complete]   # Save progress
-[learn: Tailwind is fast]             # Record learning
-[next: Add auth system]               # Set next step
-[criteria: 2]                         # Mark criterion #2 done
-[approve: Deploy to production?]      # Halt for approval
-[blocked: Need API key from client]   # Mark stuck
-[pause]                               # Stop, resume later
-[continue]                            # Keep going (daemon)
-[done]                                # Task complete
-[split: auth "Handle authentication"] # Create subtask
+Keys: `↑/↓` select, `enter` details, `r` run, `p` pause, `d` done, `x` remove
+
+## Steering: Nudge a Task
+
+Send guidance to an agent for its next wake cycle:
+
+```bash
+agx nudge <task> "focus on auth first"    # Add nudge
+agx nudge <task>                          # View pending nudges
 ```
 
-## Providers
+Nudges are shown to the agent on wake and then cleared.
 
-| Provider | Aliases | Description |
-|----------|---------|-------------|
-| claude | c, cl | Anthropic Claude Code |
-| gemini | g, gem | Google Gemini CLI |
-| ollama | o, ol | Local Ollama models |
+## Memory Commands (via mem)
 
-## Options
+Agents persist state using these commands:
 
+### Define Objective
+```bash
+mem goal "<objective>"        # Set/update goal
+mem criteria add "<text>"     # Add success criterion
+mem constraint add "<rule>"   # Add boundary/constraint
 ```
---prompt, -p <text>    Prompt to send
---model, -m <name>     Model name
---yolo, -y             Skip permission prompts
---print                Non-interactive output
---interactive, -i      Force interactive mode
---mem                  Enable mem integration (auto-detected)
---no-mem               Disable mem integration
---autonomous, -a       Create task and run autonomously (starts daemon)
---task <name>          Specific task name
---criteria <text>      Success criterion (repeatable)
+
+### Track Progress
+```bash
+mem next "<step>"             # Set what you're working on
+mem checkpoint "<msg>"        # Save progress point
+mem criteria <n>              # Mark criterion #n complete
+mem progress                  # Check progress %
+```
+
+### Learn & Adapt
+```bash
+mem learn "<insight>"         # Task-specific learning
+mem learn -g "<insight>"      # Global learning (all tasks)
+mem stuck "<reason>"          # Mark blocker
+mem stuck clear               # Clear blocker
 ```
 
-## Claude Code Plugin
+### Build Playbook
+```bash
+mem learnings -g              # List global learnings
+mem promote <n>               # Promote learning to playbook
+mem playbook                  # View global playbook
+```
 
-Install as a Claude Code plugin:
+### Query
+```bash
+mem context                   # Full context for agent
+mem history                   # Task progression
+mem query "<search>"          # Search all memory
+```
 
+### Complete
 ```bash
-claude plugin install github:ramarlina/agx
+mem done                      # Mark task complete
 ```
 
-This adds:
-- **Skill**: Claude learns how to spawn background agents
-- **Commands**: `/agx:spawn <goal>`, `/agx:continue`
+## Agent Workflow
 
-## Commands
+When an agent wakes, it should:
 
-```bash
-agx init               # Setup wizard
-agx config             # Configuration menu
-agx status             # Show current config
-agx skill              # View LLM skill
-agx skill install      # Install skill to Claude/Gemini
+1. **Orient** - Read state (goal, criteria, progress, next step, nudges)
+2. **Plan** - Define criteria if missing, set intent with `mem next`
+3. **Execute** - Work toward criteria, save learnings
+4. **Checkpoint** - Save progress with `mem checkpoint`
+5. **Adapt** - Handle blockers or ask user for nudge
+
+## Daemon Mode
+
+Run tasks automatically on a schedule:
 
-# Daemon management
+```bash
 agx daemon start       # Start background daemon
 agx daemon stop        # Stop daemon
 agx daemon status      # Check if running
-agx daemon logs        # Show recent logs
+agx daemon logs        # View logs
 ```
 
-## Autonomous Mode
+The daemon:
+- Polls continuously for active tasks
+- Runs up to 5 tasks in parallel
+- Logs to `~/.agx/logs/<taskname>.log`
+
+## One-Shot Mode
 
-Start a task that runs autonomously until complete:
+For quick questions without task creation:
 
 ```bash
-agx claude --autonomous -p "Build a React todo app with auth"
-# ✓ Created task: build-react-todo
-# ✓ Mapped: ~/Projects/app → task/build-react-todo
-# ✓ Daemon started (pid 12345)
-# ✓ Autonomous mode: daemon will continue work every 15m
+agx -p "explain this error"
+agx claude -p "refactor this function"
 ```
 
-The daemon:
-- Runs in background (survives terminal close)
-- Wakes every 15 minutes
-- Continues work on active tasks
-- Stops when task is `[done]` or `[blocked]`
-
-## Loop Control
-
-The agent controls execution flow via markers:
-
-- `[done]` → Task complete, exit
-- `[pause]` → Save state, exit (resume later with same command)
-- `[blocked: reason]` → Mark stuck, notify human, exit
-- `[continue]` → Keep going (daemon mode loops)
-- `[approve: question]` → Halt until human approves
+## Providers
 
-## Task Splitting
+| Provider | Alias | Description |
+|----------|-------|-------------|
+| claude | c | Anthropic Claude Code |
+| gemini | g | Google Gemini |
+| ollama | o | Local Ollama |
 
-Break large tasks into subtasks:
+## Key Flags
 
+```bash
+-a, --autonomous    # Full auto: create task + daemon + work until done
+-p, --prompt        # The prompt/goal
+-y, --yolo          # Skip confirmations
+--continue <task>   # Continue specific task
 ```
-Agent output:
-This is too big. Breaking it down.
 
-[split: setup "Project scaffolding"]
-[split: auth "Authentication system"]
-[split: crud "CRUD operations"]
-[next: Start with setup subtask]
-[pause]
-```
+## Key Principles
 
-agx creates subtask branches in ~/.mem linked to the parent.
+- **Memory is everything** - Agents forget between sessions. Save state.
+- **Criteria drive completion** - No criteria = no way to know when done.
+- **Checkpoint often** - Sessions can die anytime.
+- **Ask when stuck** - Get a nudge from the user vs. spinning.
+- **Learn & promote** - Build the playbook for future tasks.
 
-## Example: Full Workflow
+## Architecture
 
-```bash
-# Day 1: Start project
-mkdir ~/Projects/my-app && cd ~/Projects/my-app
-agx claude --auto-task -p "Build a React todo app with auth"
-
-# Agent works, outputs markers
-# [checkpoint: Scaffolded with Vite]
-# [learn: Vite is faster than CRA]
-# [next: Add todo list component]
-# [pause]
-
-# Day 2: Continue
-cd ~/Projects/my-app
-agx claude -p "continue"
-# Context auto-loaded, agent picks up where it left off
+```
+agx (agent execution)
+ ├── Uses mem CLI for all state operations
+ ├── Nudges via: mem set/get/pop
+ ├── Tasks via: mem tasks --json
+ └── Context via: mem context --json
+
+mem (storage layer)
+ ├── Git-backed state in ~/.mem
+ ├── Branch per task
+ └── KV primitives (set/get/pop)
 ```
 
 ## License