run-sii
Skill19 starsChanged 7 days agoMITView on GitHub
Build, run, smoke-test and drive the sii CLI, the sii-mcp stdio server and the core tasks locally, without touching production SII or ~/.sii. Use when asked to run, start, try, smoke-test or exercise the CLI / MCP server / a core task, or to check that a change works in the built binaries and not only in vitest.
- Installs packages
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cfd-upgradeSkill
- issue-newSkill
- issue-startSkill
- new-decisionSkill
- review-prSkill
- session-closeSkill
- session-startSkill
- telemetry-reportSkill
- validate-contextSkill
The file
Files
sii is a CLI (packages/cli), an MCP stdio server (packages/mcp) and the core they share
(packages/core). The agent path is driver.mjs in this skill. It runs the BUILT binaries
with SII_HOME set to a scratch dir, speaks JSON-RPC to the MCP server, and calls core tasks
against the core's own fakes (testing). Paths below are relative to the repo root;
.claude/skills is a symlink to .agents/skills, so either path works.
Build
pnpm install --frozen-lockfile
pnpm buildThe driver reads packages/*/dist. Rebuild after every source change, or it runs stale code.
Run (agent path)
One command checks everything: CLI, MCP handshake + a tool + a resource, a core task vs fakes.
node .claude/skills/run-sii/driver.mjs smokeIt prints PASS/FAIL per check and exits non-zero on any failure. Pieces:
D=.claude/skills/run-sii/driver.mjs
node $D home --reset --seed # fresh scratch SII_HOME + a synthetic session (11111111-1)
node $D cli auth status # any sii args; JSON on stdout, exit code preserved
node $D cli --human operate --list
node $D cli f29 submit --help # --help of any verb is offline
node $D mcp tools # tool names (32 today)
node $D mcp resources # sii://session, sii://operating, sii://operable, sii://config
node $D mcp read sii://operating
node $D mcp call auth_status
node $D mcp call operate '{"list":true}'
node $D core whoami # a domain task vs FakePortalDriver: result + audit entriesDirect invocation is the path most PRs need. Most PRs touch a portal facade or a task,
and those only run against fakes. core whoami in driver.mjs is the template: build a
Runtime from testing.FakePortalDriver / FixedClock / RecordingAuditSink /
InMemoryKeyValueStore, call testing.seedSession, call the task. Script the fake with
requestJson / requestText / requestBinary for the surface you changed. Copy a fixture
from that module's *.test.ts.
Run (human path)
node packages/cli/dist/main.js --helpReal use needs a real session (sii auth login, which prompts for the Clave). That is the
owner's to run, never an agent's: a failed login counts toward SII's account lock.
Test
pnpm test
pnpm vitest run packages/core/src/auth/auth.test.tsGotchas
- Anything past a local read hits production SII. The driver refuses it unless the
arguments start with
--live(CLI) or end with--live(MCP call). Offline:--help/--version,auth statuswithout--refresh,operate, MCPauth_status/operate, every resource. The seeded session has an EMPTY jar, so a live read on it just bounces (session_expired). It is still a real request to SII, so don't do it casually. - Never point the driver at the real
~/.sii.SII_RUN_HOMEmoves the scratch home, and the driver refuses~/.sii. The real session, theoperatepointer, the login latch and the audit log all live there. SII_HOMEmust be absolute. A relative value is avalidationerror (exit 1) before any command runs.- An MCP tool's JSON is a STRING inside
content[0].text, the same objectsii <cmd>prints.JSON.parseit. A failed call hasisError: trueand its text is the error object{ error, type, … }. - The
operating as:header goes to STDERR and appears only with--human. In JSON mode stdout carries the result alone. seedSessionmust run withSII_HOMEalready set.createNodeRuntime()picks the store directory when it is built. The driver'shome --seeddoes that.- 3 test files skip unless
SII_F29_CAPTURESpoints at private captures (never committed). "3 skipped" inpnpm testis normal.
Troubleshooting
driver: …/dist/main.js missing→ runpnpm build.driver: \sii<verb>…` reaches production SII; pass --live` → working as designed. Use a core-vs-fakes call instead, or ask the owner before going live.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

