Set up in one prompt.
Read https://scriptonia.dev/agents.md and set up Scriptonia for this repo.Paste that into Claude Code, Codex, Cursor, or OpenClaw. Your agent runs the whole setup — you just approve one browser sign-in and answer two questions. First PLAN.md in ~3 minutes.
free tier · sample data included · you approve everything
⚠ UNRESOLVED — agent must not proceed
→ v2: RESOLVED (human-approved override)
Every override is recorded — who approved it, when, in which plan version. That's the whole approval ceremony.
One sentence, then the whole picture.
Scriptonia turns a description of a problem into a plan your coding agent can execute — grounded in what your customers actually said, what your codebase actually looks like, and what your team already decided.
You use it entirely from the terminal. There is no dashboard you have to learn first. The whole product is five words: add signal, plan an issue, hand the plan to your agent, comment if something's off.
Every claim in a generated plan links back to a real piece of signal — a Slack message, a support ticket, a sales call transcript. If your plan would contradict a decision your team already made, Scriptonia stops and asks a human before your agent writes a single line of code.
Install — nothing to configure yet.
Scriptonia is a single command-line tool distributed on npm. You need Node.js 18 or newer — if you can run node --version in your terminal and see a number, you have it.
Run it directly with npx — no install step, always the latest version:
If you'll use it often, install it globally so the scriptonia command is always available without the npx prefix:
scriptonia — if you didn't install globally, just prefix every command with npx: npx scriptonia login.60 seconds, start to finish.
This is the entire product, run once. Everything after this section explains each step in depth.
That's it. Step 4 is wherever you already do your building — Claude Code, Codex, Cursor, whatever you use. Scriptonia's job ends at a file called PLAN.md sitting in your repo, ready to be executed.
The four moves you'll make, forever.
Everything you do with Scriptonia is one of these four things, in this order, on repeat:
You never approve a plan by clicking a button. Handing it to your agent — running claude "execute PLAN.md" — is the approval.
Adding signal — what customers actually said.
Signal is any piece of text that reflects a real customer, user, or teammate's reality: a support ticket, a Slack rant, a sales call transcript, a one-line note you typed into your phone at 2am. The more signal you add, the better Scriptonia's plans get, because every claim in a plan has to point back to something real.
Three ways to add it
1. Paste it directly, as an issue. This is the fast path — a single sentence or paragraph, quoted:
context.md file showing what it found — cited signal, and any contradiction with a past decision. See The brain, file by file.2. Point it at files. Text files, markdown notes, call transcripts (.vtt/.srt):
Scriptonia guesses the source type from the file extension (a .vtt or .srt file is treated as a sales call; everything else defaults to a founder note). Override it with --source if the guess is wrong.
3. Pipe it in. If your signal is already in another tool, pipe it straight through — no temp file needed:
Flags
What happens after you add it
Every signal is embedded and stored so it can be retrieved later by meaning, not just keyword — asking about "filtering audit logs" will find a ticket that said "can't see who did what" even though the words don't match. Adding the same file twice is safe: Scriptonia recognizes duplicates and won't double-count them.
Generating plans — the money command.
scriptonia plan is the whole point of the product. You describe an issue in plain language; Scriptonia retrieves the signal that supports it, checks it against every decision your team has made in the past, and writes a single markdown file — PLAN.md — that your coding agent can execute with no follow-up questions.
Reading PLAN.md
A generated plan always has the same seven sections, in this order:
Two things in that file matter more than the rest:
- Non-goals. This is the fence that keeps an agent from over-building. If it's not in the acceptance criteria, it doesn't belong in the PR.
- ⚠ UNRESOLVED. This means your plan conflicts with something your team already decided. Your agent should stop and wait for a human — see Refining with comments for how to clear it.
Flags
Finding a plan's slug
Every plan gets a short identifier derived from its title. List everything you've generated:
Refining with comments — the human-in-the-loop.
A generated plan is a first draft, not a final answer. If a reviewer notices something — a missing edge case, a wrong default, or explicit approval to override a past decision — leave it as a comment on the plan. The whole plan regenerates with that note folded in, as a new version.
PLAN.md is rewritten in place with the comment absorbed — you don't diff two files, you just re-open PLAN.md.
Clearing an ⚠ UNRESOLVED gate
If a plan says a constraint is unresolved, that means it conflicts with a decision on record and no one has approved overriding it yet. A human — usually whoever owns that decision — approves it the same way, in plain language:
In PLAN.md, that constraint now reads:
comments/plan/<slug>/ in the brain reference).Attributing a comment to someone else
By default a comment is attributed to your signed-in email. Override it with --as:
The brain, file by file. what your agent actually reads.
Running scriptonia init inside a repository gives that project its own brain — a folder of plain markdown and JSON files at ~/.scriptonia/projects/<your-project>/. Nothing in here is a database you need a tool to read; every file is something you or your agent can open directly.
The directory, annotated
Notice what's not there: no vector index, no embedding cache. Those live on Scriptonia's servers — the brain folder on your machine is the human- and agent-readable surface, not a copy of the database.
Keeping it fresh
contexts/ and rules/ are snapshots — they update when you run sync, not automatically on every add. Run it after you've added a batch of signal or after a teammate has recorded a new decision:
context.md and plan.md, by contrast, are always current — they're overwritten every time you run add "…" or plan.
PLAN.md itself and a small section in AGENTS.md — see the next section.Agent integration — works with what you already use.
scriptonia init (or your first scriptonia login) writes a section into your repo's AGENTS.md file — the emerging standard that Claude Code, Codex, Cursor, OpenClaw, and Hermes all read automatically before they start working. You don't configure each tool separately.
This section is idempotent — re-running init updates it in place between the same markers, without disturbing anything else you've written in AGENTS.md.
Claude Code specifically
On top of AGENTS.md, logging in also installs a dedicated skill to ~/.claude/skills/scriptonia/SKILL.md so Claude Code knows to reach for scriptonia plan before it starts any user-facing work, without you saying anything. Reinstall it any time (for example after an update) with:
MCP-native agents
If your agent speaks the Model Context Protocol instead of reading AGENTS.md, point it at Scriptonia as an MCP server:
This exposes three tools using your already-stored login — get_context, link_back, and flag_contradiction. No extra configuration; it reads the same credentials scriptonia login already saved.
Full command reference.
Every command the CLI supports, grouped the way you'll actually reach for them.
SETUP
SIGNAL
PLANS
INSPECT
ACCOUNT
Working across repos — for people juggling more than one project.
If you only ever work on one product, you don't need scriptonia init at all — login → add → plan uses your account's default project, and plan will still scan whatever directory you run it in for file paths.
If you work across several repos — different products, or client work where signal must stay separated — run scriptonia init once inside each one. Scriptonia recognizes which project you're in automatically based on your current directory, so every command after that just works without you specifying anything:
Each repo's brain lives in its own folder under ~/.scriptonia/projects/, with its own signal, its own decisions, its own plan history. Nothing crosses between them.
When something doesn't do what you expect.
The CLI is waiting on a local callback (a temporary web server on your machine, port picked automatically) for up to two minutes. If it times out, just run scriptonia login again. If your firewall or VPN blocks local loopback connections, this is the most common cause — try again with the VPN off.
This means nothing in the brain closely matched your issue description yet. Two likely causes: you just added signal and it's still being processed (wait roughly a minute and re-run scriptonia plan), or your issue description uses very different words than any signal you've added — try rephrasing closer to how a customer actually said it, or add more signal on the topic first.
Run scriptonia plans — it lists every plan you've generated along with the exact scriptonia comment plan/<slug> command, ready to copy.
Add --force: scriptonia init --force. This re-scans your codebase and refreshes the repo map without losing any signal, plans, or history you already have.
That's expected — Scriptonia treats identical signal as a duplicate on purpose so re-running scriptonia add on the same folder never double-counts your signal.
Your session has expired or you're on a machine you haven't signed into. Run scriptonia login — it takes about ten seconds and re-wires everything, including any per-repo brains you'd already set up.
Questions people actually ask.
To run the CLI commands, no — they're plain English in, a file out. Step 4 (handing PLAN.md to an agent) is where code gets written, and that part is your coding agent's job, not yours.
Signal you add is stored on Scriptonia's servers so it can be searched by meaning across your whole history. The brain folder on your own machine (~/.scriptonia/projects/…) is local — the only thing that ever gets written into your actual repository is PLAN.md and the small AGENTS.md section.
query is a quick lookup — "what have customers said about X" — and returns structured JSON in a second. plan is the full treatment: it also checks decisions, writes a complete PLAN.md with acceptance criteria and file-level steps, and is what you hand to an agent.
You can, but it won't be remembered — the next scriptonia plan --refresh or comment will overwrite it. If you want a change to stick and be part of the plan's history, leave it as a scriptonia comment instead.
Each comment regenerates the plan into a new version with everything folded in so far — comment history is kept in comments/plan/<slug>/ as one file per version, so you can see exactly which note produced which change.
The CLI ships first, on purpose — it lives where your agent lives. Want one of these sooner? Tell me.
Something missing from this page? Tell us and we'll add it.