README
¶
Your agents slop. Take control.
Deterministic project rules for your coding agent. They kick in when it touches a file or runs a command, and hold until met: files only where you allow, right skills loaded first, work proven by diff or logs. Not a suggestion in CLAUDE.md or AGENTS.md.
| Website → | Docs → |
|---|
See it in action
| Watch the 2-min video → | Claude Code session replay → |
|---|
One Claude Code session, one prompt: make every capability in harness-mocks, our fakes of Claude Code, Codex and Cursor, real for every harness, proven by recordings of the real thing. It split the work across parallel agents, and sloprail checked every step.
Why not just hooks?
Hooks, CLAUDE.md, skills, AI reviewers |
sloprail | |
|---|---|---|
| When rules appear | after a mistake, if you add them | first: the agent sets them up before any change that will repeat, and they stay |
| The rule | text the model reads, or a hook script you write | a check that verifies the work, run by code |
| Shell changes | the hook sees the command, not which files it changed | checks every file the change touched |
| What gets judged | one tool call at a time | sliced the way each rule needs: one file, a module, or the whole commit |
| Push and merge | blocked only if your hook pattern matches | blocked until the checks pass |
| Review | an AI reviewer re-reads it every time; what it checked is opaque | every verdict saved with its rule and reason, reused until the code changes |
Install
sloprail is installed per project: run these from the project's root.
Claude Code:
claude plugin marketplace add sloprail/sloprail --scope project
claude plugin install sloprail@sloprail-marketplace --scope project
Codex (then enable the plugin in the project's .codex/config.toml, and trust its hooks with sr-session codex-trust):
codex plugin marketplace add sloprail/sloprail
codex plugin add sloprail@sloprail-marketplace
Cursor (plugins are per user; this also installs the binaries):
curl -fsSL https://raw.githubusercontent.com/sloprail/sloprail/main/install.sh | sh -s -- --harness cursor
The first session after that installs the sr*
binaries the hooks call, once: the release matching the plugin's version,
checksum-verified, into ~/.local/bin, and says so. From then on every tool
call and turn-end runs through sloprail — you don't run anything by hand.
Install has each
harness's verification step and what differs between them.
Rather install the binaries yourself?
Set SLOPRAIL_NO_AUTO_INSTALL=1 and run
curl -fsSL https://raw.githubusercontent.com/sloprail/sloprail/main/install.sh | sh
(or go install ./services/... from a checkout).
How it works
Rules live under .sloprail/, one folder per rule:
gate/checks an action before it happensfile-guard/checks what a file holds, on every commitcontext/is a mode other rules depend onfile-guard/structure.yamllists where files may go at all
Your harness calls sloprail on every tool call and turn end, and sloprail runs the rules that apply.
To make verdicts block merges, run sr-checks verify in CI: see the Quickstart.
You've seen these happen
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
changeset
Package changeset is what a file-guard judges: the net change between two commits, as one value.
|
Package changeset is what a file-guard judges: the net change between two commits, as one value. |
|
checkcache
Package checkcache is where what file-guards concluded about commits is kept, so that no one asks a judge the same question twice.
|
Package checkcache is where what file-guards concluded about commits is kept, so that no one asks a judge the same question twice. |
|
checkstore
Package checkstore holds what file-guards concluded about commits, in a10n's check-results shape: a CheckRun (one rule evaluated once over one commit range: base_ref, head_ref, exit_code, error, metadata) holds Checks (one per subject and kind: status pass | fail | skip | error | interrupted, fingerprint, metadata) and each Check holds CheckItems (a finding: a file a judge named, a prerequisite of `require:`).
|
Package checkstore holds what file-guards concluded about commits, in a10n's check-results shape: a CheckRun (one rule evaluated once over one commit range: base_ref, head_ref, exit_code, error, metadata) holds Checks (one per subject and kind: status pass | fail | skip | error | interrupted, fingerprint, metadata) and each Check holds CheckItems (a finding: a file a judge named, a prerequisite of `require:`). |
|
clidoc
Package clidoc walks a Cobra command tree into a JSON shape the docs render, so the CLI reference is generated from the real commands, flags and help text rather than hand-listed.
|
Package clidoc walks a Cobra command tree into a JSON shape the docs render, so the CLI reference is generated from the real commands, flags and help text rather than hand-listed. |
|
commandmod
Package commandmod is the module for commands: what a shell command line is about to run.
|
Package commandmod is the module for commands: what a shell command line is about to run. |
|
cyclemod
Package cyclemod is the module for the cycle itself: that one ended.
|
Package cyclemod is the module for the cycle itself: that one ended. |
|
declaration
Package declaration reads the rule declarations a project keeps under its `.sloprail/` directory into typed, validated Go values.
|
Package declaration reads the rule declarations a project keeps under its `.sloprail/` directory into typed, validated Go values. |
|
dispatch
Package dispatch is the shared CHECK-RUNNER at the heart of the new nature-based guardrails: given a matched declaration's `require` and `checks` and the context of a fired event, it runs them in order and returns one verdict — pass, or refuse-with-reason.
|
Package dispatch is the shared CHECK-RUNNER at the heart of the new nature-based guardrails: given a matched declaration's `require` and `checks` and the context of a fired event, it runs them in order and returns one verdict — pass, or refuse-with-reason. |
|
event
Package event is what crosses every boundary in sloprail.
|
Package event is what crosses every boundary in sloprail. |
|
filemod
Package filemod is the module for files: what is about to be written, and what a cycle turned out to have changed.
|
Package filemod is the module for files: what is about to be written, and what a cycle turned out to have changed. |
|
fingerprint
Package fingerprint answers what a file's content is, as one short string.
|
Package fingerprint answers what a file's content is, as one short string. |
|
gitrepo
Package gitrepo asks git what state a working tree is in.
|
Package gitrepo asks git what state a working tree is in. |
|
grounding
Package grounding is the one place a command line's CITATIONS are read.
|
Package grounding is the one place a command line's CITATIONS are read. |
|
harness
Package harness is the harness-neutral seam: the interface every coding-agent harness (Claude Code today; Codex or Cursor later) implements, and the shared normalized types its callers consume.
|
Package harness is the harness-neutral seam: the interface every coding-agent harness (Claude Code today; Codex or Cursor later) implements, and the shared normalized types its callers consume. |
|
harness/claudecode
Package claudecode is the Claude Code implementation of internal/harness: every path, file schema, hook wire format and environment variable that is specific to Claude Code lives here and nowhere else in sloprail's production code (the tool-call and citation readers in internal/transcript still name Claude's record shapes; see the refactor's follow-ups).
|
Package claudecode is the Claude Code implementation of internal/harness: every path, file schema, hook wire format and environment variable that is specific to Claude Code lives here and nowhere else in sloprail's production code (the tool-call and citation readers in internal/transcript still name Claude's record shapes; see the refactor's follow-ups). |
|
harness/claudecode/record
Package record is Claude Code's session-file format: the spelling of one JSONL line and where Claude Code keeps those files.
|
Package record is Claude Code's session-file format: the spelling of one JSONL line and where Claude Code keeps those files. |
|
harness/codex
Package codex is the OpenAI Codex CLI implementation of internal/harness: every path, file schema, hook wire format and environment variable specific to Codex lives here.
|
Package codex is the OpenAI Codex CLI implementation of internal/harness: every path, file schema, hook wire format and environment variable specific to Codex lives here. |
|
harness/codex/record
Package record is Codex's session file ("rollout") format: how one JSONL line is read into the neutral harness.Record, and where Codex keeps those files.
|
Package record is Codex's session file ("rollout") format: how one JSONL line is read into the neutral harness.Record, and where Codex keeps those files. |
|
harness/codex/trust
Package trust establishes Codex's trust in sloprail's plugin hooks.
|
Package trust establishes Codex's trust in sloprail's plugin hooks. |
|
harness/cursor
Package cursor is the Cursor (cursor-agent) implementation of internal/harness: the hook payloads and outputs, transcript format and layout, plugin layout and environment that are specific to Cursor.
|
Package cursor is the Cursor (cursor-agent) implementation of internal/harness: the hook payloads and outputs, transcript format and layout, plugin layout and environment that are specific to Cursor. |
|
harness/cursor/record
Package record is Cursor's session-file format: the spelling of one JSONL line of a conversation's agent-transcripts file and where Cursor keeps those files.
|
Package record is Cursor's session-file format: the spelling of one JSONL line of a conversation's agent-transcripts file and where Cursor keeps those files. |
|
harnessmock
Package harnessmock locates the pinned a10n-claude-mock (a stand-in `claude`) and builds the plugin wiring a mock session needs: a directory-sourced local marketplace and the settings that enable sloprail from it.
|
Package harnessmock locates the pinned a10n-claude-mock (a stand-in `claude`) and builds the plugin wiring a mock session needs: a directory-sourced local marketplace and the settings that enable sloprail from it. |
|
hookinput
Package hookinput resolves, from a normalised hook input (harness.HookInput), the session record it belongs to and the directory its stores are keyed by.
|
Package hookinput resolves, from a normalised hook input (harness.HookInput), the session record it belongs to and the directory its stores are keyed by. |
|
judgelimit
Package judgelimit coordinates parallel `sr-checks run` processes on one machine through lock files under the user cache dir.
|
Package judgelimit coordinates parallel `sr-checks run` processes on one machine through lock files under the user cache dir. |
|
module
Package module is the extension point.
|
Package module is the extension point. |
|
module/modules
Package modules holds the one list of modules a build ships with.
|
Package modules holds the one list of modules a build ships with. |
|
natures
Package natures holds the state a rule of any nature reads about the world around it — the `context` and `gates` maps a file-guard, a gate, or a context trigger sees when its `match` runs.
|
Package natures holds the state a rule of any nature reads about the world around it — the `context` and `gates` maps a file-guard, a gate, or a context trigger sees when its `match` runs. |
|
procgroup
Package procgroup keeps the children this process starts from outliving it.
|
Package procgroup keeps the children this process starts from outliving it. |
|
reap
Package reap removes the temp directories sloprail's runs leave behind when they are killed (sr-test-case-*, sr-tree-*, sr-agent-output*): a run that dies skips its deferred cleanup, and thousands of them pile up in the OS temp dir.
|
Package reap removes the temp directories sloprail's runs leave behind when they are killed (sr-test-case-*, sr-tree-*, sr-agent-output*): a run that dies skips its deferred cleanup, and thousands of them pile up in the OS temp dir. |
|
scriptexec
Package scriptexec is the one place sloprail decides whether a declared script may be run: it must be executed DIRECTLY, so it must be executable and carry a shebang naming a standard interpreter.
|
Package scriptexec is the one place sloprail decides whether a declared script may be run: it must be executed DIRECTLY, so it must be executable and carry a shebang naming a standard interpreter. |
|
sessionpath
Package sessionpath is where a session's data lives, and who the session is.
|
Package sessionpath is where a session's data lives, and who the session is. |
|
sessionstate
Package sessionstate holds what one session must remember between hook runs.
|
Package sessionstate holds what one session must remember between hook runs. |
|
srevents
Package srevents is the rule-decision log sr-test reads: when SR_EVENTS_FILE is set, every decision a rule makes (a gate, a file-guard, a structure gate, a context entering or leaving) appends one JSON line to it.
|
Package srevents is the rule-decision log sr-test reads: when SR_EVENTS_FILE is set, every decision a rule makes (a gate, a file-guard, a structure gate, a context entering or leaving) appends one JSON line to it. |
|
srtest
Package srtest runs a project's end-to-end rule tests and reports one result per case.
|
Package srtest runs a project's end-to-end rule tests and reports one result per case. |
|
srtest/agent
Package agent implements `sr-test agent`: run a scripted agent (a10n-claude-mock) in the current directory with sloprail's plugins enabled from the local marketplace build, and report what the guardrails decided.
|
Package agent implements `sr-test agent`: run a scripted agent (a10n-claude-mock) in the current directory with sloprail's plugins enabled from the local marketplace build, and report what the guardrails decided. |
|
subbin
Package subbin resolves a co-installed sloprail service binary (sr-session, sr-file, sr-mark, ...) by its well-known sibling path.
|
Package subbin resolves a co-installed sloprail service binary (sr-session, sr-file, sr-mark, ...) by its well-known sibling path. |
|
tagmod
Package tagmod is the module for tags: the `#tag`-shaped tokens the agent wrote into its own messages over a cycle.
|
Package tagmod is the module for tags: the `#tag`-shaped tokens the agent wrote into its own messages over a cycle. |
|
tooluse
Package tooluse is the module for the tool call itself: what the harness is about to run, before any file or command meaning is derived from it.
|
Package tooluse is the module for the tool call itself: what the harness is about to run, before any file or command meaning is derived from it. |
|
transcript
Package transcript reads a harness's record of a session into the one shape every rule is written against.
|
Package transcript reads a harness's record of a session into the one shape every rule is written against. |
|
tuidrive
Package tuidrive drives a harness's interactive (TUI) mode headlessly, on a pseudo-terminal: it waits for the input to be live, types a prompt, decides when the turn has ended, and quits the way a person does.
|
Package tuidrive drives a harness's interactive (TUI) mode headlessly, on a pseudo-terminal: it waits for the input to be live, types a prompt, decides when the turn has ended, and quits the way a person does. |
|
version
Package version holds the one build-time version string every sr* binary reports through Cobra's own --version flag.
|
Package version holds the one build-time version string every sr* binary reports through Cobra's own --version flag. |
|
services
|
|
|
sr
command
Command sr is the root sloprail CLI.
|
Command sr is the root sloprail CLI. |
|
sr-agent
command
Command sr-agent runs an agent without the caller naming the harness that will run it.
|
Command sr-agent runs an agent without the caller naming the harness that will run it. |
|
sr-checks
command
Command sr-checks judges a project's file-guards over an explicit range of commits, and shows what they concluded.
|
Command sr-checks judges a project's file-guards over an explicit range of commits, and shows what they concluded. |
|
sr-eval
command
Command sr-eval proves that a guardrail's use-case doc is true of a real agent, not just of a mock transcript.
|
Command sr-eval proves that a guardrail's use-case doc is true of a real agent, not just of a mock transcript. |
|
sr-file
command
This file answers the one question CUE has no opinion about: which bytes of a file are the document.
|
This file answers the one question CUE has no opinion about: which bytes of a file are the document. |
|
sr-mark
command
Command sr-mark writes `// sr:<kind> <fqn>` enforcement markers DIRECTLY into impl source files.
|
Command sr-mark writes `// sr:<kind> <fqn>` enforcement markers DIRECTLY into impl source files. |
|
sr-session
command
Command sr-session enforces a project's declared guardrails at the moments its harness can pause.
|
Command sr-session enforces a project's declared guardrails at the moments its harness can pause. |
|
sr-test
command
Command sr-test runs a project's end-to-end rule tests.
|
Command sr-test runs a project's end-to-end rule tests. |
|
tests
|
|
|
e2e/harness
Package harness drives end-to-end tests the way a session actually runs.
|
Package harness drives end-to-end tests the way a session actually runs. |
|
e2e/harness/session/changesetkit
Package changesetkit reads what a file-guard's recording check was handed on the changeset model: one payload per judged range, its selected files under `.changeset.files[]` as {path, status} with status A (added), M (modified) or D (deleted).
|
Package changesetkit reads what a file-guard's recording check was handed on the changeset model: one payload per judged range, its selected files under `.changeset.files[]` as {path, status} with status A (added), M (modified) or D (deleted). |
|
tools
|
|
|
docsgen
command
Command docsgen extracts the guardrail declaration types from the source and emits them as JSON for the docs site to render.
|
Command docsgen extracts the guardrail declaration types from the source and emits them as JSON for the docs site to render. |
Click to show internal directories.
Click to hide internal directories.