feat: Cude Claw, agent modes, checkpoints and MCP

CHANGELOG.md

@@ -4,12 +4,40 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### New Features
+
+- **Cude Claw** (`cude claw`) — an interactive agent session that keeps context
+  between turns. Every file edit is previewed as a diff and approved
+  individually (yes / no / always / stop); a declined edit tells the model not
+  to retry it, and stopping mid-turn still answers every tool call the model
+  made. `@path` in a message attaches that file's contents. Slash commands:
+  `/mode` `/model` `/tools` `/mcp` `/rules` `/cost` `/undo` `/checkpoints`
+  `/auto` `/clear` `/exit`.
+- **Agent modes** — `code`, `architect`, `ask`, `debug`, `orchestrator`. A mode
+  is a system prompt plus a tool budget, and the budget is enforced twice: when
+  the tool list is built for the model, and again before each call, so a model
+  asking for a tool it was never offered is refused rather than obeyed.
+  Architect's "writes only Markdown" is a path rule, not a description.
+  `cude run --mode <name>`, `cude modes list|show`.
+- **Project rules** — `AGENTS.md`, `CUDE.md`, `.cuderules` and
+  `.cude/rules/*.md` are discovered from the filesystem root down to the
+  workspace root, so a monorepo rule applies to packages inside it and the
+  closest file wins. `cude rules`.
+- **Checkpoints** — the state of every file is captured before the agent
+  changes it, so any edit can be undone. Works without git and never touches
+  git if present. `cude checkpoint list|show|restore|restore-run|clear`.
+- **MCP server support** — connect Model Context Protocol servers over stdio or
+  HTTP and their tools become agent tools, namespaced `mcp__<server>__<tool>`
+  so none can shadow a built-in. Implemented against the protocol directly, so
+  no new runtime dependency. `~/.cude/mcp.json` uses the same `mcpServers`
+  shape as other MCP clients. `cude mcp list|test|add|remove|enable|disable`.
+
+### Bug Fixes
+
 Ten defects found by an end-to-end audit that installed the tool and ran the
 agent against a local OpenAI-compatible endpoint. F1, F2 and F5 change
 behaviour.
 
-### Bug Fixes
-
 - **[F1] The agent reported success even when it failed.** `runToolsAgent` and
   `runReActAgent` returned `success: true` unconditionally, so a run that
   exhausted `--max-iterations` or tripped the budget gate printed
@@ -59,8 +87,11 @@ behaviour.
 
 - `test/helpers/openai-stub.mjs`: a scripted local OpenAI-compatible server
   that makes the agent loop testable end-to-end with no API key.
-- New suites: `agent`, `wire`, `config`, `budget`, `providers`, `spinner`.
-  80 tests total, up from 24.
+- New suites: `agent`, `wire`, `config`, `budget`, `providers`, `spinner`,
+  `modes`, `checkpoints`, `mcp`, `claw`. 130 tests total, up from 24.
+- `test/helpers/mcp-stub-server.mjs`: a real stdio MCP server, so the client is
+  tested against the protocol rather than a mock of it — which is how two
+  Windows spawn bugs and a tool-namespacing bug were caught.
 - `CUDE_HOME` redirects persisted state so budget- and config-backed behaviour
   can be tested without touching the real `~/.cude`.
 

README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="./assets/cude-banner.svg" alt="Cude Code — YAZ. ANLA. ÜRET." width="900">
+  <img src="./assets/cude-banner.png" alt="Cude Code — YAZ. ANLA. ÜRET." width="100%">
 </p>
 
 <p align="center">
-  <img src="./assets/cude-cli.png" alt="Cude Code running in the terminal" width="620">
+  <img src="./assets/cude-cli.svg" alt="Cude Code running in the terminal" width="620">
 </p>
 
 # Cude Code - Professional AI Development CLI
@@ -71,6 +71,9 @@ cude chat -p openai -m gpt-4
 
 # Run an autonomous task
 cude run "Create a REST API in TypeScript"
+
+# Or work with it interactively, approving each edit
+cude claw
 ```
 
 ## Usage Examples
@@ -90,6 +93,92 @@ cude chat -s my-project
 cude chat --free
 ```
 
+### Cude Claw — interactive sessions
+
+Claw keeps context between turns and shows you every edit before it happens.
+
+```bash
+cude claw                          # start a session
+cude claw "refactor src/api"       # start with a task
+cude claw --mode ask               # read-only: it cannot modify anything
+cude claw -y                       # apply edits without asking
+```
+
+Inside a session:
+
+| | |
+|---|---|
+| `@src/app.ts` | Attach a file's contents to your message |
+| `/mode architect` | Switch mode mid-conversation |
+| `/model claude-sonnet-5` | Switch model |
+| `/cost` | Spend so far this session |
+| `/undo` | Revert every file change this session made |
+| `/tools` `/mcp` `/rules` | What the agent currently has available |
+| `/help` | Everything else |
+
+When the agent wants to change a file, you see the diff and choose
+`y` / `n` / `a`(lways) / `s`(top).
+
+### Agent Modes
+
+A mode is a system prompt plus a **tool budget** — what the agent may touch, not
+just what it is told to do. The restriction is enforced when the tool list is
+built *and* again before each call.
+
+| Mode | Can do |
+|---|---|
+| `code` | Everything (default) |
+| `architect` | Reads anything, writes only Markdown |
+| `ask` | Read-only — cannot modify anything |
+| `debug` | Everything, prompted to find causes before fixes |
+| `orchestrator` | Everything, works through ordered sub-tasks |
+
+```bash
+cude run "plan the migration" --mode architect
+cude modes list
+cude modes show ask
+```
+
+### Project Rules
+
+Standing instructions live in the repository, not in every prompt. Cude reads
+`AGENTS.md`, `CUDE.md`, `.cuderules` and `.cude/rules/*.md`, walking from the
+filesystem root down to your workspace — so a monorepo-wide rule applies to the
+packages inside it, and the closest file wins.
+
+```bash
+cude rules    # show which files are in effect
+```
+
+### Undo
+
+Every agent file change is checkpointed first, so a wrong edit is not permanent.
+Works without git, and never touches git if present — an agent run is not a
+commit.
+
+```bash
+cude checkpoint list
+cude checkpoint restore-run <id>   # undo a whole run
+cude checkpoint restore <id>       # undo one tool call
+```
+
+### MCP Servers
+
+Connect Model Context Protocol servers to give the agent tools beyond the
+built-in ones. `~/.cude/mcp.json` uses the same `mcpServers` shape as other MCP
+clients, so an existing configuration copies across unchanged.
+
+```bash
+cude mcp add files --command npx -- -y @modelcontextprotocol/server-filesystem .
+cude mcp add docs --url https://example.com/mcp
+cude mcp test        # connect to each and list its tools
+cude mcp disable docs
+```
+
+Servers are verified before they are saved, tools are namespaced
+`mcp__<server>__<tool>` so none can shadow a built-in, and a server that fails
+to start is reported and skipped rather than taking the run down.
+
 ### Autonomous Tasks
 ```bash
 # Code generation
@@ -145,8 +234,15 @@ cude budget status
 
 # Set alert
 cude budget alert 5
+
+# Remove a limit (reset only clears the counters)
+cude budget unset --total
+cude budget unset --all
 ```
 
+Free and local providers (Ollama, vLLM, llama.cpp) are never blocked by a
+spending limit — they do not cost anything to block.
+
 ### Session Management
 ```bash
 # List sessions
@@ -267,15 +363,25 @@ cude config set default-model gpt-4o
 - **Linux/macOS**: `~/.cude/config.json`
 - **Windows**: `%USERPROFILE%\.cude\config.json`
 
-Sessions are stored under `~/.cude/sessions/` and spending records under `~/.cude/budget.json`.
+Sessions are stored under `~/.cude/sessions/`, spending records under
+`~/.cude/budget.json`, undo history under `~/.cude/checkpoints/`, and MCP
+servers in `~/.cude/mcp.json`. Set `CUDE_HOME` to move all of it.
 
 ## Security
 
-- All data stored locally
-- No cloud sync (unless enabled)
+- **Workspace boundary** — file-modifying tools are confined to a workspace
+  root (default: the current directory). Anything outside it is refused. Reads
+  are unrestricted. Override with `CUDE_WORKSPACE_ROOT` or
+  `cude config set workspace-root <dir>`.
+- **Destructive commands require confirmation**, including deletes, and
+  including `git_command` and `npm_command` — covering POSIX *and* Windows
+  (`del /f`, `rd /s`, `Remove-Item -Recurse`, `diskpart`), pipe-to-shell, and
+  the git subcommands that destroy unrecoverable work.
+- **Every file change is reversible** via checkpoints.
+- **Read-only modes are actually read-only** — enforced at execution, not by
+  prompt.
+- All data stored locally; no cloud sync
 - API keys never logged
-- Destructive commands require confirmation
-- Safe command execution
 - Open source for transparency
 
 ## Benchmarks
@@ -327,8 +433,15 @@ Free for personal and commercial use.
 - Environment-variable key fallback
 - Automatic legacy data migration
 
+### Unreleased
+- **Cude Claw** — interactive sessions with per-edit approval and diffs
+- **Agent modes** with enforced tool budgets, and project rule files
+- **Checkpoints** — undo any agent file change, no git required
+- **MCP server support** (stdio and HTTP)
+- Workspace boundary for file writes; Windows-aware destructive-command filter
+- Correct failure reporting and exit codes from `cude run`
+
 ### Planned (v0.2)
-- MCP (Model Context Protocol) server support
 - VS Code extension
 - Advanced analytics & spend reports