{"id":"65bee8a3-53be-4569-bb19-95afa77a8cc0","slug":"scroll","kind":"mcp","name":"scroll","summary":"SCROLL - a harness for agentic loops. Build AI agents as folders, not code.","owner":"LeHungViet","repoUrl":"https://github.com/LeHungViet/scroll","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-01T06:34:11.000Z","addedAt":"2026-10-21T09:04:00.648Z","logoUrl":"https://avatars.githubusercontent.com/u/11349635?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["agent-harness","agentic","agentic-loops","ai-agents","autonomous-agents","llm","loop-engineering","vendor-neutral"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T03:44:03.511Z","sample":false,"url":"https://conduits.dev/tools/scroll","language":"JavaScript","transports":["stdio"],"install":{"npm":"@agentpro/scroll"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<!-- This is the PUBLIC, publishable README — the face of the framework devs see. EN by default (global dev audience). VN version available on request. -->\n\n# 📜 SCROLL — a harness for agentic loops\n\n**Build AI agents as folders, not code.** A filesystem-native harness: an agent is a directory of markdown, the LLM does the work, a thin CLI coordinates. No engine, no database, no runtime lock-in. Runs the same locally and in the cloud — and gives you the **outer loop** (loop engineering) so an agent finds its own work, does it, verifies it, and remembers it, without you prompting each turn.\n\n```bash\nnpm i -g @agentpro/scroll\nscroll new researcher                 # scaffold a compliant agent (L1-ready: hard-rules + 3 gold evals)\nscroll build researcher               # render it for Cowork / Codex / Gemini / voice\nscroll run  researcher --task \"…\"     # inner loop: one harnessed run — capped, gated, checkpointed\nscroll loop LOOP.md                   # outer loop: schedule + find work + stop conditions\n```\n\n`MIT` · `Node ≥ 20` · **Spec v1.6** · **`@agentpro/scroll` 0.11.0** · vendor-neutral — runs on Claude · OpenAI/Codex · Gemini · Grok\n\n> **GitHub topics:** `loop-engineering` · `agent-harness` · `agentic` · `agentic-loops` · `ai-agents` · `autonomous-agents` · `llm` · `mcp`\n\n---\n\n## Why SCROLL\n\nMost agent frameworks make you import a heavy runtime (graphs, schedulers, vector DBs) and lock you to one model vendor. SCROLL bets the opposite way:\n\n| | Heavy frameworks | **SCROLL** |\n|---|---|---|\n| An agent is… | an object in code | **a folder of markdown** |\n| State lives in… | a database / session | **the filesystem + git** |\n| Orchestration | the framework runtime | **a declarative DAG you advance deterministically** |\n| Safety | hope the model behaves | **risk-tiered gates + grounding, enforced in code** |\n| Model | locked to one vendor | **vendor-neutral — one definition, any runtime** |\n| The whole framework | a dependency tree | **a convention + one small CLI** |\n\nThe thesis in one line: **SCROLL doesn't try to make the model smarter — it makes the model's built-in weaknesses unable to cause harm.** Every mechanism below compensates for a specific model failure mode.\n\n| Mechanism | The model weakness it neutralizes |\n|---|---|\n| Risk-tiered permission matrix | the model doesn't understand *consequences* |\n| Grounding pre-check | *hallucination* (inventing ids / amounts) |\n| Tool-boundary enforcement | *sycophancy* — it can't be trusted to stop itself |\n| External eval (gold cases) | biased self-assessment |\n| Comprehension digest | the *user's* passive over-delegation |\n\n---\n\n## Implementation status (2026-07-15 · v1.6)\n\n**Built & tested** (`test/` — **73 checks green**: 9 core + 14 runtime + 16 v1.4 + 6 v1.5 + 10 v1.6 + 11 installers + 7 audit):\n\n- **§28 Effect confirmation** — a write is not \"done\" because the call returned a non-error. `lib/effects.js` re-reads the state with a **separate** probe and checks a declared predicate; a mismatch emits `effect_unconfirmed` and fails the step. `financial`/`destructive` writes with no `confirm` are blocked (fail-closed) and flagged by `scroll audit`. Corollary: an unknown input field is rejected, never dropped — silently dropping input is how a system reports success for work it never did.\n- **§29 Ungraded is not pass** — `verdict` is ternary (`pass | fail | ungraded`). \"No check ran\" is counted separately and never folded into `ok`; a judge that could not run says nothing, so it grades `ungraded` rather than `fail`.\n- **§30 Fixture provenance** — gold cases declare `fixture.provenance` (`product-path | recorded | synthetic`); `scroll eval` prints it beside every verdict and `scroll audit` flags a suite built only on hand-made fixtures — the shape where a scheduler's *execute* path is green while its *arm* path was never run once.\n\n- **Inner loop** `scroll run` — deterministic DAG advance from `WORK.md`, single controller, cost-gate, append-only `blackboard/`, hard caps + circuit breaker, stable-prefix caching, model routing, deterministic non-LLM steps, verify-before-done, per-tick checkpoint, `events.jsonl`.\n- **Risk-tiered permissions** — five tiers (`read_only · reversible_write · external_comm · financial · destructive`), enforced at the **action boundary in code** (not the prompt). Risk is declared as data in `.mcp.json` / `IDENTITY.security`, never read from prose.\n- **Grounding pre-check** — before a `financial`/`destructive` action, every critical parameter must trace to a real prior source; a fabricated id/amount **never executes**.\n- **Outer loop** `scroll loop` + `LOOP.md` — schedule, work-source, and stop conditions for self-directed runs. A loop with no stop condition is refused.\n- **Comprehension digest** — every run writes a human-readable `digest.md` from the event stream (no model call), language-aware.\n- **`scroll eval`** — gold cases run N times → machine checks + consistency (`pass^k`) + optional LLM-judge + hash-bound record. **(built — earlier docs called this roadmap; it ships.)**\n- **Per-language token budgeting** — `scroll cost` / the cost gate scale by language (Vietnamese ≈ 1.8× English).\n- **Worktree-lite isolation** — parallel tasks get isolated working dirs (real `git worktree` with `--worktree` on a repo) so two agents never corrupt shared state.\n- **Crash-resume** — `scroll run --resume` restores completed tasks from the checkpoint and finishes the rest **without re-billing**.\n- **`scroll audit`** — convention scan + hash-bound compliance report (CI; `--verify`).\n- **Extension installers** — `scroll mcp add` (wire an MCP server/connector into `.mcp.json`, with `${vault:KEY}` credentials + per-tool risk tiers), `scroll skill add` (install or scaffold a `SKILL.md` skill, attach it to an agent), `scroll plugin add` (unpack an agent-pack bundle: agents + skills + merged `.mcp.json`).\n\nProviders: `mock` (offline) · `codex` · `claude` · `openai` · `anthropic` · `gemini`. On a case-gated live A/B eval the runtime cut billable tokens **50–88%** and latency **50–75%** vs an unstructured baseline, at equal-or-better quality.\n\n**Roadmap:** AG-UI / OpenTelemetry event emission · storage adapters (S3/GCS/repo) · registry-backed discovery for `mcp add`.\n\n---\n\n## Quickstart\n\n**1. Install** — `npm i -g @agentpro/scroll`\n\n**2. Create an agent** — `scroll new` scaffolds a correct, **L1-ready** folder:\n```\nagents/atlas/\n├── IDENTITY.md      # who it is + security (risk tiers) — machine-readable frontmatter\n├── SOUL.md          # how it thinks (you write this part)\n├── TOOLS.md         # what it can use\n├── hard-rules.md    # rules it must never break\n├── memory/          # what it remembers\n└── evals/           # 3 gold cases — graded by `scroll eval`\n```\n\n**3. Build, run, loop:**\n```bash\nscroll check atlas             # validate structure (pre-commit + CI)\nscroll build atlas             # → Cowork / Codex / Gemini / Claude-subagent / A2A\nscroll run   atlas --task \"…\"  # inner loop: deterministic, capped, gated, checkpointed\nscroll loop  LOOP.md           # outer loop: scheduled, self-directed, with stop conditions\n```\n\n---\n\n## Inner loop vs. outer loop (loop engineering)\n\nThe shift the field is naming **loop engineering** is from writing prompts to designing the *system that prompts the agent*. SCROLL gives you both halves explicitly:\n\n- **`scroll run` — the inner loop.** One harnessed execution of a `WORK.md`: advance the DAG, act inside a step, verify, checkpoint.\n- **`LOOP.md` + `scroll loop` — the outer loop.** Defines **when** to start an inner loop (`schedule`), **where** it finds work (`work_source`), and **when to stop** (`stop_conditions` — required). It rides your host scheduler (cron / scheduled-tasks); there's no daemon engine.\n\n```yaml\n# LOOP.md\nid: market-watch-daily\ncontroller: lead\nschedule:       { cron: \"0 7 * * *\" }\nwork_source:    { type: work_file, query: WORK.md }\nstop_conditions:{ max_runs_per_day: 4, budget_usd_per_day: 5, halt_on: [gate_denied, verify_fail] }\ndigest: required\n```\n\nThe outer loop **never escalates privilege** — every action inside still passes the permission matrix below — and writes a digest after every run.\n\n---\n\n## Safety: risk tiers + grounding, enforced in code\n\nA model is sycophantic and prompt-injectable, so it can't be trusted to stop before a dangerous action. SCROLL puts the gate in **deterministic code, in front of the action**.\n\n**Five tiers, lowest → highest consequence**, each mapped to a policy:\n\n| tier | default policy |\n|---|---|\n| `read_only` | auto |\n| `reversible_write` | auto + log |\n| `external_comm` | soft-hold |\n| `financial` | must-approve **+ grounding** |\n| `destructive` | must-approve **+ grounding** |\n\nRisk is **data, not prose** — declared per-tool in `.mcp.json` or per-namespace in `IDENTITY.security` (a label a model can read is just another prompt it can be talked out of):\n\n```yaml\n# IDENTITY.md\nsecurity:\n  risk_defaults: { fs.read: read_only, shell.exec: destructive, mcp.*: external_comm }\n  approval:      { financial: must-approve, destructive: must-approve }\n```\n\n`must-approve` blocks until an approval file appears under `control/approvals/`. **Grounding** runs first for `financial`/`destructive`: every declared parameter (a product code, an amount, a customer id) must trace to a real source seen earlier in the run — otherwise the action is **denied and never runs, even if \"approved.\"** An invented invoice can't be issued.\n\n---\n\n## Multi-agent, the safe way\n\nAgents coordinate through **files**, not a message bus:\n\n- **`WORK.md`** — the task chain as a declarative DAG. One *controller* owns it (this prevents the #1 multi-agent failure: infinite handoff loops). A deterministic runner advances it; the LLM only acts *inside* a step.\n- **`blackboard/`** — a shared space where agents post discoveries (one append-only file each).\n- **Worktree-lite isolation** — parallel tasks write to isolated dirs, so two agents never collide.\n\nDefault is **single-agent**. Multi-agent is opt-in and only when a task is genuinely parallel — it costs ~15× the tokens, so SCROLL estimates cost (language-aware) *before* it spawns.\n\n---\n\n## Watch, control, and read back\n\n```\nruns/<id>/events.jsonl   # run_started · permission_decision · grounding_checked · cost_update · completed …\nruns/<id>/digest.md      # human-readable summary — what it did, which dangerous tiers it touched, cost\n```\n\n- **Stream** the events (tail locally, or SSE/WebSocket in the cloud; types map to **AG-UI**).\n- **Control** a live run by writing files: `control/pause`, `control/stop`, `control/steer.md`, or approve a gate under `control/approvals/`.\n- **Read the digest** — so the owner understands the run instead of just trusting it (an antidote to passive over-delegation).\n\n---\n\n## Compliance is structural, not trust-based\n\nSCROLL doesn't rely on you reading the docs — the correct path is the only one that works: a **scaffold** that's correct by default, a JSON **schema**, a **linter** (`scroll check`) in CI, a build that **refuses** invalid agents, an [`AGENTS.md`](./AGENTS.md) that teaches AI coding tools the rules, and **`scroll audit`** — a hash-bound report so a \"pass\" is tied to the exact file state and can't be faked.\n\n---\n\n## CLI reference\n\n| Command | Does | Status |\n|---|---|---|\n| `scroll new <name>` | Scaffold an L1-ready agent folder | ✅ built |\n| `scroll check <name>` | Validate structure (linter; pre-commit + CI) | ✅ built |\n| `scroll build <name>` | Render one source → every runtime | ✅ built |\n| `scroll run --work <f>` | **Inner loop** over a `WORK.md` (or `run <agent> --task`) | ✅ built |\n| `scroll loop <LOOP.md>` | **Outer loop** — schedule + find work + stop conditions | ✅ built |\n| `scroll eval <name>` | Gold cases N× → machine checks + consistency + judge | ✅ built |\n| `scroll audit [name]` | Conventions + hash-bound report (CI; `--verify`) | ✅ built |\n| `scroll registry` | Scan agents → a config/observability view | ✅ built |\n| `scroll cost <task> [--language vi]` | Single vs multi token estimate (language-aware) | ✅ built |\n| `scroll mcp add <name>` | Wire an MCP server / connector into `.mcp.json` (`${vault:KEY}` creds · per-tool risk) | ✅ built |\n| `scroll skill add <ref>` | Install / scaffold a `SKILL.md` skill (`--agent` to attach) | ✅ built |\n| `scroll plugin add <ref>` | Unpack an agent-pack bundle (agents + skills + merged `.mcp.json`) | ✅ built |\n\nUseful `run` flags: `--resume` (crash-resume), `--worktree` (git-worktree isolation), `--risk <tier>`, `--auto-approve`, `--language <code>`, `--max-usd` / `--max-iterations`.\n\n---\n\n## Packaging\n\n- **`@agentpro/scroll`** — the CLI + loader (npm).\n- **`@agentpro/scroll-schema`** — the versioned spec + JSON Schema.\n- **Storage adapters** — `@agentpro/scroll-s3`, `-gcs`, `-repo` (roadmap).\n\nYour *agents* are never packaged — they're folders you own and version, like `AGENTS.md`.\n\n## Learn more\n- [`SPEC.md`](./SPEC.md) — the formal agent-folder + frontmatter spec (incl. §21 permissions, §22 grounding, §23 LOOP)\n- [`AGENTS.md`](./AGENTS.md) — how AI coding tools follow SCROLL\n- [`templates/`](./templates/) — a worked agent + a `WORK.md` + a `LOOP.md`\n\n## License\n[MIT](./LICENSE) © 2026 Agent Pro. Use it, fork it, ship it — just keep the copyright notice.\n\n---\n\n*SCROLL — a harness for agentic loops. Turn every AI subscription your team pays for into coordinated, governed, portable agents. Built by Agent Pro.*\n"}