@swarmify/agents-cli 1.5.13 → 1.5.15

package/README.md

@@ -1,275 +1,155 @@
-# @swarmify/agents-cli
+# agents-cli
 
-Your virtual environment manager for AI coding agents.
-
-Homepage: https://swarmify.co/#agents-cli
-NPM: https://www.npmjs.com/package/@swarmify/agents-cli
-VS Code Extension: [Agents](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext) - full-screen agent terminals with sub-agent spawning
+**`systemctl` + `venv` for AI coding agents.** Manage, configure, schedule, and sandbox Claude, Codex, Gemini, Cursor, and OpenCode from a single CLI.
 
 ```bash
 npm install -g @swarmify/agents-cli
 ```
 
-## The Problem
-
-You spend hours configuring Claude Code: MCP servers, slash commands, hooks, skills. Then you switch to Codex or Gemini and start from scratch. Or you get a new machine and lose everything.
-
-## The Solution
-
-One command to configure all your agents.
+- **Configure** - Sync commands, MCP servers, hooks, and skills across all agents from one repo
+- **Schedule** - Run agents on cron schedules with a built-in daemon
+- **Sandbox** - Each job gets an isolated HOME overlay with whitelisted tools, dirs, and env vars
+- **Manage** - Install, upgrade, and monitor agent CLIs
 
 ```bash
-# New machine? One command.
-agents pull
-
-# See what's installed
-agents status
-```
-
-```
-Agent CLIs
-
-  Claude Code    2.0.65
-
-Installed Commands
-
-  Claude Code:
-    User: clean, debug, plan, recap, ship, spawn, test, verify
-    Project: eval
-
-Installed Skills
-
-  Claude Code:
-    User: remotion-best-practices, vercel-react-best-practices
-
-Installed MCP Servers
-
-  Claude Code:
-    User: Swarm@latest, GoDaddy
+agents pull            # Sync config to all agents
+agents jobs run my-job # Run an agent job now
+agents daemon start    # Start the job scheduler
+agents status          # See what's installed
 ```
 
-Your `.agents` repo becomes the source of truth for all your AI coding tools.
-
 ## What Gets Synced
 
-| Resource | Description | Agents |
-|----------|-------------|--------|
-| Slash commands | `/debug`, `/plan`, custom prompts | Claude, Codex, Gemini, Cursor, OpenCode |
-| MCP servers | Tools your agents can use | Claude, Codex, Gemini |
-| Hooks | Pre/post execution scripts | Claude, Gemini |
-| Skills | Reusable agent capabilities | Claude, Codex, Gemini |
-| CLI versions | Which version of each agent | All |
+| Resource | Agents |
+|----------|--------|
+| Slash commands | Claude, Codex, Gemini, Cursor, OpenCode |
+| MCP servers | Claude, Codex, Gemini |
+| Hooks | Claude, Gemini |
+| Skills | Claude, Codex, Gemini |
+| CLI versions | All |
 
 ## Quick Start
 
 ```bash
-# 1. Install
 npm install -g @swarmify/agents-cli
-
-# 2. Pull (auto-configures from default repo on first run)
-agents pull
-
-# 3. Check what's installed
-agents status
+agents pull       # Auto-configures from default repo on first run
+agents status     # See what got installed
 ```
 
-Pull a specific agent only:
+Use your own config repo:
 
 ```bash
-agents pull claude    # Only configure Claude Code
-agents pull codex     # Only configure Codex
-```
-
-## Using Your Own Config
-
-By default, `agents pull` uses the [system repo](https://github.com/muqsitnawaz/.agents). To use your own:
-
-```bash
-# Fork the system repo, then:
 agents repo add gh:username/.agents
-
-# Now pull uses your repo
 agents pull
 ```
 
-## .agents Repo Structure
-
-```
-.agents/
-  agents.yaml              # CLI versions, MCP servers, defaults
-  shared/commands/         # Slash commands for all agents
-  claude/commands/         # Claude-specific commands
-  claude/hooks/            # Claude hooks
-  codex/prompts/           # Codex-specific prompts
-  gemini/commands/         # Gemini commands (auto-converted to TOML)
-  skills/                  # Agent Skills (SKILL.md + rules/)
-```
-
-Example `agents.yaml`:
-
-```yaml
-clis:
-  claude:
-    package: "@anthropic-ai/claude-code"
-    version: "latest"
-  codex:
-    package: "@openai/codex"
-    version: "latest"
-
-mcp:
-  filesystem:
-    command: "npx -y @anthropic-ai/mcp-filesystem"
-    transport: stdio
-    scope: user
-    agents: [claude, codex, gemini]
-
-  memory:
-    command: "npx -y @anthropic-ai/mcp-memory"
-    transport: stdio
-    scope: user
-    agents: [claude, codex, gemini]
-
-defaults:
-  method: symlink
-  scope: user
-  agents: [claude, codex, gemini]
-```
-
 ## Commands
 
-### Status
-
 ```bash
-agents status              # Full overview
-agents status --agent claude
-```
-
-### Pull & Push
+# Sync
+agents pull [agent]              # Pull config (optionally for one agent)
+agents push                      # Push local changes back
 
-```bash
-agents pull                # Sync all agents from your repo
-agents pull claude         # Sync only Claude resources
-agents pull cc             # Same (aliases: cc, codex/cx, gemini/gx)
-agents pull --dry-run      # Preview what would change
-agents pull -y             # Auto-confirm, skip conflicts
-agents pull -f             # Auto-confirm, overwrite conflicts
-agents push                # Push local changes back
-```
+# Resources
+agents commands list|add|remove|push
+agents mcp list|add|remove|push
+agents skills list|add|info
+agents hooks list|add|remove
 
-The pull command shows an overview of NEW vs EXISTING resources before installation. For conflicts, you're prompted per-resource to overwrite, skip, or cancel.
+# CLI management
+agents cli list|add|remove|upgrade
 
-### Slash Commands
+# Registries
+agents search <query>            # Search MCP registries
+agents add mcp:<name>            # Install from registry
 
-```bash
-agents commands list
-agents commands add gh:user/my-commands
-agents commands remove my-command
-agents commands push my-command   # Promote project -> user scope
+# Jobs
+agents jobs list|add|run|enable|disable|logs|report
+agents daemon start|stop|status|logs
 ```
 
-### MCP Servers
-
-```bash
-# List across all agents
-agents mcp list
+Resources support two scopes: **user** (`~/.{agent}/`) for global availability, and **project** (`./.{agent}/`) for repo-specific config. Use `push` subcommands to promote project scope to user scope.
 
-# Add (use -- before the command)
-agents mcp add memory -- npx -y @anthropic-ai/mcp-memory
-agents mcp add api https://api.example.com --transport http
+## Jobs
 
-# Search registries
-agents search filesystem
-agents add mcp:@anthropic-ai/mcp-filesystem
+Schedule AI agents to run autonomously on a cron schedule. Define a job in YAML, the daemon handles the rest.
 
-# Remove
-agents mcp remove memory
-```
+```yaml
+name: reddit-engagement
+schedule: "0 9 * * 1-4"
+agent: claude
+mode: plan
+timeout: 30m
+prompt: |
+  Today is {day}. Follow the engagement plan.
 
-### Skills
+allow:
+  tools: [web_search, web_fetch]
+  sites: [reddit.com, old.reddit.com]
+  dirs: [~/.agents/reports/reddit-engagement]
 
-```bash
-agents skills list
-agents skills add gh:user/my-skills
-agents skills info my-skill
+config:
+  model: claude-sonnet-4-5
 ```
 
-### Hooks
+Jobs support `claude`, `codex`, and `gemini` agents. The `prompt` supports template variables: `{day}`, `{date}`, `{time}`, `{job_name}`, `{last_report}`.
 
-```bash
-agents hooks list
-agents hooks add gh:user/my-hooks
-agents hooks remove my-hook
-```
+### Sandboxed Execution
 
-### CLI Management
+Each job runs in an isolated environment. The agent doesn't see your real home directory - it gets an overlay:
 
-```bash
-agents cli list            # Show installed versions
-agents cli add claude      # Install agent CLI
-agents cli remove codex    # Uninstall agent CLI
-agents cli upgrade         # Upgrade all to latest
 ```
-
-## Scopes
-
-Resources can exist at two levels:
-
-| Scope | Location | Use |
-|-------|----------|-----|
-| User | `~/.{agent}/` | Available everywhere |
-| Project | `./.{agent}/` | This repo only, committed |
-
-Promote project-scoped items to user scope:
-
-```bash
-agents commands push my-command
-agents mcp push my-server
-agents skills push my-skill
+~/.agents/jobs/reddit-engagement/home/     <-- agent sees this as $HOME
+  .claude/
+    settings.json                          <-- generated from allow.tools
+  .agents/
+    reports/
+      reddit-engagement/ -> ~/real/path    <-- symlink from allow.dirs
 ```
 
-## Filtering
+Two layers of enforcement, neither relies on prompt injection:
 
-All list commands support filters:
+| Layer | What it does | How |
+|-------|-------------|-----|
+| **Agent config** | Tool allowlists (`WebSearch(*)`, `Read(*)`, etc.) | Agent CLI reads generated config and blocks disallowed tools |
+| **HOME overlay** | Filesystem isolation | Only `allow.dirs` entries are symlinked in; everything else is invisible |
+| **Env sanitization** | No credential leakage | Only safe env vars (PATH, SHELL, LANG, etc.) are passed through |
 
-```bash
-agents commands list --agent claude
-agents mcp list --scope project
-agents skills list --agent codex --scope user
-```
-
-## Registries
+The agent can't access `~/.ssh`, `~/.aws`, `~/.gitconfig`, API keys in env vars, or anything else you didn't explicitly allow. The overlay is recreated fresh before each run.
 
-Search and install from public registries:
-
-```bash
-# Search
-agents search github --type mcp
+### Model Pinning
 
-# Install from registry
-agents add mcp:@anthropic-ai/mcp-filesystem
+```yaml
+# Claude
+config:
+  model: claude-sonnet-4-5
 
-# Manage registries
-agents registry list
-agents registry add mcp myregistry https://api.example.com
-agents registry config mcp myregistry --api-key KEY
+# Codex
+agent: codex
+config:
+  model: gpt-5.2-codex
 ```
 
 ## Supported Agents
 
-| Agent | Commands | MCP | Hooks | Skills |
-|-------|----------|-----|-------|--------|
-| Claude Code | Yes | Yes | Yes | Yes |
-| Codex | Yes | Yes | - | Yes |
-| Gemini CLI | Yes | Yes | Yes | Yes |
-| Cursor | Yes | Yes | - | - |
-| OpenCode | Yes | Yes | - | - |
+| Agent | Commands | MCP | Hooks | Skills | Jobs |
+|-------|----------|-----|-------|--------|------|
+| Claude Code | Yes | Yes | Yes | Yes | Yes |
+| Codex | Yes | Yes | - | Yes | Yes |
+| Gemini CLI | Yes | Yes | Yes | Yes | Yes |
+| Cursor | Yes | Yes | - | - | - |
+| OpenCode | Yes | Yes | - | - | - |
 
-Format conversion is automatic. Write commands in markdown, they're converted to TOML for Gemini.
+## Roadmap: Context Drives
 
-## Related
+Sync docs, research, and agent chat history across machines and teams. Per-directory conflict strategies (CRDT, git, lock, last-write-wins). Checkpointing and rollback.
 
-- [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) - MCP server for sub-agent spawning
-- [Agents Extension](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext) - Full-screen agent terminals in VS Code/Cursor
+```bash
+agents drive create <name>
+agents drive sync
+agents drive checkpoint "before refactor"
+agents drive rollback <checkpoint>
+```
 
 ## License