Raider user guide
Use the installed headless CLI for first use, or build the source checkout for the Scala REPL and tab shell. This guide focuses on workflows available from a source checkout: a model-backed coding task, scripted demo, audit, and typed workflow. For installation, first command, mock mode, and the artifact path, start with installed onboarding. The installed headless JAR does not contain the Scala compiler or JLine and cannot start the REPL/TUI.
Choose how to work
| Need | Start with | What it does |
|---|---|---|
| Ask Raider to change a project | Headless coding task | Runs the coder agent against the workspace you name |
| Explore agent requests in Scala | Scala REPL | Evaluates Scala definitions and Raider requests in one session |
| Keep several tabs and drafts | Tab shell | Switches between tabs; text typed in a tab is saved as a draft, not evaluated as Scala |
| Run one repeatable workflow in CI | Local CI guide | Runs checks, reviews, and a typed decision |
Prepare the source checkout
Install JDK 21, sbt 1.11.4, and Python 3. From the repository root, build the example classpath and bundle:
sh scripts/build/user-examples.sh
RAIDER_CP=$(cat artifacts/user-examples/classpath.txt)
The build uses the pinned Scala 3.9.0 and ZIO 2.1.26 dependencies. The classpath lets you start the CLI and REPL directly from this checkout. For provider setup and troubleshooting, see onboarding.
Fix a Scala bug with a model
This example copies a small Scala billing project into a temporary directory.
The policy is “discount 1,000 cents when the subtotal is at least 10,000
cents”; the fixture has a strict > comparison, so the exact boundary fails.
Follow model setup first. This case uses an OpenAI-compatible endpoint. The helper creates the disposable workspace, gives the coder a compile/test command, and checks the resulting source and tests.
: "${RAIDER_BASE_URL:?Set your OpenAI-compatible endpoint URL}"
: "${RAIDER_MODEL:?Set the model name for that endpoint}"
RAIDER_PROVIDER=openai RAIDER_LIVE_APPROVED=1 \
python3 scripts/quality/user_examples.py --only coding --live
This makes live model calls using your configured credentials. The expected
change is s > 10000 to s >= 10000, with these test results:
Before the edit: FAIL exact-threshold
After the edit: DiscountSpec: PASS 3 boundaries
The command prints the run-artifact directory. The copied project is under
artifacts/user-examples/verification-<id>/workspace/, and its result report is
artifacts/user-examples/verification-<id>/report.json. Check the final source
and test results there. The original fixture stays unchanged.
Work on your own project
Use coder to give a model access to a project you choose. Work on a branch or
disposable copy, and replace the path and task below with your own. Include the
command that checks the change so the agent knows how to finish.
RAIDER_CP=$(cat artifacts/user-examples/classpath.txt)
WORKSPACE='/absolute/path/to/your/project-copy'
java -cp "$RAIDER_CP" raider.cli.Main run \
--agent coder --provider "$RAIDER_PROVIDER" \
--base-url "$RAIDER_BASE_URL" --model "$RAIDER_MODEL" \
--workspace "$WORKSPACE" \
--input "Fix the discount boundary bug. Keep public signatures unchanged. Run sbt test and report the changed files and test result." \
--out artifacts/project-task
Replace sbt test if your project uses a different check command. The CLI uses
the provider flags above; set them through model setup.
Unlike the fixture helper, this command works directly in WORKSPACE. It can
change files and run processes with your permissions.
Raider prints a work-<id> path beneath artifacts/project-task. Read its
summary.md for the result and transcript.json for tool output. In your
project copy, review git diff and run the relevant checks yourself before
accepting the change. See reading a run.
See the same bug case without a live model
Run the fixed-response demo with the local scripted stand:
python3 scripts/quality/user_examples.py --only coding
It drives the real Scala tools through the billing repair sequence, but its responses follow a fixed script; the file edits and Scala checks still run.
Create an audit report
The audit fixture has allow_plaintext_fallback = true in
config/payments.conf. Run the offline report example:
python3 scripts/quality/user_examples.py --only audit
The expected AUDIT.json identifies the file and line, quotes the setting,
and gives an impact and remediation. The example works in a disposable copy;
the source configuration stays unchanged. The report content comes from the scripted demo.
Check release readiness from typed input
The compiled task-summary bundle validates three supplied statuses. It
reports a pending check; it does not compile code, run a migration, or decide
whether the statuses are true.
java -cp "$RAIDER_CP" raider.cli.Main run \
--bundle artifacts/user-examples/task-summary.jar \
--workflow task-summary \
--input 'tests=pass,migration=pass,rollback=pending' \
--out artifacts/user-examples/readiness --mock
Expected workflow output, included in summary.md:
{"decision":"BLOCKED","passed":["migration","tests"],"pending":["rollback"],"action":"Complete: rollback."}
Set rollback=pass to get READY. BLOCKED is a valid workflow result and
the command exits successfully; missing, duplicate, unknown, or invalid
checks are rejected. The implementation is
TaskSummary.scala. See
the Scala tutorial for Program, Task, andThen, and
parallel typed requests.
Run a local CI workflow
The Billing CI example repairs the billing fixture, checks it independently, runs parallel reviews, and writes a typed decision plus an index of its run artifacts. It makes live provider calls. Read its provider and budget requirements before running it.
The walkthrough includes a successful run and links to the complete Scala projections, so you can compare a result with the workflow that produced it.
Read a run's trace
For the coding task above, begin with summary.md and run.json in the
generated work directory. Then use lineage.scala to find call order and
follow each data: reference into lineage-data.json. transcript.json and
events.jsonl contain the model/tool exchange and process results. These
files explain what ran; compare them with the actual changed source and check
output before you decide the task is done. For a guided example, see the
lineage walkthrough.
Common setup problems
- The classpath file is missing or Java is rejected: rebuild with JDK 21 and inspect
artifacts/user-examples/build.log. - A live call reports missing credentials: privately provide
RAIDER_API_KEYor configureRAIDER_API_KEY_CMD; never pass a key as an argument. - The run refuses to start: include
--out, exactly one input flag, and either--agentor both--bundleand--workflow. - The agent says it passed but tests do not: check the actual compiler/test exit and output. If lineage is absent, inspect
run.json,summary.md, andevents.jsonl.