monkeyscode-cli 0.1.12 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 > AI-powered coding agent for the terminal. Works on macOS, Linux, and Windows.
 
-[![npm version](https://img.shields.io/npm/v/@monkeyscode/cli)](https://www.npmjs.com/package/@monkeyscode/cli)
+[![npm version](https://img.shields.io/npm/v/monkeyscode-cli)](https://www.npmjs.com/package/monkeyscode-cli)
 [![GitHub Actions](https://img.shields.io/github/actions/workflow/status/MonkeysCloud/monkeyscode/cli-release.yml)](https://github.com/MonkeysCloud/monkeyscode/actions)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
@@ -12,23 +12,25 @@
 ## Quick Install
 
 ```bash
-# macOS / Linux
-curl -fsSL https://monkeyscode.com/install.sh | sh
+# macOS / Linux (installs `mc` to /usr/local/bin; override with MC_INSTALL_DIR)
+curl -fsSL https://monkeyscode.com/cli/install.sh | bash
 
 # Windows (PowerShell)
-irm https://monkeyscode.com/install.ps1 | iex
+irm https://monkeyscode.com/cli/install.ps1 | iex
 
-# npm
-npm install -g @monkeyscode/cli
-
-# Homebrew
-brew install monkeyscode
+# npm (Node 18+)
+npm install -g monkeyscode-cli
 ```
 
+The binary is installed as `mc`, with `monkeyscode` (and `mcode` from the
+install script) as aliases. A Homebrew formula template lives in
+`packaging/homebrew/`, but there is no published tap yet.
+
 ## Usage
 
 ```bash
-# Interactive REPL
+# Interactive REPL (optionally with a first prompt)
+mc
 mc "refactor the auth module"
 
 # Headless (CI/CD)
@@ -37,11 +39,11 @@ mc -p "fix all lint errors" --headless --auto-approve
 # Background job with auto-PR
 mc -p "write tests" --background --auto-branch --auto-pr
 
-# Pipe mode
+# Pipe mode: stdin becomes the prompt, the answer goes to stdout
 echo "explain this error" | mc
 
 # Model selection
-mc --model claude-opus "deep architecture review"
+mc --model opus "deep architecture review"
 ```
 
 <!-- TODO: Record with asciinema and convert to GIF -->
@@ -50,11 +52,13 @@ mc --model claude-opus "deep architecture review"
 ## Features
 
 ### 🤖 Multi-Model Support
-Switch between Claude, GPT-4o, Gemini, and MonkeysCode's own Capuchin model.
+Switch between MonkeysCode's own Capuchin model (the default), Claude Sonnet
+and Opus, Gemini 2.5 Pro, and GPT-4.1. `mc models list` shows the full list with
+pricing.
 
 ```bash
-mc --model auto "fix the bug"       # Smart model selection
-mc --model claude-opus "review PR"  # Specific model
+mc --model auto "fix the bug"   # Your configured default model
+mc --model opus "review PR"     # Aliases: sonnet, opus, capuchin, or a full model id
 ```
 
 ### 📁 Full Tool Suite
@@ -64,11 +68,14 @@ The agent can edit files, run terminal commands, search code, and manage git —
 <!-- ![Tool execution](docs/assets/tools.gif) -->
 
 ### 🔒 Sandboxed Execution
-Run agent commands in isolated sandboxes (bubblewrap, sandbox-exec, Docker).
+Run agent commands in isolated sandboxes (bubblewrap on Linux, sandbox-exec on
+macOS, Docker anywhere). The best available provider is picked automatically;
+without one, `--sandbox` reports it as unavailable instead of pretending.
 
 ```bash
 mc --sandbox "run the migration script"
-mc --sandbox-network=none "process sensitive data"
+mc --sandbox --sandbox-network none "process sensitive data"   # none | local | full
+mc --sandbox --sandbox-provider docker "try the install script"
 ```
 
 ### 🌐 Background Jobs
@@ -90,32 +97,82 @@ mc dream           # Consolidate session history into memory
 ```
 
 ### ⚡ CI/CD Integration
-Run headlessly in GitHub Actions, GitLab CI, or any CI system.
+Run headlessly in GitHub Actions, GitLab CI, or any CI system. The action lives
+in this directory (`apps/cli/action.yml`), not at the repository root:
 
 ```yaml
-# .github/workflows/review.yml
-- uses: MonkeysCloud/monkeyscode@main
+# .github/workflows/monkeyscode-mention.yml — answers "@monkeyscode …" comments, read-only
+- uses: MonkeysCloud/monkeyscode/apps/cli@main
   with:
-    prompt: 'Review this PR'
-    mode: plan
-    output: github
     api-key: ${{ secrets.MONKEYSCODE_API_KEY }}
+    max-cost: '1'
+```
+
+Ready-made workflows are in [`workflows/`](workflows/): PR review (SARIF),
+`@monkeyscode` mentions, fix failing CI → PR, issue → draft PR, and nightly
+dependency updates. Each one limits what the agent may run, never lets it
+push, and skips fork runs that would expose your key. Give CI a
+**restricted key** (spend cap + model allowlist); the action warns when it
+isn't. See [docs/cli/ci.md](../../docs/cli/ci.md).
+
+Anywhere else, call the CLI directly:
+
+```bash
+mc -p "fix the failing test" --allowed-tools "run_command(npm test:*)" "edit_file(src/**)" -o json --max-cost 2
+git diff | mc -p "review this diff"            # stdin is appended to the prompt
+mc -p -o stream-json "refactor utils"           # one JSON event per line
 ```
 
+The exit code tells you what happened: `0` ok, `2` bad flags, `3` auth,
+`4` quota, `5` `--max-cost`/`--max-tokens`, `6` only denials, `124`
+timeout. Flags, the event stream, multi-turn stdin and permission prompts are in
+[docs/cli/headless.md](../../docs/cli/headless.md).
+
 ### 🔌 MCP Servers
 Extend the agent with custom tools via the Model Context Protocol.
 
 ```bash
-mc mcp add jira npx @monkeyscode/mcp-jira
-mc mcp add slack npx @monkeyscode/mcp-slack
+mc mcp browse                                   # 35+ curated servers
+mc mcp add jira                                 # Add from the registry by id
+mc mcp add my-tools npx -y my-mcp-server        # Or any command
 mc mcp list
 ```
 
+Servers start in the background when a session opens; their tools reach the model as
+`mcp__<server>__<tool>` (e.g. `mcp__jira__create_issue`) and follow permission rules like
+any other tool (`mcp__jira__*` allows or denies a whole server). `/mcp` shows status and
+tool counts and can `reconnect`, `disable` or `enable` a server for the session.
+
+A server defined by the repository (`.monkeyscode/settings.json`, `.monkeyscode/mcp.json`)
+runs a command someone else chose, so it does not start until you approve it with
+`/mcp approve <name>` or `mc mcp approve <name>`. Editing the entry voids the approval.
+Servers you add with `mc mcp add` are approved automatically.
+
+### 🧩 Commands, Subagents, Skills, Hooks & Plugins
+Extend the agent with plain files in `.monkeyscode/`, in Claude Code's formats:
+
+```bash
+mc import claude --dry-run          # bring over .claude/ (commands, agents, skills, hooks, MCP)
+mc import cursor                    # .cursor/rules, .cursorrules, .cursor/mcp.json
+mc plugin install https://github.com/<owner>/<repo>   # guarded: nothing from it runs
+mc plugin enable <name>             # review what it can do, then trust + enable
+```
+
+- `.monkeyscode/commands/*.md` → `/name` (`$ARGUMENTS`, `@file`, `` !`cmd` ``, `allowed-tools`)
+- `.monkeyscode/agents/*.md` → subagents the model delegates to
+- `.monkeyscode/skills/<name>/SKILL.md` → skills, loaded on demand
+- `hooks` in settings → Claude-compatible hooks (exit 2 blocks)
+
+Hooks, scripts and status lines from a repository wait for **workspace trust**.
+Plugins are validated, hash-pinned, re-verified on every start and capped at runtime.
+The full reference is [docs/cli/extensibility.md](../../docs/cli/extensibility.md).
+
 ### 👥 Multi-Agent Teams
 Spawn parallel agents to divide and conquer large tasks.
 
 ```bash
-mc team spawn --task "Implement auth, payments, and email modules"
+# One quoted prompt per agent; each runs in its own git worktree
+mc team spawn "Implement auth" "Implement payments" "Implement email" --max-agents 3
 mc team status
 mc team merge team-abc123
 ```
@@ -124,25 +181,54 @@ mc team merge team-abc123
 
 | Format | Use Case |
 |--------|----------|
-| `text` | Interactive terminal (default) |
-| `json` | Structured result for scripts |
-| `jsonl` | Streaming events for real-time parsing |
+| `text` | The final answer (default) |
+| `json` | One `result` object: answer, cost, usage, session id, denials |
+| `stream-json` | Every event, one per line (the protocol the SDKs speak) |
+| `jsonl` | Legacy event stream |
 | `diff` | Unified diff (`git apply` compatible) |
 | `markdown` | Clean markdown (for PR descriptions) |
 | `github` | GitHub Actions output format |
 | `azure` | Azure DevOps format |
 | `sarif` | SARIF 2.1.0 for code scanning |
+| `stream` | Raw event stream |
+
+## Permissions & Effort
+
+What the agent **may do** (permission mode + rules) and how hard the model
+**thinks** (effort) are separate settings.
+
+```bash
+mc --permission-mode acceptEdits "refactor utils"     # default | acceptEdits | plan | bypass
+mc -p "fix tests" --headless --allowed-tools "run_command(npm test:*)" "edit_file(src/**)"
+mc --effort high "find the race condition"            # low | medium | high
+```
+
+In a session: Shift+Tab cycles `default` → `acceptEdits` → `plan`, `/plan` jumps to plan mode, `/effort high` changes
+effort from the next request, and `/permissions` lists every effective rule
+and the file it came from. Headless runs never prompt. A call that would
+prompt is denied and reported in `permissionDenials`. If *only* denials
+happened, the exit code is **6**.
+
+The rule syntax, evaluation order and shell-command handling are in
+[docs/cli/permissions.md](../../docs/cli/permissions.md).
 
 ## Configuration
 
 ```bash
-mc config set defaultModel claude-sonnet    # Set default model
-mc config set theme dark                     # Set theme
-mc config list                               # Show all settings
-mc config path                               # Show config file locations
+mc config set model claude-sonnet                        # user settings
+mc config set permissions.defaultMode acceptEdits --scope project
+mc config list --show-origin                             # effective values + where each came from
+mc config path                                           # settings file locations
+mc config migrate                                        # fold legacy config.json/permissions.json/mcp.json
+mc doctor                                                # auth, settings layers, invalid rules, defaults
 ```
 
-Project-level config: `.monkeyscode/config.json`
+Settings are layered. From highest to lowest precedence: managed policy →
+flags → env → `.monkeyscode/settings.local.json` (gitignored) →
+`.monkeyscode/settings.json` (committed) → `~/.monkeyscode/settings.json`.
+Permission rules are combined across layers. For other keys, the
+highest-precedence layer wins. A repository can't set backend URLs or other
+trusted-only keys. Legacy `config.json` files are still read.
 
 ## Shell Completions
 
@@ -150,7 +236,7 @@ Project-level config: `.monkeyscode/config.json`
 mc completions bash >> ~/.bashrc
 mc completions zsh >> ~/.zshrc
 mc completions fish > ~/.config/fish/completions/mc.fish
-mc completions powershell >> $PROFILE
+mc completions pwsh >> $PROFILE
 ```
 
 ## Slash Commands (REPL)
@@ -158,35 +244,40 @@ mc completions powershell >> $PROFILE
 | Command | Description |
 |---------|-------------|
 | `/help` | Show all commands |
+| `/clear` | Start a fresh conversation (the old one stays resumable); Ctrl+L only clears the screen |
 | `/model <name>` | Switch model |
-| `/mode <mode>` | Switch mode (agent/plan/ask) |
-| `/compact` | Toggle compact output |
+| `/plan` | Switch to plan (read-only) mode; Shift+Tab to cycle back |
+| `/effort [low\|medium\|high]` | Show or set reasoning effort |
+| `/permissions` | Show rules and their sources; `allow`/`deny`/`ask`/`remove` |
+| `/status` | Model, mode, effort, context and cost at a glance |
+| `/compact ["focus"]` | Summarise the conversation to free context |
 | `/diff` | Show session changes |
-| `/undo` | Revert last edit |
+| `/undo` | Revert the last turn's file changes |
 | `/commit [msg]` | Commit changes |
 | `/files` | List touched files |
-| `/cost` | Show token usage |
+| `/cost [all]` | Session cost totals plus a per-turn breakdown |
 | `/vim` | Toggle Vim keybindings |
 | `/cloud` | Hand off to cloud |
-| `/context <file>` | Add file to context |
+| `/context [file]` | Show context usage, or add a file to it |
 
 ## SDK
 
-Build custom integrations with the TypeScript SDK:
-
-```bash
-npm install @monkeyscode/sdk
-```
+Run this agent from your own code, with your settings, rules, hooks and MCP
+servers:
 
 ```typescript
-import { MonkeysCode } from '@monkeyscode/sdk';
+import { query } from '@monkeyscode/agent';   // the engine in process (Node)
 
-const agent = new MonkeysCode({ apiKey: process.env.MONKEYSCODE_API_KEY });
-const result = await agent.run('Fix all TypeScript errors');
-console.log(result.summary);
+const q = query({ prompt: 'Fix the failing test', options: { allowedTools: ['run_command(npm test:*)'], maxCostUsd: 1 } });
+for await (const e of q) if (e.type === 'result') console.log(e.result);
 ```
 
-See [`@monkeyscode/sdk`](../packages/sdk-typescript/) for full documentation.
+From Python (`monkeyscode.cli_process`), Go (`monkeyscode.Query`) or
+TypeScript (`@monkeyscode/sdk/subprocess`), the same API drives an installed
+`mc` over stdio. Guide: [docs/cli/sdk.md](../../docs/cli/sdk.md).
+
+The cloud clients (`MonkeysCode` in [`@monkeyscode/sdk`](../../packages/sdk-typescript/))
+call the hosted API instead.
 
 ## Accessibility
 
@@ -216,9 +307,15 @@ Respects the `DO_NOT_TRACK=1` environment variable.
 - [Core Runtime](../../docs/coding-agent/cli/01-core-runtime.md)
 - [Interactive Experience](../../docs/coding-agent/cli/02-interactive-experience.md)
 - [Auth & Configuration](../../docs/coding-agent/cli/03-auth-configuration.md)
-- [Headless / CI/CD](../../docs/coding-agent/cli/04-headless-cicd.md)
+- [Headless mode: flags, exit codes, stream-json](../../docs/cli/headless.md)
+- [CI: workflow recipes and restricted keys](../../docs/cli/ci.md)
+- [SDKs: in process and subprocess](../../docs/cli/sdk.md)
+- [Headless / CI/CD (older overview)](../../docs/coding-agent/cli/04-headless-cicd.md)
 - [Background & Cloud](../../docs/coding-agent/cli/05-background-cloud.md)
 - [Distribution](../../docs/coding-agent/cli/06-distribution.md)
+- [Permissions](../../docs/cli/permissions.md)
+- [Extensibility: memory, commands, subagents, skills, hooks, MCP, plugins, import](../../docs/cli/extensibility.md)
+- [Plugin marketplace contract](../../docs/plugin-marketplace.md)
 - [SDK & Extensibility](../../docs/coding-agent/cli/07-sdk-extensibility.md)
 
 ## License