cheap-agent 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "cheap-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Cut your Claude Code usage: Claude plans, a cheap model writes the code. One command to install.",
+  "license": "Elastic-2.0",
+  "author": "muaaz9329",
+  "homepage": "https://github.com/muaaz9329/cheap-ag#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muaaz9329/cheap-ag.git"
+  },
+  "bugs": {
+    "url": "https://github.com/muaaz9329/cheap-ag/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "mcp",
+    "ai-agents",
+    "deepseek",
+    "openrouter",
+    "cost",
+    "delegation"
+  ],
+  "type": "module",
+  "bin": {
+    "cheapag": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@opencode-ai/sdk": "1.19.0",
+    "opencode-ai": "1.19.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "cheapag",
+  "displayName": "Cheap Agent",
+  "version": "1.0.0",
+  "description": "Claude plans and reviews while a cheaper model implements: the cheapag MCP server, the plan-writing skill, status, allow, hook and clean commands, and an opt-in edit guard.",
+  "author": { "name": "muaaz9329" },
+  "keywords": ["delegation", "opencode", "mcp", "cost"]
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cheapag": {
+      "command": "npx",
+      "args": ["-y", "cheap-agent@1.0.0"]
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,38 @@
+# Cheap Agent plugin for Claude Code
+
+Gives Claude the Cheap Agent MCP server (`delegate`, `research`, `reply`, `jobs`, `land`), the plan-writing skill, `/cheapag:status`, and the user-only commands `/cheapag:allow`, `/cheapag:clean` and `/cheapag:hook`.
+
+## Worker models
+
+`npx cheap-agent login` asks which worker models to use, after the provider. Each preset picks the implement and escalation models for your provider (OpenCode Go, OpenRouter or DeepSeek):
+
+- **cheapest**: the lowest worker spend. Claude takes over more often when the worker fails.
+- **balanced** (the default): the preset the benchmark measured and recommends.
+- **strongest**: the strongest cheap models, for when you would rather pay the worker than have Claude take over.
+
+Measured on SWE-bench Verified (OpenRouter): Flash's worker cost is about $0.005 per easy task and $0.03 per hard one; GLM-5.3 costs about $0.06 on the hard ones, and there Claude used 1.5x fewer tokens than with Flash, because GLM-5.3's failures cost Claude less to recover from. On the hard tier alone GLM-5.3 showed no gain, so `balanced` keeps Flash everywhere and `strongest` (GLM-5.3 for every task) is opt-in. `cheapest` is the same as `balanced` today.
+
+The choice goes into `models` in `~/.config/cheapag/config.json`. Run `npx cheap-agent login --preset <cheapest|balanced|strongest>` to switch without the prompts. `ping` and `cheapag status` show it as `preset=<name>`. For a finer choice, set `models` (`implement`, `research`, `escalation`, `fallback`, as full `provider/model` names) in a repo's `cheapag.json`, which overrides the user config, or in the user config itself; answering `custom` (or `--preset custom`) makes login leave it as you wrote it. Changing the models after `/cheapag:allow` makes the next job ask for it again, with the new list.
+
+## What it costs to keep in context
+
+Everything Claude Code loads at session start is sent again on every turn: the system prompt, tool definitions, every enabled skill's description, plugin instructions and CLAUDE.md. A bigger prefix means each turn costs more, and a prefix that changes between sessions is rewritten at full price instead of read from cache. Measured on a real machine (Claude Code 2.1.285), a session that only answers "OK" cost $0.10 with ~100 user plugins and skills enabled, against $0.02–0.04 with only what the task needs.
+
+- **Disable plugins you are not using** (`/plugin` → disable). Each enabled plugin adds its skills and instructions to every turn of every session.
+- **Mark skills you only call by name** with `disable-model-invocation: true` in their `SKILL.md` frontmatter. Their descriptions then stay out of the context. Cheap Agent's `allow`, `clean` and `hook` already do this.
+- **Keep CLAUDE.md under ~200 lines.** It is part of every turn. Move rarely needed detail into files Claude reads on demand.
+- **Pin the Claude Code version** (`DISABLE_AUTOUPDATER=1`) during long stretches of work. An update changes the system prompt, so the next session rewrites the whole cached prefix.
+- **For scripted runs** (`claude -p`): `--setting-sources project` skips user plugins and settings, and `--exclude-dynamic-system-prompt-sections` keeps per-machine details (cwd, git status) out of the cached prefix. The `includeGitInstructions: false` setting drops the commit/PR boilerplate when the agent never commits.
+
+`cheapag status` prints the prefix size of this repo's most recent Claude Code session, when its transcript is readable (`claude prefix: 18.4k tokens on the first turn …`). Under ~20k is lean; 40k+ usually means plugins or skills the work doesn't use.
+
+## Sessions, `/clear` and the cache TTL
+
+Claude Code caches the session prefix. Every turn that starts within the cache's lifetime reads it at a tenth of the input price, instead of writing it again at more than the input price. How you split work into sessions decides how often you pay the full write.
+
+- **One session per block of work.** Starting a fresh `claude` for every small task writes the whole prefix each time. Inside a session it is written once and then read.
+- **`/clear` between unrelated tasks.** It's free: the prefix stays cached, and only the conversation is dropped. It also keeps old, unrelated context from distracting Claude on the next task.
+- **Pick the TTL for how you work.** The default 1-hour cache suits all-day work with pauses. For short bursts of back-to-back tasks, `CLAUDE_CODE_PROMPT_CACHE_TTL=5m` makes cache writes cheaper ($5 instead of $8 per million tokens on Opus), as long as you never idle more than five minutes. After a longer pause, the next turn rewrites the prefix.
+- `cheapag status` shows the last session's cache use: `claude cache: 14 requests, 91% of input from cache, 1h TTL`. A low percentage on a long session means the prefix kept changing (plugins toggled, an update, idle gaps past the TTL).
+
+On a Pro or Max plan these are dollar estimates at API prices. Anthropic says cached tokens count less toward plan limits, but publishes no ratio.

package/plugin/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "description": "Cheap Agent: SessionStart adds a one-line pointer to the delegate tool; the edit guard (edits and Bash file writes) is off until /cheapag:hook on; after a cheapag FAIL or PARTIAL, Claude hands the step to a Sonnet subagent (or, with takeover: self, its own calls are capped at limits.takeover_calls), and after an OK it does not re-run tests. Shell tests keep both free (no npx) while unused.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "r=$(git rev-parse --show-toplevel 2>/dev/null) && { [ -f \"$r/.cheapag/hook.json\" ] || [ -f \"$r/.cheapag/hook/takeover\" ]; } && npx -y cheap-agent@1.0.0 hook guard; exit 0",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__.*cheapag__(delegate|jobs|reply|land)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y cheap-agent@1.0.0 hook result; exit 0",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y cheap-agent@1.0.0 hook context",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/skills/allow/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: allow
+description: Opt this repository in to sending code to Cheap Agent's worker models - all models, --zdr-only (zero-retention only), or --models provider/model,...
+argument-hint: "[--zdr-only | --models provider/model,...]"
+disable-model-invocation: true
+allowed-tools: Bash(npx -y cheap-agent@1.0.0 allow) Bash(npx -y cheap-agent@1.0.0 allow *)
+---
+
+!`npx -y cheap-agent@1.0.0 allow $ARGUMENTS`
+
+The developer ran this consent command themselves; its output is above. Report it in one line. Do not run `cheapag allow` or change consent in any other way.

package/plugin/skills/clean/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: clean
+description: Remove Cheap Agent's old worktrees and job logs now; --all removes everything not in flight.
+argument-hint: "[--all]"
+disable-model-invocation: true
+allowed-tools: Bash(npx -y cheap-agent@1.0.0 clean) Bash(npx -y cheap-agent@1.0.0 clean *)
+---
+
+!`npx -y cheap-agent@1.0.0 clean $ARGUMENTS`
+
+Report the result above to the user in one or two lines.

package/plugin/skills/hook/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: hook
+description: Turn Cheap Agent's edit guard on or off for this repo - when on, Claude's large edits (or a 3rd edit to one file in a turn) are denied and redirected to delegate.
+argument-hint: "[on | off]"
+disable-model-invocation: true
+allowed-tools: Bash(npx -y cheap-agent@1.0.0 hook) Bash(npx -y cheap-agent@1.0.0 hook *)
+---
+
+!`npx -y cheap-agent@1.0.0 hook $ARGUMENTS`
+
+The developer ran this command themselves; its output is above. Report it in one line. Do not turn the edit guard on or off in any other way.

package/plugin/skills/plan-writing/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: plan-writing
+description: Write or fix a Cheap Agent plan file before calling the cheapag delegate tool. Use when planning a change of more than ~20 lines or several files for the cheap worker, splitting work into steps, or after delegate rejects a plan.
+---
+
+# Writing a Cheap Agent plan
+
+The cheap worker sees the whole plan, then implements the steps you name in `delegate`. It works in an isolated copy of the repo and does only what a step says, so each step must stand on its own: exact files, what to build, and a check that proves it works.
+
+Save plans under `.plan/` in the repository, e.g. `.plan/rate-limit.md` (the developer may read, edit or commit them). Pass the path relative to the repository root.
+
+## Grammar
+
+```
+# <plan title>                              ← required, exactly one H1
+<shared context, optional, ≤ ~15 lines>
+## <id> <short title>                       ← id = integer or integer+letter (3, 3a)
+files: <path>, <dir/>, ...                  ← required; scope + overlap key
+do: <what to build; continuation lines indented 2+ spaces>
+done-when: <condition>; <condition>         ← required; `backticked` = executed
+dont: <constraint>; <constraint>
+needs: <step id>, ...
+difficulty: easy | medium | hard            ← picks the worker model; wins over delegate's
+model: <model>
+deps: <package@range>                       ← the step needs a new package
+```
+
+- Keys are lowercase, at the start of the line, never bullets (`- files:` is wrong). Continuation lines are indented 2+ spaces.
+- In `done-when`, every `backticked` fragment is run as a shell command in the worker's copy and must exit 0. Put only commands in backticks; plain text is the worker's responsibility.
+- Unknown keys (e.g. `api:`, `example:`) are passed to the worker as hints.
+
+## Rules
+
+- **Size:** one step ≈ under an hour of junior-developer work. Split anything bigger.
+- **Checks:** give every step an executable `done-when` (a test command, a type check), not only prose. Name the one test file or test id the step concerns, never the whole suite.
+- **Source:** put the user's request or the issue verbatim in the shared context, or pass it as `delegate(source=…)` (text or a file path): the worker checks your steps against it and reports where they disagree.
+- **Scope:** `files:` lists every file or directory the step may touch, accurately. It also decides which steps can run in parallel.
+- **Constraints:** add `dont:` for the mistakes you expect (new dependencies, touching auth, changing public APIs).
+- **Grouping:** make independent steps separate comma groups so they run in parallel; use `needs:` when one step must land first.
+- **Packages:** declare a new package with `deps:`; the worker cannot install packages itself.
+- Share context once at the top (conventions, existing helpers to reuse) instead of repeating it per step.
+
+## Example
+
+```md
+# Rate limiting for auth endpoints
+Redis is already wired in src/lib/redis.ts. Keep middleware style consistent with src/middleware/*.
+
+## 1 limiter lib
+files: src/lib/rateLimit.ts, test/rateLimit.test.ts
+do: sliding-window limiter `limit(key, max, windowSec) -> {allowed, retryAfter}` using redis ZSET.
+done-when: `npm test -- rateLimit` passes; tests cover allow, block, window expiry
+dont: add dependencies
+
+## 2 wire into login
+files: src/api/login.ts, src/middleware/, test/login.test.ts
+do: 5 req/min per IP on POST /api/login; on block return 429 + Retry-After.
+done-when: `npm test -- login` passes; new test: 6th request → 429
+dont: touch auth/session logic
+needs: 1
+
+## 3 docs
+files: docs/api.md
+do: document the 429 response and Retry-After.
+done-when: section "Rate limits" exists under /api/login
+```
+
+## Delegating it
+
+- `steps="3"`: one step, one job. `steps="3-5"`: a range, run in order in one job. `steps="1-2,3"`: comma-separated groups, run in parallel unless their `files:` overlap or `needs:` orders them.
+- `delegate(plan=".plan/rate-limit.md", steps="1-2,3")`
+- `delegate(plan=".plan/rate-limit.md", steps="2", note="use the existing ipFrom(req) helper")`: a `note` is at most 300 characters, for one-off guidance.

package/plugin/skills/status/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: status
+description: Show Cheap Agent's status for this repo - running jobs, recent results, consent, and tracked spend against OpenCode Go windows.
+allowed-tools: Bash(npx -y cheap-agent@1.0.0 status)
+---
+
+!`npx -y cheap-agent@1.0.0 status`
+
+Show the status above to the user as is. Add a line only if something needs their action (a BLOCKED job to reply to, a missing consent, a Go window near its cap).