智能CLI工具

Install

```bash pip install simplicio-cli # from PyPI (pulls simplicio-mapper + simplicio-prompt)

stderr: "simplicio: auto-activation installed in Claude Code …"

Opt out before the first call:

**Explicit path.** Same effect, no auto-magic:

Either way, two files land in ~/.claude/:

A backup of your previous settings.json is written to settings.json.bak before any merge.

Path 1 example — inside Claude Code

After pip install simplicio-cli && simplicio smoke (which triggers auto-bootstrap), just type your task in Claude Code:

hide the Delete button for non-admins in src/app/screen/screen.component.html

Claude Code sees the skill (semantic match) and the hook hint ([SIMPLICIO_PROMPT_HINT] on stderr — deterministic classifier). It runs simplicio's 6-layer contract under the hood. You see the diff + tests + verification — same as before, just dramatically more accurate.

Path 2 example — subscription shell-out, zero key

You already pay for Claude Pro/Max or ChatGPT Plus + Codex CLI. simplicio piggybacks on that login — no extra bill, no key to manage.

```bash

Path 3 example — standalone with API key

export SIMPLICIO_API_KEY=sk-or-v1-…                      # OpenRouter key
export SIMPLICIO_MODEL=anthropic/claude-opus-4
export SIMPLICIO_BASE_URL=https://openrouter.ai/api/v1

simplicio index --stack angular                           # one-time, builds embedding cache
simplicio task "hide Delete button for non-admins" \
  --stack angular \
  --target src/app/screen/screen.component.html \
  --criteria "- no admin perm: button absent from DOM
- with admin perm: button present" \
  --constraints "- don't touch save flow
- build passes"

Provider-agnostic — see Configure for the full matrix.

---

Option A — Claude Code subscription (run `claude login` once)

export SIMPLICIO_MODEL=claude-cli/sonnet # or claude-cli/opus, claude-cli/default unset SIMPLICIO_API_KEY # explicitly: no key needed

simplicio task "hide Delete button for non-admins" --stack angular \ --target src/app/screen/screen.component.html

Option B — Codex CLI subscription (run `codex login` once)

export SIMPLICIO_MODEL=codex-cli/gpt-5 # or codex-cli/default simplicio task "..." --stack angular --target ...

How it works: simplicio shells out to `claude -p "<prompt>"` (or `codex exec "<prompt>"`) as a subprocess, captures stdout, runs the test loop. The inner CLI authenticates via your existing OAuth session in `~/.claude/` or `~/.codex/`. simplicio sets `SIMPLICIO_HOOK_GUARD=1` in the subprocess env so the inner Claude Code session does **not** re-fire simplicio's own UserPromptSubmit hook (no infinite recursion).

For orchestrators such as SendSprint, `simplicio task` also has a structured
contract:

simplicio task "front-only task" \ --stack angular \ --target src/app/screen/screen.component.html \ --bound-paths "src/app/**" \ --json ```

--dry-run-task generates the would-be diff/test output without applying or testing it. --json returns `{task_id, applied, files_changed, tokens_used, cost_usd, diff_summary, warnings}. Repeat --bound-paths <glob>` to reject diffs outside the allowed edit surface; violations are reported in warnings and the command exits non-zero.

Configure — any LLM, nothing hardcoded

Applies to Path 2 (standalone CLI). Path 1 users can skip this entire section — Claude Code handles the LLM call with the model and key already tied to your subscription.

If SIMPLICIO_BASE_URL is unset and the key is ANTHROPIC_API_KEY, it uses the native Anthropic SDK. Otherwise it uses an OpenAI-compatible client pointed at your base_url — so any OpenAI-like provider works without code changes.

simplicio smoke      # prints provider config + one test call

Rich mapper integration

When simplicio-mapper has generated .simplicio/project-map.json and .simplicio/precedent-index.json, simplicio-cli consumes them directly:

• exact target file metadata, roles, imports and exports
• entry points, test files, modules, entities and architecture signals
• recent changes and changed-file context
• precedent snippets ranked from precedent-index.json

If those artifacts are missing, the CLI falls back to the older target-file inspection path, so existing projects keep working.

The pipeline (both paths)

Whichever entry point you use, each task runs through the same engine:

precedent (from cache)
  → skill match
  → 6-layer prompt
  → LLM generates diff + test + Playwright
  → apply diff
  → run SIMPLICIO_TEST_CMD
  → pass?  done  :  send the error back → fix → retry (up to 3x)

The 6-layer contract is what moves pass-rate from 41% to 99% on frontier models (see the numbers above). The retry loop is what catches the remaining edge cases — measured separately in the 4-quadrant bench.

Common questions

"I have a Claude Pro subscription but no API key — does this work?" Yes, on Path 1. Install simplicio-cli, open Claude Code, type your task as normal. Claude Code makes the LLM call with your subscription; simplicio shapes the prompt. No key needed.

"I want to run it in CI / a script / outside Claude Code." Path 2. Get an API key from any of the providers above (OpenRouter is the cheapest way to try multiple models behind one key), set SIMPLICIO_API_KEY + SIMPLICIO_MODEL + optional SIMPLICIO_BASE_URL, run simplicio task ....

"How do I load .env.local safely before running a local API?" Use eval "$(simplicio env-export .env.local)" instead of source .env.local. This preserves values with semicolons, such as PostgreSQL connection strings, without executing the dotenv file as shell code.

"I have Codex CLI / ChatGPT Plus and don't want to pay for an API key." Not auto-wired yet. Workarounds: (a) get an OpenRouter key (~$2 covers thousands of tasks at small-model rates), (b) wait for the shell-out provider that pipes through claude -p / codex exec using your subscription — tracked, not shipped.

**"Will Claude Code use simplicio for every prompt now?"** No. The skill only triggers on prompts that look like code edits (the description is specific). The hook fires simplicio detect on every prompt but only emits a hint when the deterministic classifier scores ≥ 3 (verbs + file extensions + code nouns − read-only cues). "What does this function do?" gets no nudge. "Add a delete confirmation to UserList.tsx" does.

"How do I turn it off?" See Disable / re-enable above. Two ways: env var (SIMPLICIO_SKIP_AUTO_INIT=1 before first call) or delete the hook entry from ~/.claude/settings.json.

---