{"_id":"@ache-lol/cli","_rev":"3-2f254c26edfcf2c565b2d7f47a238edc","name":"@ache-lol/cli","dist-tags":{"latest":"0.1.99"},"versions":{"0.1.97":{"name":"@ache-lol/cli","version":"0.1.97","license":"Apache-2.0","_id":"@ache-lol/cli@0.1.97","maintainers":[{"name":"ache.lol","email":"npm@ache.lol"}],"bin":{"ache":"bin/ache.js"},"dist":{"shasum":"281e1033d589e05bd018d2894f66831b59cb76e7","tarball":"https://registry.npmjs.org/@ache-lol/cli/-/cli-0.1.97.tgz","fileCount":40,"integrity":"sha512-HYBkogh5teg+nEpNiIpCzr0YSIBGe/YHyh9KU3y4z0JMg08oHYkFlmzNKfYJTUWu2sVTSBNxPdQkHd4YRGG97w==","signatures":[{"sig":"MEUCIQC59F27x2Mxr+gUCXVTG5xbIaZEk/MlQUSTRe1+1IX6FQIgB2bs80WVXPPScS6j+IwG52hSKWG/5dqO38/LT4jYOOg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":270242169},"type":"module","_from":"file:ache-lol-cli-0.1.97.tgz","engines":{"node":">=22.19.0"},"scripts":{"dev":"make -C tools/proxy-helper/ copy-for-dev && bun run --preload ./src/set-package-dir.ts src/entry.ts","lint":"biome check src/ scripts/ tests/","test":"vitest run --dir src","build":"tsc --noEmit && node scripts/copy-resources.js --dev","check":"pnpm run lint && pnpm run typecheck","clean":"rm -rf dist","verify":"pnpm run check && pnpm run build:binary && pnpm run test && pnpm run test:smoke","lint:fix":"biome check --write src/ scripts/ tests/","dev:setup":"bun run --preload ./src/set-package-dir.ts src/entry.ts setup","typecheck":"tsc --noEmit","test:smoke":"vitest run --config tests/smoke/vitest.config.ts","dev:overlay":"scripts/dev-overlay.sh","postinstall":"node scripts/postinstall.js","build:binary":"node scripts/build-binary.js","test:e2e:acp":"pnpm run build:binary && vitest run --config tests/e2e/acp/vitest.config.ts","test:e2e:tui":"pnpm run build:binary && node scripts/run-tui-e2e.js","install:local":"node scripts/install-local.js","build:proxy-helper":"node scripts/build-proxy-helper.js","test:e2e:tui:debug":"pnpm run build:binary && node scripts/run-tui-e2e.js --debug","test:e2e:tui:trace":"pnpm run build:binary && node scripts/run-tui-e2e.js --trace","build:binary-linux-x64":"node scripts/build-binary.js --target linux-x64","build:binary-linux-arm64":"node scripts/build-binary.js --target linux-arm64","build:binary-windows-x64":"node scripts/build-binary.js --target windows-x64","test:e2e:tui:trace:replay":"node scripts/run-tui-e2e.js replay"},"_npmUser":{"name":"ache.lol","email":"npm@ache.lol"},"piConfig":{"name":"ache","configDir":".config/ache/harness"},"_resolved":"C:\\Users\\skill\\AppData\\Local\\Temp\\aa03634d141ba73fbcc6994ac47c55e8\\ache-lol-cli-0.1.97.tgz","_integrity":"sha512-HYBkogh5teg+nEpNiIpCzr0YSIBGe/YHyh9KU3y4z0JMg08oHYkFlmzNKfYJTUWu2sVTSBNxPdQkHd4YRGG97w==","_npmVersion":"11.11.1","description":"ache — a coding agent CLI powered by Cast AI, built on Ache","directories":{},"_nodeVersion":"24.14.0","dependencies":{"tar":"^7.5.15","zod":"^4.4.3","diff":"^9.0.0","open":"^10.2.0","ssh2":"^1.17.0","uuid":"^14.0.0","yaml":"^2.8.4","shiki":"^4.0.2","undici":"^8.2.0","wcwidth":"^1.0.1","micromatch":"^4.0.8","@types/diff":"^8.0.0","@types/ssh2":"^1.15.5","shell-quote":"1.8.4","@shikijs/cli":"^4.0.2","@clack/prompts":"^1.3.0","@xterm/headless":"^6.0.0","proper-lockfile":"^4.1.2","@bulkhead-ai/core":"^0.7.0","@earendil-works/pi-tui":"0.84.1","@types/proper-lockfile":"^4.1.4","@agentclientprotocol/sdk":"0.19.2","@modelcontextprotocol/sdk":"^1.29.0","@modelcontextprotocol/ext-apps":"^1.7.1","@earendil-works/pi-coding-agent":"0.84.1"},"_hasShrinkwrap":false,"devDependencies":{"ws":"^8.20.1","tsx":"^4.21.0","husky":"^9.1.7","vitest":"^3.2.4","node-pty":"^1.1.0","turndown":"^7.2.4","@types/ws":"^8.18.1","@types/tar":"^7.0.87","playwright":"1.59.1","typescript":"^5.9.3","@types/node":"^22.19.18","@biomejs/biome":"^2.5.3","supports-color":"^10.2.2","@types/turndown":"^5.0.6","@types/micromatch":"^4.0.10","@mixmark-io/domino":"^2.2.0","@types/shell-quote":"^1.7.5","@microsoft/tui-test":"0.0.4","@earendil-works/pi-ai":"0.84.1"},"peerDependencies":{"typebox":"*"},"optionalDependencies":{"@mariozechner/clipboard-darwin-x64":"0.3.6","@mariozechner/clipboard-darwin-arm64":"0.3.6","@mariozechner/clipboard-linux-x64-gnu":"0.3.6","@mariozechner/clipboard-linux-x64-musl":"0.3.6","@mariozechner/clipboard-win32-x64-msvc":"0.3.6","@mariozechner/clipboard-linux-arm64-gnu":"0.3.6","@mariozechner/clipboard-darwin-universal":"0.3.6","@mariozechner/clipboard-linux-arm64-musl":"0.3.6","@mariozechner/clipboard-win32-arm64-msvc":"0.3.6"},"_npmOperationalInternal":{"tmp":"tmp/cli_0.1.97_1787293273767_0.15440962007391845","host":"s3://npm-registry-packages-npm-production"}},"0.1.98":{"name":"@ache-lol/cli","version":"0.1.98","license":"Apache-2.0","_id":"@ache-lol/cli@0.1.98","maintainers":[{"name":"ache.lol","email":"npm@ache.lol"}],"bin":{"ache":"bin/ache.js"},"dist":{"shasum":"71b39de4ac6fb1cfecaf877716738679d593c6b1","tarball":"https://registry.npmjs.org/@ache-lol/cli/-/cli-0.1.98.tgz","fileCount":39,"integrity":"sha512-p5hMhTTJFpDSIeA0+mdxFOu+0nBkb64umjxMEq1/Hjx7Z/PXgj5V3BHvotn7svt15qUvNwx9kaxvWSgd2KSSkg==","signatures":[{"sig":"MEUCIQCVAyEmmEOS/n5AeRyFYSW3qejJBQx2jpvUxPvEe0IrGQIgd2RCNT/7c50yDuZ9QvaIDCGOLA/ZAfiGgPuMJtpfyRM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":138916102},"type":"module","_from":"file:ache-lol-cli-0.1.98.tgz","engines":{"node":">=22.19.0"},"scripts":{"dev":"make -C tools/proxy-helper/ copy-for-dev && bun run --preload ./src/set-package-dir.ts src/entry.ts","lint":"biome check src/ scripts/ tests/","test":"vitest run --dir src","build":"tsc --noEmit && node scripts/copy-resources.js --dev","check":"pnpm run lint && pnpm run typecheck","clean":"rm -rf dist","verify":"pnpm run check && pnpm run build:binary && pnpm run test && pnpm run test:smoke","lint:fix":"biome check --write src/ scripts/ tests/","dev:setup":"bun run --preload ./src/set-package-dir.ts src/entry.ts setup","typecheck":"tsc --noEmit","test:smoke":"vitest run --config tests/smoke/vitest.config.ts","dev:overlay":"scripts/dev-overlay.sh","postinstall":"node scripts/postinstall.js","build:binary":"node scripts/build-binary.js","test:e2e:acp":"pnpm run build:binary && vitest run --config tests/e2e/acp/vitest.config.ts","test:e2e:tui":"pnpm run build:binary && node scripts/run-tui-e2e.js","install:local":"node scripts/install-local.js","build:proxy-helper":"node scripts/build-proxy-helper.js","test:e2e:tui:debug":"pnpm run build:binary && node scripts/run-tui-e2e.js --debug","test:e2e:tui:trace":"pnpm run build:binary && node scripts/run-tui-e2e.js --trace","build:binary-linux-x64":"node scripts/build-binary.js --target linux-x64","build:binary-linux-arm64":"node scripts/build-binary.js --target linux-arm64","build:binary-windows-x64":"node scripts/build-binary.js --target windows-x64","test:e2e:tui:trace:replay":"node scripts/run-tui-e2e.js replay"},"_npmUser":{"name":"ache.lol","email":"npm@ache.lol"},"piConfig":{"name":"ache","configDir":".config/ache/harness"},"_resolved":"C:\\Users\\skill\\AppData\\Local\\Temp\\605ef52032fdac242bc9279412f22c16\\ache-lol-cli-0.1.98.tgz","_integrity":"sha512-p5hMhTTJFpDSIeA0+mdxFOu+0nBkb64umjxMEq1/Hjx7Z/PXgj5V3BHvotn7svt15qUvNwx9kaxvWSgd2KSSkg==","_npmVersion":"11.11.1","description":"ache — a coding agent CLI powered by Cast AI, built on Ache","directories":{},"_nodeVersion":"24.14.0","dependencies":{"tar":"^7.5.15","zod":"^4.4.3","diff":"^9.0.0","open":"^10.2.0","ssh2":"^1.17.0","uuid":"^14.0.0","yaml":"^2.8.4","shiki":"^4.0.2","undici":"^8.2.0","wcwidth":"^1.0.1","micromatch":"^4.0.8","@types/diff":"^8.0.0","@types/ssh2":"^1.15.5","shell-quote":"1.8.4","@shikijs/cli":"^4.0.2","@clack/prompts":"^1.3.0","@xterm/headless":"^6.0.0","proper-lockfile":"^4.1.2","@bulkhead-ai/core":"^0.7.0","@earendil-works/pi-tui":"0.84.1","@types/proper-lockfile":"^4.1.4","@agentclientprotocol/sdk":"0.19.2","@modelcontextprotocol/sdk":"^1.29.0","@modelcontextprotocol/ext-apps":"^1.7.1","@earendil-works/pi-coding-agent":"0.84.1"},"_hasShrinkwrap":false,"devDependencies":{"ws":"^8.20.1","tsx":"^4.21.0","husky":"^9.1.7","vitest":"^3.2.4","node-pty":"^1.1.0","turndown":"^7.2.4","@types/ws":"^8.18.1","@types/tar":"^7.0.87","playwright":"1.59.1","typescript":"^5.9.3","@types/node":"^22.19.18","@biomejs/biome":"^2.5.3","supports-color":"^10.2.2","@types/turndown":"^5.0.6","@types/micromatch":"^4.0.10","@mixmark-io/domino":"^2.2.0","@types/shell-quote":"^1.7.5","@microsoft/tui-test":"0.0.4","@earendil-works/pi-ai":"0.84.1"},"peerDependencies":{"typebox":"*"},"optionalDependencies":{"@mariozechner/clipboard-darwin-x64":"0.3.6","@mariozechner/clipboard-darwin-arm64":"0.3.6","@mariozechner/clipboard-linux-x64-gnu":"0.3.6","@mariozechner/clipboard-linux-x64-musl":"0.3.6","@mariozechner/clipboard-win32-x64-msvc":"0.3.6","@mariozechner/clipboard-linux-arm64-gnu":"0.3.6","@mariozechner/clipboard-darwin-universal":"0.3.6","@mariozechner/clipboard-linux-arm64-musl":"0.3.6","@mariozechner/clipboard-win32-arm64-msvc":"0.3.6"},"_npmOperationalInternal":{"tmp":"tmp/cli_0.1.98_1787293763176_0.5403478706090545","host":"s3://npm-registry-packages-npm-production"}},"0.1.99":{"name":"@ache-lol/cli","version":"0.1.99","description":"ache — a coding agent CLI powered by Cast AI, built on Ache","type":"module","license":"Apache-2.0","bin":{"ache":"bin/ache.js"},"piConfig":{"name":"ache","configDir":".config/ache/harness"},"dependencies":{"@agentclientprotocol/sdk":"0.19.2","@bulkhead-ai/core":"^0.7.0","@clack/prompts":"^1.3.0","@earendil-works/pi-coding-agent":"0.84.1","@earendil-works/pi-tui":"0.84.1","@modelcontextprotocol/ext-apps":"^1.7.1","@modelcontextprotocol/sdk":"^1.29.0","@shikijs/cli":"^4.0.2","@types/diff":"^8.0.0","@types/proper-lockfile":"^4.1.4","@types/ssh2":"^1.15.5","@xterm/headless":"^6.0.0","diff":"^9.0.0","micromatch":"^4.0.8","open":"^10.2.0","proper-lockfile":"^4.1.2","shell-quote":"1.8.4","shiki":"^4.0.2","ssh2":"^1.17.0","tar":"^7.5.15","undici":"^8.2.0","uuid":"^14.0.0","wcwidth":"^1.0.1","yaml":"^2.8.4","zod":"^4.4.3"},"peerDependencies":{"typebox":"*"},"optionalDependencies":{"@mariozechner/clipboard-darwin-arm64":"0.3.6","@mariozechner/clipboard-darwin-universal":"0.3.6","@mariozechner/clipboard-darwin-x64":"0.3.6","@mariozechner/clipboard-linux-arm64-gnu":"0.3.6","@mariozechner/clipboard-linux-arm64-musl":"0.3.6","@mariozechner/clipboard-linux-x64-gnu":"0.3.6","@mariozechner/clipboard-linux-x64-musl":"0.3.6","@mariozechner/clipboard-win32-arm64-msvc":"0.3.6","@mariozechner/clipboard-win32-x64-msvc":"0.3.6"},"devDependencies":{"@biomejs/biome":"^2.5.3","@earendil-works/pi-ai":"0.84.1","@microsoft/tui-test":"0.0.4","@mixmark-io/domino":"^2.2.0","@types/micromatch":"^4.0.10","@types/node":"^22.19.18","@types/shell-quote":"^1.7.5","@types/tar":"^7.0.87","@types/turndown":"^5.0.6","@types/ws":"^8.18.1","husky":"^9.1.7","node-pty":"^1.1.0","playwright":"1.59.1","supports-color":"^10.2.2","tsx":"^4.21.0","turndown":"^7.2.4","typescript":"^5.9.3","vitest":"^3.2.4","ws":"^8.20.1"},"engines":{"node":">=22.19.0"},"scripts":{"clean":"rm -rf dist","build":"tsc --noEmit && node scripts/copy-resources.js --dev","build:proxy-helper":"node scripts/build-proxy-helper.js","build:binary":"node scripts/build-binary.js","install:local":"node scripts/install-local.js","build:binary-linux-arm64":"node scripts/build-binary.js --target linux-arm64","build:binary-linux-x64":"node scripts/build-binary.js --target linux-x64","build:binary-windows-x64":"node scripts/build-binary.js --target windows-x64","dev":"make -C tools/proxy-helper/ copy-for-dev && bun run --preload ./src/set-package-dir.ts src/entry.ts","dev:overlay":"scripts/dev-overlay.sh","dev:setup":"bun run --preload ./src/set-package-dir.ts src/entry.ts setup","lint":"biome check src/ scripts/ tests/","lint:fix":"biome check --write src/ scripts/ tests/","typecheck":"tsc --noEmit","check":"pnpm run lint && pnpm run typecheck","test":"vitest run --dir src","test:smoke":"vitest run --config tests/smoke/vitest.config.ts","test:e2e:tui":"pnpm run build:binary && node scripts/run-tui-e2e.js","test:e2e:tui:debug":"pnpm run build:binary && node scripts/run-tui-e2e.js --debug","test:e2e:tui:trace":"pnpm run build:binary && node scripts/run-tui-e2e.js --trace","test:e2e:tui:trace:replay":"node scripts/run-tui-e2e.js replay","test:e2e:acp":"pnpm run build:binary && vitest run --config tests/e2e/acp/vitest.config.ts","postinstall":"node scripts/postinstall.js","verify":"pnpm run check && pnpm run build:binary && pnpm run test && pnpm run test:smoke"},"_id":"@ache-lol/cli@0.1.99","_integrity":"sha512-mBFIpCYSR3gUcuTGpWbPuaFoVlQUJL2XOKgIhSpmofeceoclfhD7cdFqmTlP2LiUHRlP0p8J2zOlx7vJvKi5Aw==","_resolved":"C:\\Users\\skill\\AppData\\Local\\Temp\\f3c36f0c4576eb6e374c264d6236c9c7\\ache-lol-cli-0.1.99.tgz","_from":"file:ache-lol-cli-0.1.99.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.11.1","dist":{"integrity":"sha512-mBFIpCYSR3gUcuTGpWbPuaFoVlQUJL2XOKgIhSpmofeceoclfhD7cdFqmTlP2LiUHRlP0p8J2zOlx7vJvKi5Aw==","shasum":"fc7a7288b6b76748c3b73c540162f62bcbc9d928","tarball":"https://registry.npmjs.org/@ache-lol/cli/-/cli-0.1.99.tgz","fileCount":69,"unpackedSize":136481288,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCWOyeLWm3WJPAf27l/7PWNX9pLxIiHxJlGOhOdqQYTvAIgYYrAhlkPkrKEVw4dITvClDWY/5CiSmCbx92VVrvekJM="}]},"_npmUser":{"name":"ache.lol","email":"npm@ache.lol"},"directories":{},"maintainers":[{"name":"ache.lol","email":"npm@ache.lol"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_0.1.99_1787294767882_0.4527041122794946"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-21T06:21:13.368Z","modified":"2026-08-21T06:46:08.945Z","0.1.97":"2026-08-21T06:21:15.026Z","0.1.98":"2026-08-21T06:29:23.888Z","0.1.99":"2026-08-21T06:46:08.774Z"},"license":"Apache-2.0","description":"ache — a coding agent CLI powered by Cast AI, built on Ache","maintainers":[{"name":"ache.lol","email":"npm@ache.lol"}],"readme":"# Ache\n\nAche is a coding agent CLI for the terminal. It's a fork of the open-source [Ache](https://github.com/getache/ache) CLI (Apache 2.0), built on the same [pi-mono](https://github.com/badlogic/pi-mono) coding agent SDK, adapted to run against [ache.lol](https://ache.lol) as its LLM provider and extended with:\n\n- A **Read / Plan / Edit / Auto** permission model (`Shift+Tab` cycles between them)\n- **Persistent, cross-session project memory** in `ache.md` + `.ache/` (`/init` to scaffold, `/memory` to inspect)\n- An Ache LLM provider alongside Ache's own, so both can be configured at once during the transition\n\nEverything Ache already does well — the terminal UI, sessions, MCP support, skills, subagents, LSP integration, Ferment project workflows — is unchanged and reused as-is. See [NOTICE](NOTICE) for full attribution; Ache does not claim Ache's original code as its own and is not affiliated with CAST AI Group, Inc.\n\n## Quick start\n\nThis repository does not have packaged releases yet — build and run it from source.\n\n```bash\ngit clone https://github.com/EOSKILLZ/ACHECLI.git\ncd ACHECLI\ncorepack enable\npnpm install\nnode ./scripts/copy-resources.js --dev\n```\n\nConfigure your API key and launch:\n\n```bash\npnpm run dev setup      # one-time interactive setup (Ache key, optional Ache key)\npnpm run dev            # launch the coding agent\n```\n\nOr build a standalone binary (see [Development](#development) below):\n\n```bash\npnpm run build:binary\n./dist/bin/ache           # or ./dist/bin/ache -- same build, both names work\n```\n\nOnce installed globally (`npm link` or similar), both `ache` and `ache` work as the command name — `package.json` registers both as aliases for the same entry point.\n\nRun `pnpm run dev -- --help` to see all available subcommands and flags.\n\n## Models\n\n### Model selection\n\nThe supported model list is fetched at startup from the ache metadata service. Use `/model` or `ctrl+p` in the interactive CLI to switch between available models.\n\nAche operates in one of two modes:\n\n| Mode | Status line indicator | Behavior |\n|------|-----------------|----------|\n| **Multi-model** | `multi-model (orchestrator-id)` | The orchestrator delegates each task to the model assigned for that role |\n| **Single-model** | model name | All work runs on the selected model directly |\n\nUse `ctrl+p` to cycle through models. The last entry in the cycle is `multi-model`. You can also open the `/model` picker and select a specific model or `multi-model` from the list.\n\nIn single-model mode the orchestration system prompt (environment, tools, research rules, guidelines, phase tagging) stays active, but task classification and delegation are disabled. The subagent tool remains available if you explicitly ask the agent to delegate.\n\n### Model roles\n\nIn multi-model mode, each task type is handled by a specific role. Each role can have one model or a **pool of candidates** — the orchestrator reads model tier and description and picks the best fit for each task.\n\nUse `/multi-model` in the interactive CLI to toggle models on/off per role, or edit `~/.config/ache/harness/settings.json` directly:\n\n```json\n{\n  \"modelRoles\": {\n    \"orchestrator\": \"ache-dev/kimi-k2.6\",\n    \"builder\": [\"ache-dev/minimax-m2.7\", \"anthropic/claude-sonnet-4-5\"],\n    \"reviewer\": \"anthropic/claude-sonnet-4-5\",\n    \"explorer\": \"ache-dev/nemotron-3-ultra-fp4\"\n  }\n}\n```\n\n| Role | Default | Description |\n|------|---------|-------------|\n| **orchestrator** | `kimi-k2.6` | Runs the main loop, classifies tasks, delegates work. Single model. |\n| **planner** | `kimi-k2.6` | Designs the approach, writes specs. When same as orchestrator, planning is done in-process. |\n| **builder** | `kimi-k2.6`, `minimax-m2.7` | Code implementation. For complex tasks the orchestrator may pick a heavier model from the pool. |\n| **reviewer** | `kimi-k2.6`, `minimax-m2.7` | Code review. Orchestrator picks the strongest by tier for initial review. |\n| **explorer** | `nemotron-3-ultra-fp4` | Codebase exploration — navigating files, reading code, tracing architecture. |\n| **researcher** | `kimi-k2.6` | Research beyond the codebase — web search, documentation lookup, external sources. |\n\nDefaults are hardcoded in `DEFAULT_MODEL_ROLES`. Roles accept any `provider/model-id` string or an array of strings. Only non-default values need to be specified; missing keys fall back to defaults.\n\n#### How delegation works\n\nThe orchestrator receives explicit per-phase directives generated from the role configuration. For each pipeline phase (plan, build, review, explore, research), the system prompt tells the orchestrator exactly what to do:\n\n- **Roles it owns** (its model ID appears in the role pool): \"DO perform this work yourself.\"\n- **Roles it does not own**: \"DO NOT perform this work yourself. Delegate to Agent(type: X, model: Y).\" — with the concrete model IDs from the pool.\n- **Review is always delegated**, even when the orchestrator has the reviewer role, to ensure independence via a fresh context.\n\nWhen a role pool has multiple models, the orchestrator picks the lightest-tier model that fits the task and escalates to heavy-tier only for complex work (concurrency, algorithms) or as a retry after a standard-tier model has failed.\n\nBuilt-in models (ache-dev) have tier and description baked in. External models need metadata — see below.\n\n#### Model metadata\n\nExternal models (Anthropic, OpenAI, or any non-builtin provider) have no built-in tier or description. Without metadata, they default to `standard` tier, `vision: false`, and an auto-generated description based on their assigned roles. To give the orchestrator better routing information, add a `modelMetadata` section to `settings.json`:\n\n```json\n{\n  \"modelRoles\": {\n    \"builder\": [\"ache-dev/minimax-m2.7\", \"anthropic/claude-sonnet-4-5\"],\n    \"reviewer\": \"anthropic/claude-sonnet-4-5\"\n  },\n  \"modelMetadata\": {\n    \"anthropic/claude-sonnet-4-5\": {\n      \"tier\": \"heavy\",\n      \"description\": \"Strong general-purpose model — use for complex builds and thorough reviews.\"\n    }\n  }\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `tier` | `standard` | `light`, `standard`, or `heavy`. Used for complexity-based routing. |\n| `description` | Auto-generated | Shown to the orchestrator so it can match model strengths to task requirements. |\n| `vision` | `false` | Whether the model supports image input. |\n\nWith the metadata above, the orchestrator will use minimax for simple build chunks and Claude for complex ones. Without it, both models look like standard-tier to the orchestrator and selection is arbitrary.\n\nMetadata can also be managed interactively via `/multi-model` → \"Edit model metadata\" — this is the only in-app path for configuring or overriding metadata, so model selection stays uninterrupted. Custom overrides can be reset to defaults from the same menu. Metadata for builtin models can be overridden the same way.\n\n#### Completion token limits\n\nAche omits Pi's estimated `max_completion_tokens` and `max_tokens` fields from requests to managed Ache providers. The gateway determines how much output fits using the model's actual tokenizer; output-budget enforcement belongs at the gateway rather than in Pi's approximate client-side context calculation.\n\n### Phase tracking\n\nAche tags every LLM request with a `phase:{name}` label for usage analytics and cost attribution. The orchestrator sets the phase as work progresses and it is displayed in the status line.\n\n| Phase | Description |\n|-------|-------------|\n| `explore` | Navigating the codebase, reading files to understand structure |\n| `plan` | Designing, breaking down tasks, writing specs |\n| `build` | Writing, modifying, or refactoring code |\n| `review` | Analyzing output, verifying correctness |\n| `research` | Investigating documentation, researching issues |\n\nSubagents inherit the current phase from the orchestrator but cannot change it.\n\n## Permission modes\n\n`Shift+Tab` cycles through four modes:\n\n| Mode | Behavior |\n|------|----------|\n| **Read** | Inspect and explain only -- no file modifications, no writes |\n| **Plan** | Plan and ask questions -- no implementation, same read-only tool restriction as Read plus the structured planning workflow (`<!-- PLAN_COMPLETE -->` menu, optional hand-off to a Ferment) |\n| **Edit** | Modify files, asks for approval before each change (this is the `default` mode internally) |\n| **Auto** | Runs freely; a classifier still gates high-risk actions |\n\nA fifth mode, **YOLO**, skips every permission check with no classifier. It's deliberately excluded from the `Shift+Tab` cycle -- select it explicitly via `/permissions mode yolo`, `--yolo`, or `--dangerously-skip-permissions` when you actually want it.\n\n## Project memory\n\nAche adds persistent, cross-session project memory on top of Ache's existing session/Ferment persistence:\n\n```\nache.md             -- concise, always-visible project overview\n.ache/\n├── architecture.md   -- technical structure, important systems\n├── decisions.md      -- architectural decisions and reasoning\n├── changelog.md       -- completed implementations, newest first\n├── tasks.md           -- current, future, and unfinished work\n└── known-issues.md    -- unresolved bugs, limitations, risks\n```\n\n`ache.md` is injected into the system prompt like `AGENTS.md`/`CLAUDE.md`. The `.ache/*.md` files are not force-injected -- the agent reads them on demand via the standard Read tool, guided by a standing system-prompt note that appears whenever `.ache/` exists in the project.\n\n| Command | Description |\n|---------|--------------|\n| `/init` | Scaffold `ache.md` and any missing `.ache/*.md` files. Never overwrites an existing file. |\n| `/memory` | Show which memory files exist, with a short excerpt of each. |\n\nThe status line shows scaffold progress as `Memory N/6` when pinned (on by default).\n\n**Updates aren't just a polite suggestion.** If a turn writes or edits files outside `.ache/` and the model\nthen stops normally without having touched `.ache/*.md` itself, it gets nudged once to consider updating\nmemory before moving on -- capped at a few nudges per session so a genuinely-not-memory-worthy change\ndoesn't get nagged forever. This mirrors Ache's existing plan-mode stop-nudge pattern.\n\n## Tags\n\nAche supports tagging LLM requests for usage tracking and cost attribution. Tags are included with every request and displayed in the status line, grouped by key with color coding.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/tags` | List all active tags |\n| `/tags add key:value ...` | Add one or more tags (e.g., `/tags add project:myapp team:backend`) |\n| `/tags remove tag ...` | Remove one or more user-defined tags |\n| `/tags clear` | Remove all user-defined tags |\n\n### Tag format\n\nTags use `key:value` format. Key and value must start and end with alphanumeric characters (middle characters may include `-`, `_`, `.`), each 64 characters max, 10 tags total.\n\n### Static tags\n\nSet via the `ACHE_TAGS` environment variable (comma-separated). Static tags are read-only within the session and shown with a `[static]` marker.\n\n```bash\nexport ACHE_TAGS=\"team:backend,project:api\"\n```\n\n### Auto-tags\n\nTwo tags are added automatically to every request and do not count toward the 10 tag limit:\n\n- `model:{model_id}` -- the model handling the request\n- `phase:{phase}` -- the current work phase\n\n### Persistence\n\nUser-defined tags (added via `/tags add`) are persisted to `~/.config/ache/tags.json` and survive across sessions. Static tags from `ACHE_TAGS` must be set each session.\n\n## Ferment -- cross-session project management\n\nFerment is Ache's progressive-refinement project mode for multi-session work. Instead of starting from scratch each chat, Ferment persists a structured plan (goal, phases, steps) as a JSON state file.\n\n### Quick start\n\n```bash\nache --ferment \"Build Tetris\"\n```\n\nOr inside an active session:\n\n```\n/ferment new \"Build Tetris\"    # create a ferment\n/ferment auto                   # keep going until done or blocked\n```\n\n### Concepts\n\n- **Ferment** -- the top-level project (e.g. \"Build Tetris\", \"Auth rewrite\")\n- **Phase** -- a milestone within the project (e.g. \"Canvas & Grid\", \"Movement\")\n- **Step** -- a single executable task within a phase (e.g. \"Create index.html\")\n- **Decision** -- an architectural choice recorded for posterity\n- **Memory** -- a gotcha, convention, or pattern encountered during work\n\n### State machine\n\nAll lifecycle transitions are validated by a deterministic finite state machine that enforces valid state changes and prevents illegal operations (e.g. completing a step before it starts, skipping an already-completed phase).\n\n```\ndraft -> planned -> running -> [paused] -> complete\n```\n\n1. **draft** -- created via `/ferment new`, agent collects goal and phases conversationally\n2. **planned** -- `scope_ferment` sets goal, criteria, constraints, phase breakdown\n3. **running** -- `activate_ferment_phase` starts a phase, agent executes steps\n4. **paused** -- user intervention required, or paused with `/ferment pause`\n5. **complete** -- all phases terminal\n\n### Continuation policy\n\nControls whether the active ferment advances across phase boundaries.\n\n| Policy | Behavior | Command |\n|--------|----------|---------|\n| **manual** | Ask before moving to the next phase | `/ferment manual` |\n| **automated** | Keep going until complete, blocked, paused, or user input is needed | `/ferment auto` |\n\nPause/resume is separate: `/ferment pause` stops the ferment, `/ferment resume` continues it using the current policy. `/ferment exit` leaves Ferment mode without deleting or abandoning the ferment; planned/running work is paused first, active Ferment UI/tools are cleared, and you can later select it from `/ferment list` or `/ferment switch`.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/ferment` | Start a new ferment via prompt |\n| `/ferment new \"Name\"` | Create new ferment |\n| `/ferment switch <id>` | Resume by ID prefix or name |\n| `/ferment delete <id>` | Delete permanently |\n| `/ferment export` | Export stats to JSON |\n| `/ferment progress` | Open phase/step navigator overlay |\n| `/ferment manual` | Set manual continuation policy |\n| `/ferment auto` | Set automated continuation policy |\n| `/ferment pause` | Pause the active ferment lifecycle |\n| `/ferment resume` | Resume the active ferment lifecycle |\n| `/ferment exit` | Leave Ferment mode without deleting the ferment |\n\n### Recovery\n\nEvery session writes a `ferment_reference` entry in the session log. On next start, the harness reads this entry and resumes from the exact state.\n\n```bash\n# Day 1\n$ ache --ferment \"Build Tetris\"\n# ... agent works, crashes, terminal closes ...\n\n# Day 2\n$ ache --ferment \"Build Tetris\"\n# -> Rehydrates state, continues Phase 2 exactly where it left off\n```\n\n### Where state lives\n\n```\n.ache/\n  ferments/\n    <uuid>.json          -- snapshot (machine-readable plan state)\n    <uuid>.events.jsonl  -- append-only audit log of every transition\n  sessions/\n    <timestamp>.jsonl    -- chat history + tool calls\n```\n\nEvery mutation is persisted as an append-only event with pre/post state hashes, enabling full auditability. Stats (phase/step counts, timing, model usage, grade distributions) are computed on demand from the snapshot and exported via `/ferment export`.\n\nFor full documentation see `docs/ferment.md` and `docs/ferment-storage-schema.md`.\n\n## LSP Integration\n\nache ships with built-in Language Server Protocol (LSP) support, giving the agent type-aware code intelligence. The extension loads by default — no configuration required.\n\n### Supported languages\n\n| Language | Server | Install |\n|---|---|---|\n| TypeScript / JavaScript | `typescript-language-server` | `npm i -g typescript-language-server typescript` |\n| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |\n\nServers are auto-detected via `which` on `PATH`. If a server binary is not found, the corresponding tools are silently unavailable.\n\n### Tools\n\n| Tool | Description |\n|---|---|\n| `lsp_diagnostics` | Get type errors, warnings, and linter diagnostics for a file |\n| `lsp_hover` | Get type information and documentation for a symbol at a position |\n| `lsp_definition` | Navigate to the definition of a symbol (supports `typeDefinition` and `implementation` variants) |\n| `lsp_references` | Find all references to a symbol across the codebase |\n| `lsp_rename` | Atomically rename a symbol across all files |\n\nThe agent is prompted to prefer LSP tools over text-based alternatives (e.g., `lsp_definition` over `grep` for navigating to definitions). File changes made via `edit`, `write`, or `read` are automatically synced to the language server.\n\n### Status bar\n\nWhen LSP servers are active, the status bar shows the server name(s) and current diagnostic error count (e.g., `LSP: typescript-language-server (3 diags)`).\n\n## Remote Sessions\n\nHand off an in-progress session to a cloud sandbox with `/teleport` — the agent keeps running when you close your laptop, switch machines, or hand off to a teammate. Resume from the CLI, the Ache console, or VS Code.\n\n> **Requires Ache CLI v0.1.52+.** Check with `ache --version`, update with `ache update`. Not available on Windows.\n\n```bash\n/teleport\n```\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/teleport [name] [flags]` | Rsync working tree to a cloud sandbox and foreground it |\n| `/remote-sessions` | Browse all workspaces and sessions; reattach with Enter |\n| `/sync up\\|down --workspace <name> --source <path> --target <path>` | Push or pull files without restarting the session |\n| `/terminal [name-or-id]` | Open a raw SSH shell on the sandbox |\n\n\n### `/teleport` flags\n\n| Flag | Description |\n|------|-------------|\n| `--workspace <id\\|name>` | Reuse an existing workspace instead of creating a new one |\n| `--git-repo <url>` | Clone from a git URL instead of rsyncing local files |\n| `--branch <branch>` | Branch to check out after cloning (requires `--git-repo`) |\n| `--allow-dirty` | Proceed with uncommitted changes |\n| `--force` | Override the 5 GB workspace size limit |\n| `--no-git-token` | Skip git credentials prompt |\n| `--skip-session` | Start remote agent fresh (don't upload current session history) |\n\n\nOnce teleported, you're in the **PTY overlay** — a fullscreen tabbed terminal. Use `Ctrl+B c` / `n` / `p` to open and switch tabs. Press `Ctrl+D` to drop back to local ache; the sandbox and agent keep running.\n\nFor full documentation see [docs.ache.dev/docs/coding-remote-sessions](https://docs.ache.dev/docs/coding-remote-sessions).\n\n## Configuration\n\n### Authentication\n\nThe Ache API key is resolved in this order:\n\n1. `ACHE_API_KEY` environment variable (takes precedence)\n2. `~/.config/ache/config.json` field `api_key`\n\nThe Ache provider key is resolved independently, so both can be configured at once:\n\n1. `ACHE_API_KEY` environment variable (takes precedence)\n2. `~/.config/ache/config.json` field `acheApiKey`\n\nRun `ache setup` (or `ache setup`) for an interactive first-time configuration, which now offers an optional Ache-key step alongside the Ache one.\n\n### Agent config\n\nAche stores its configuration (settings, sessions, models) under:\n\n```\n~/.config/ache/harness/\n```\n\n### Context files\n\nYou can provide custom instructions that are injected into the system prompt on every session. Ache discovers two kinds of context files:\n\n**Global** — applied to every session, regardless of project:\n\n```\n~/.config/ache/harness/AGENTS.md\n```\n\nPlace rules that apply everywhere (e.g., your name, code style preferences, or global tool defaults) in this file. It is loaded before any project-level files.\n\n**Project-level** — applied when working in a specific directory tree. Ache walks from the working directory up to the filesystem root and collects one context file per directory:\n\n```\nAGENTS.md\nCLAUDE.md\n```\n\nPer directory, `AGENTS.md` takes priority over `CLAUDE.md`. A `.local.md` variant (e.g. `AGENTS.local.md`) is appended to its primary file for user-specific, gitignored overrides.\n\nWhen both global and project files exist, global instructions appear first in the prompt, followed by ancestor directories, and finally the working directory. This means project-level rules can refine or override global ones.\n\n### Packages\n\nAche supports native Pi packages. `ache install npm:<package>` installs a package only for Ache, while `pi install npm:<package>` keeps the package owned by the original Pi harness. Ache can also load original Pi packages through the **Pi package lookup** resource, so both CLIs can use Pi packages without sharing Ache's install scope.\n\nIf the same package is installed in both places, the Ache install wins. Disable original Pi package lookup with:\n\n```bash\nache resources disable extensions.pi-package-lookup\n```\n\nUpdate packages with:\n\n```bash\nache update                       # update installed packages, then Ache itself\nache update --extensions          # update installed packages only\nache update context-mode          # update one package by source or display name\nache update self                  # update Ache itself only\nache update v1.2.3                # install a specific Ache release (downgrades work too)\nache update v1.2.3-rc.1           # install a release candidate\nache update --canary              # install the latest canary build from master\n```\n\n### HTTP proxy\n\nAche respects `HTTP_PROXY` / `HTTPS_PROXY` environment variables for network requests.\n\n### Token optimization (RTK)\n\nAche installs [RTK](https://github.com/rtk-ai/rtk) during setup and keeps the `rtk` command available on startup. When enabled, ache rewrites bash tool calls through `rtk rewrite` before execution. This compresses command output (git, cargo, npm, docker, etc.) by 60-90%, reducing LLM context usage.\n\nBefore every bash tool execution, ache calls `rtk rewrite \"<command>\"`. If RTK returns a rewritten command (e.g. `git status` becomes `rtk git status`), the rewritten version is executed instead.\n\n```bash\nbrew install rtk    # macOS / Linux\n```\n\nRTK rewrite is managed from resources:\n\n```bash\nache resources disable hooks.rtk-rewrite\nache resources enable hooks.rtk-rewrite\n```\n\n### Hooks\n\nUsers can add custom Bash hooks to rewrite or block shell commands before they run. Global hooks live in `~/.config/ache/harness/hooks/bash/`; project hooks live in `.ache/hooks/bash/` and default to disabled until enabled from `/resources` or `ache resources enable ...`.\n\nSee `docs/hooks.md` for the hook protocol and examples.\n\n### Migrating from another coding agent\n\nOn first run, ache looks for an existing **Claude Code**, **OpenCode**, or **Cursor** installation and offers to migrate its MCP servers. If anything is migratable you will see a one-shot prompt:\n\n```\n+  Claude Code + OpenCode + Cursor configuration found\n|\n|  MCP servers: filesystem, github, ripgrep\n|  Claude Code skills: 4 in ~/.claude/skills\n|  OpenCode skills: 2 in ~/.config/opencode/skills\n|  Cursor skills: 3 in ~/.cursor/skills\n|\n*  Migrate MCP servers to Ache?\n|  * Migrate now\n|  * Skip this time\n|  * Never ask again\n```\n\nDiscovered MCP servers are merged into `~/.config/ache/harness/mcp.json`. Existing Ache entries always win on name collisions, so re-running the migration is safe.\n\nThe prompt is only shown when something is actually worth migrating. If neither agent is installed or both are empty, the wizard skips silently.\n\n#### Sources scanned\n\n| Agent | Config files (read in order, results merged) | Skills directory |\n|---|---|---|\n| Claude Code | `~/.claude.json` (top-level `mcpServers` + per-project `projects[*].mcpServers`) | `~/.claude/skills/` |\n| OpenCode | `$OPENCODE_CONFIG`, then `~/.config/opencode/opencode.json`, `opencode.jsonc`, `config.json`, `~/.opencode.json` | `~/.config/opencode/skills/` |\n| Cursor | `~/.cursor/mcp.json`, then `~/.config/cursor/mcp.json` | `.cursor/skills/`, then `~/.cursor/skills/` |\n\nFor OpenCode, both the modern (`mcp` block) and legacy Go-binary (`mcpServers` block) schemas are supported. Servers with `enabled: false` are skipped. For Cursor, servers with `disabled: true` are skipped.\n\n#### Conflict resolution\n\nWhen the same MCP server name appears in multiple sources:\n\n1. **Within one agent**: earlier files win; project-level entries win over top-level (Claude Code); modern `mcp` block wins over legacy `mcpServers` (OpenCode); `~/.cursor/mcp.json` wins over `~/.config/cursor/mcp.json` (Cursor).\n2. **Across agents**: Claude Code wins over OpenCode, which wins over Cursor.\n3. **Against existing Ache config**: your entries in `~/.config/ache/harness/mcp.json` always win.\n\n#### \"Never ask again\"\n\nStored in `~/.config/ache/config.json` (`migrationState: \"skip-forever\"`). Delete that field to re-trigger the prompt. Adding support for another agent is a small change -- drop a new definition into `src/agent-discovery/agents/` and append it to the registry.\n\n## Development\n\n### Prerequisites\n\n- Node.js 22 (LTS)\n- [Bun](https://bun.sh/) (dev server and binary compilation)\n- [corepack](https://nodejs.org/api/corepack.html) enabled (`corepack enable`)\n- pnpm (installed automatically via corepack)\n\n### Quick setup\n\n```bash\n./scripts/dev-startup.sh\n```\n\nThis script checks and installs node, pnpm, and bun if missing, initializes git submodules, runs `pnpm install`, copies resources, and starts the harness with `pnpm run dev`.\n\n### Manual setup\n\n```bash\ngit clone git@github.com:getache/ache.git\ncd ache\n# Currently a no-op (no submodules after superpowers removal); kept for future use\ngit submodule update --init --recursive\ncorepack enable\npnpm install\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `pnpm run build` | Compile TypeScript to `dist/` and copy theme assets |\n| `pnpm run dev` | Run the CLI locally via Bun |\n| `pnpm run check` | Biome lint + TypeScript type check |\n| `pnpm run lint` | Biome lint only |\n| `pnpm run lint:fix` | Biome lint with auto-fix |\n| `pnpm run test` | Run tests with vitest |\n| `pnpm run test:smoke` | End-to-end smoke tests |\n\n### Running locally\n\nPropagate resources before first run:\n\n```bash\nnode ./scripts/copy-resources.js --dev\n```\n\nRun the CLI directly via Bun:\n\n```bash\npnpm run dev\n```\n\nOr build a standalone binary:\n\n```bash\npnpm run build:binary\n./dist/bin/ache\n```\n\n### Project structure\n\n```\nsrc/\n  entry.ts              -- Entry point\n  cli.ts                -- CLI logic & harness initialization\n  cli-args.ts           -- Argument parsing\n  config.ts             -- Auth & config loading\n  models.ts             -- Model metadata fetching & registration\n  setup-wizard.ts       -- First-run wizard\n  commands/             -- CLI subcommands (setup, login, config, update, ...)\n  extensions/           -- Agent extensions\n    agents/             -- Subagent system (personas, manager, memory)\n    orchestration/      -- Task classification, model registry, delegation\n    ferment/            -- Ferment lifecycle tools & UI\n    mcp-adapter/        -- MCP server integration\n    permissions/        -- Tool auth flows\n    behaviours/         -- Contextual prompt behaviours\n    web-fetch/          -- Web content fetching\n    web-search/         -- Web search\n    lsp/                -- Language Server Protocol\n    login/              -- OAuth flows\n    onboarding/         -- Session mode startup wizard\n  ferment/              -- Ferment state machine, event store, stats\n  modes/\n    interactive/        -- TUI harness\n    acp/                -- JSON-RPC over stdio (IDE integration)\n    teleport/           -- Remote session multiplexing\n  agent-discovery/      -- Detection & migration of other coding agents\n  config/               -- Config loading & merging\n  auth/                 -- API key management\n  utils/                -- Shared helpers\n```\n\n## Benchmarking\n\nThe `benchmark/` directory contains tools for smoke-testing ache sessions and auditing their quality.\n\n- **Manual benchmarks** (`benchmark/manual/`) -- run predefined tasks against different models and compare results. See `benchmark/manual/README.md`.\n- **Terminal-bench-2** (`benchmark/terminal-bench-2/`) -- run the [terminal-bench](https://www.harborframework.com/) suite (89 tasks) against ache inside Docker containers. See `benchmark/terminal-bench-2/README.md`.\n- **Session audit** (`benchmark/audit-session/`) -- audit a completed session for phase discipline, code quality, architecture, testing, model alignment, and cost efficiency. See `benchmark/audit-session/README.md`.\n\n## Release\n\n`pnpm run build:binary` compiles a standalone binary with `bun build --compile` (no runtime required on the\nuser's machine) and, since this fork's binary registers under two names (`ache` and `ache` -- see\n[Quick start](#quick-start)), produces **both** `dist/bin/ache` and `dist/bin/ache` from the same build\n(byte-identical copies, not symlinks, for Windows portability).\n\nSupported platforms:\n\n- macOS (amd64, arm64)\n- Linux (amd64, arm64)\n- Windows (amd64)\n\n`.github/workflows/release.yml`, `scripts/install.sh`, and `scripts/install.ps1` are adapted for this fork:\nGitHub Actions builds/verifies/uploads both binary names, release assets follow `ache_{os}_{arch}.tar.gz`\n(macOS/Linux) / `ache_windows_amd64.zip` naming with a `checksums.txt` (SHA256), and the install scripts pull\nfrom `EOSKILLZ/ACHECLI` releases by default. **Homebrew publishing was removed, not reworked** -- upstream\nAche's release pipeline pushed formula updates to `getache/homebrew-tap`, a repository this fork has no\naccess to, and no Ache-owned tap exists yet (see `.ache/decisions.md` for how to reinstate it later). Nothing\nin this pipeline has actually been run yet -- no tag has been pushed and no release has been cut.\n\nWindows build and local VM testing notes live in [`docs/windows/README.md`](docs/windows/README.md).\n\n## License\n\n[Apache License 2.0](LICENSE) -- see [CONTRIBUTING.md](CONTRIBUTING.md) for the CLA and contributor guidelines.\n","readmeFilename":"README.md"}