scriptonia

Turn customer signal into executable plans your coding agent runs. An issue goes in; a hyper-focused, sourced, contradiction-checked PLAN.md comes out — your agent (Claude Code, Codex, OpenClaw, Hermes) executes it into a PR.

Quick start

npx --yes scriptonia@latest doctor
npx --yes scriptonia@latest login
cd /absolute/path/to/the/committed-git-repository-root
npx --yes scriptonia@latest init
npx --yes scriptonia@latest brain status --check
npx --yes scriptonia@latest add feedback.txt call.vtt notes.md
npx --yes scriptonia@latest plan "let compliance filter the audit log by actor"

A browser opens during login; credentials are stored locally (you never see a key), and the Claude skill is installed. init is a separate, required step run from the exact Git root you want bound. It writes that repository's managed AGENTS.md contract and builds its first structural brain. Do not continue until brain status --check reports READY, fresh, and coverage PASS.

If you are inside a subdirectory, print and enter the root first:

git rev-parse --show-toplevel
cd /the/exact/path/printed/above

The final command writes PLAN.md: goal, cited evidence, non-goals, real file paths, and acceptance criteria. Hand that file to your coding agent.

Left a review note? The plan regenerates:

npx --yes scriptonia@latest comment plan/<slug> "default to all actors, and gate behind the admin role"
# → PLAN.md v2 with your note folded in

The loop

| step | command | what happens | |---|---|---| | SIGNAL | npx --yes scriptonia@latest add <files> | Ingest text · md · vtt as customer signal (deduped, auto-sourced). | | PLAN | npx --yes scriptonia@latest plan "<issue>" | Retrieve cited brain evidence, prove full-census file presence/absence, check prior decisions, and write PLAN.md; contradictions stay UNRESOLVED until a human approves. | | BUILD | claude "execute PLAN.md" | Your agent implements against the plan's cited criteria and Non-goals fence. | | REFINE | npx --yes scriptonia@latest comment plan/<slug> "…" | A note regenerates the plan (v+1). A comment approving an override flips a contradiction to RESOLVED. | | VERIFY | npx --yes scriptonia@latest verify | Freeze the Git/product-memory snapshot and consume declared CI/JUnit/static evidence. It never executes repository commands. |

Build the codebase brain

Run the credential-free structural build once in each repository. It performs a full census and real Tree-sitter analysis, stores the evidence in an immutable SQLite generation, and activates projections only if coverage and reference-integrity gates pass.

Deep Brain requires a Git repository with a committed HEAD so it can prove freshness and bind every generation to an exact checkout. If you downloaded a project as a ZIP, create a safe empty baseline first; this does not stage the project files:

git init
git commit --allow-empty -m "Initialize repository"

npx --yes scriptonia@latest brain build --fast --offline
npx --yes scriptonia@latest brain status --check
npx --yes scriptonia@latest brain context "trace checkout authorization and totals"
npx --yes scriptonia@latest why source/path/to/file.ts

After the first build, npx --yes scriptonia@latest brain build --offline is incremental. For cited model enrichment, use npx --yes scriptonia@latest brain build --deep after login and repository binding; the API credential remains on the Scriptonia server.

Commands

setup     login                     init [per repo]
signal    add <files>               (--source, --segment, or pipe text to add -)
plan      plan "<issue>"            (--out <file>, --refresh <slug>)
          plans                     list plans + their slugs
          comment plan/<slug> "…"   refine → regenerates PLAN.md
capture   run -- <agent-command>      capture exactly the command supplied
          runs | run show <id>        inspect captured agent sessions
verify    diff-check [--base <ref>]   sub-second deterministic policy pass
          verify [--base <ref>]       complete evidence report
          gate [--base <ref>]         CI-compatible aggregate exit status
learn     learn <finding-id>          confirmed finding → draft eval
          eval run [id] | eval doctor run and maintain regression cases
memory    decide | pulse | why | recall local-first product/codebase memory
brain     brain build | brain status | brain context "<task>"
                                         build, inspect, and retrieve cited task context
doctor    doctor                     diagnose Node, SQLite, parser assets, Git, and brain state
inspect   scriptonia                the loop + what's next
          contexts | query "<topic>" | link "<id>" | sync
account   status | logout | skill | mcp

Diagnose an install

Run this from any folder; it does not use the network or require a Git repository:

npx --yes scriptonia@latest doctor

It checks the supported Node range, the installed better-sqlite3 native binding, packaged Tree-sitter grammars and queries, Git/ripgrep availability, and the active local brain when run inside a repository. If Node was upgraded after installation, doctor prints the exact reinstall or rebuild command instead of exposing a native loader stack trace.

Platform support

Scriptonia is fully validated and release-gated on Linux and macOS (Node 22, 24, and 26). Windows is limited/experimental support: core commands (login, init, plan, logout) work, but the deep-brain build pipeline (brain build --deep) has known POSIX assumptions that are not yet validated on Windows, and generated projection paths may differ. For the deep-brain experience today, use Linux/macOS or WSL. Windows validation is tracked as follow-up work.

One brain per repo (for people juggling projects)

npx --yes scriptonia@latest init at the exact committed Git root gives that repository its own brain at ~/.scriptonia/projects/<slug>/, builds the credential-free Deep Brain, and writes an AGENTS.md section. The compatibility REPO.md in that project is an exact copy of the activated full-census, Tree-sitter-backed projection at .scriptonia/REPO.md; init does not create a second shallow repo map. Customer signal you submit is stored and embedded on Scriptonia's servers; it is not written into the repository. V2 policies, eval definitions, and operational brain data are local-first. Deterministic verification does not upload the codebase. When semantic evaluation is explicitly enabled, only the bounded evidence bundle is sent through the authenticated Scriptonia gateway.

init is required for every repository. login authenticates the account and installs the Claude skill; it does not bind a repository or write AGENTS.md. Running from an unbound parent, child, or sibling repository is rejected so a plan cannot silently use the wrong codebase.

Recover from connected-build or plan errors

If connected Deep Brain enrichment reaches its time budget, the failed attempt does not replace the active READY generation. Inspect it, retry once, or use the fully local fallback:

npx --yes scriptonia@latest brain status --check
npx --yes scriptonia@latest brain build --deep
npx --yes scriptonia@latest brain build --deep --offline

If plan reports an HTTP 422 structured-output/schema error, that is a Scriptonia service/product fault, not a repository fault. No PLAN.md is overwritten. Confirm you are running @latest, retry once, and contact support with the request id if it persists; do not delete .scriptonia/brain.db or edit the generated schema as a workaround.

For MCP-native agents

{ "command": "npx", "args": ["--yes", "scriptonia@latest", "mcp"] }

Exposes get_context, link_back, flag_contradiction from your stored login.

Self-hosting

Defaults to https://scriptonia.dev. Point elsewhere with SCRIPTONIA_URL=https://your.host npx --yes scriptonia@latest login (or --url). Node 24 LTS is the V2 release baseline; Node 22 remains in the compatibility matrix.