- Perl 98.6%
- Shell 1.3%
.claude/skilletor.json: getty-perl-pod and getty-perl-release-author-getty come from getty instead of karr Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| .github/workflows | ||
| assets | ||
| bin | ||
| docs | ||
| examples/multi-raider-hall | ||
| lib | ||
| maint | ||
| plugins/claude-code | ||
| scripts | ||
| share/packs | ||
| t | ||
| .dockerignore | ||
| .gitignore | ||
| .worktreeinclude | ||
| Changes | ||
| CLAUDE.md | ||
| CONTEXT.md | ||
| cpanfile | ||
| dist.ini | ||
| Dockerfile | ||
| LICENSE | ||
| README.md | ||
Langertha::Raider
The autonomous agent engine of Langertha
(Langertha::Raider, plus the Langertha::Raid orchestration layer) together with
the raider command-line agent built on it (Langertha::Raider::CLI).
raider is an autonomous command-line agent in Perl. It wraps Langertha::Raider
with a practical toolbox — filesystem, bash, web search, web fetch, optional
Perl-native tools — and drops you into a REPL (or a one-shot run) where a viking
shield-maiden named Langertha does the work, against any of the ten LLM
providers -e knows (from Perl, Langertha::Raider takes any Langertha engine).
__ __
.----.---.-.|__|.--| |.-----.----.
| _| _ || || _ || -__| _|
|__| |___._||__||_____||_____|__|
perl agent - powered by Langertha
Status: 0.x. The engine, the CLI and the Hall are covered by the test suite and an acceptance suite with a scripted model (
t/scenarios/). Interfaces can still change between 0.x releases; the documented wire formats (ADR 0013, 0015, 0033) only change with a new format version.
This README describes what
raiderdoes today. The wider vision — the home-directory assistant, provider discovery, delegates, reviewed long-term memory, editor integration over stdio — lives inCONTEXT.mdand the ADRs underdocs/adr/, and is collected under Roadmap / Planned below so you can tell the two apart.
One tool, two jobs
Raider is designed to be two things from one kernel: a project agent that works inside a directory (like Claude Code), and a personal assistant that lives in your home and is reachable everywhere (like a Hermes agent).
Today the project-agent side is what ships: you run raider in a project, it
reads that project's instructions and tools, and records its work in per-project
sessions. The assistant side (the ~/.raider/ home profile, reviewed long-term
memory, home-mounted services) is largely on the roadmap; the
Hall already covers the always-reachable, long-lived, Telegram/cron part of it.
Quick start
From CPAN:
cpanm Langertha::Raider
export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, GROQ_API_KEY, ...
cd ~/dev/my-project
raider # REPL opens in the current directory
From a git checkout:
cpanm --installdeps .
perl -Ilib bin/raider
Note: two dependencies are ahead of CPAN, so cpanm --installdeps . cannot fetch them
yet. Release order: Skilletor 0.001 (the perl/ dist of
skilletor) first, then Langertha 0.504 (the
release after 0.503, with Langertha::Engine::Virtual for -e mock and the scenario
suites, and stream_usage), then raider. Until then install both from their checkouts
(dzil install).
Upgrading? Three changes are incompatible (see
Changes): every tool call now passes a permission policy, and a run nobody can approve (one-shot,--json, Hall, ACP) refuses writes,bash, network and messages unless a rule or--permission-modeallows them;bashrefuses heavy commands under memory pressure (loadguard,LOADGUARD_THROTTLE=0turns it off); and a project with onlyCLAUDE.mdor.claude/is read like Claude Code reads it.
Or as a single-file Linux binary — no Perl needed (see Binary).
Or via Docker — no Perl toolchain required (see Docker):
docker run --rm -it -v "$PWD:/work" -e ANTHROPIC_API_KEY raudssus/raider
Then tell Langertha what to do:
raider> lies die Changes und schreib mir ne kurze summary
raider> such im web nach "Perl 5.40 release notes", dann hol den ersten treffer
raider> prove -l t/ laufen, falls was rot ist report zurück
One-shot usage (no REPL):
raider "check git status and summarize"
raider --json "count the .pm files in lib" | jq .
When stdin is a terminal and you give no prompt on the command line, raider drops
into the REPL automatically. With Term::ReadLine::Gnu
installed, line editing and persistent input history (~/.raider_history) are on.
How it picks an engine
Zero configuration: the first *_API_KEY found in the environment decides the
engine (in the order below), and a cheap model is used by default.
| Engine | Env var | Default model |
|---|---|---|
| anthropic | ANTHROPIC_API_KEY |
claude-haiku-4-5 |
| openai | OPENAI_API_KEY |
gpt-4o-mini |
| deepseek | DEEPSEEK_API_KEY |
deepseek-chat |
| groq | GROQ_API_KEY |
llama-3.3-70b-versatile |
| mistral | MISTRAL_API_KEY |
mistral-small-latest |
| gemini | GEMINI_API_KEY |
gemini-2.5-flash |
| minimax | MINIMAX_API_KEY |
MiniMax-M3 |
| cerebras | CEREBRAS_API_KEY |
llama3.1-8b |
| openrouter | OPENROUTER_API_KEY |
(set -m) |
| ollama | (none — local) | llama3.3 |
Auto-detection tries anthropic, openai, deepseek, groq, mistral, gemini
in that order, and falls back to anthropic. Override with -e <engine>,
-m <model> or -k <key>.
raider uses provider API keys only. Claude Code subscription / OAuth credentials
from ~/.claude are not read or reused as Anthropic API credentials.
Commands and options
raider [options] [prompt...] run a prompt (or open the REPL)
raider config explain [options] show each effective setting and its source
raider config migrate [--dry-run] move .raider.yml / .raider.md into .raider/
raider session list | show | resume | fork | rm see Sessions
raider provider inspect HOST show a provider's manifest, see Providers
raider provider add ALIAS HOST bind ALIAS to a provider (asks on a terminal), see Providers
raider provider list | show ALIAS | remove ALIAS [--yes] the stored aliases, see Providers
raider --provider HOST|ALIAS [options] run on a provider's manifest endpoint, see Providers
raider hall <subcommand> the optional Raider Hall daemon
raider acp <subcommand> the bundled ACP client
Options:
-e, --engine NAME anthropic, openai, deepseek, groq, mistral, gemini,
minimax, cerebras, openrouter, ollama (default: auto)
-m, --model NAME Model identifier (engine-specific cheap default)
-k, --api-key KEY API key (overrides *_API_KEY env var)
-o, --option KEY=VALUE Engine attribute (repeatable), e.g. -o temperature=0.2;
raider's own config keys (perl, packs=a,b, ...)
configure raider instead
-r, --root DIR Working directory (default: cwd). File tools are
confined to this directory.
-M, --mission TEXT Replace the persona and the instructions file
(.raider/instructions.md, else .raider.md; skills,
packs and the tool descriptions still apply)
--bare Isolated context: no instructions file, Claude
layout, skills, packs:, default packs or detection
(--pack NAME and /pack NAME still work)
-i, --interactive REPL mode (default on a TTY with no prompt / pipe)
--json[=N] Print one JSON document for the run and exit
--msgpack[=N] The same document as MessagePack
--yaml[=N] The same document as YAML
--stream-json[=N] Print the run as JSON Lines events as it happens
--stream-msgpack[=N] The same events as MessagePack objects
--stream-yaml[=N] The same events as YAML documents
--no-session Do not record the run(s) in a session journal
--session ID Continue session ID (replay + record)
--continue The same, with the newest session of the project
--max-iterations N Hard safety cap on tool rounds per raid (default 10000)
--no-color Disable ANSI colors
--no-trace Hide live tool-call progress output (--trace shows
it, also with a machine flag, on stderr)
--perl Enable perl_eval / perl_check / perl_cpanm tools
--pack NAME Enable a bundled pack (repeatable)
--no-pack NAME Switch a pack off (also a detected/default one)
--no-detect Do not activate packs by workspace detection
(--detect forces it on over detect: false)
--claude Read the Claude Code layout (CLAUDE.md, settings,
Claude skills) also in a .raider/ project
--openai / --codex Load AGENTS.md
--skills DIR Offer DIR's skills (*/SKILL.md or *.md; repeatable)
--customize-prompt Launch the prompt-builder at startup
--permission-mode MODE
default, acceptEdits, plan or bypassPermissions
(see Permissions below)
--dangerously-skip-permissions
The same as --permission-mode bypassPermissions
--export-skill [PATH] Write a "how to use raider" markdown doc, exit
--export-claude-skill [PATH] Write a Claude Code SKILL.md, exit
--version Print raider's and Langertha's version, exit
-h, --help Show help
REPL slash commands:
| Command | Does |
|---|---|
/help |
Command list |
/clear |
Reset conversation history and token counters |
/metrics |
Cumulative raid metrics |
/stats |
Tokens in / out / cache per model, subcalls included |
/reload |
Re-read instructions, memory, settings, skills; re-detect packs |
/prompt |
Launch the prompt-builder (edits the instructions) |
/skill [PATH] |
Export the plain-markdown how-to-use doc |
/skill-claude [PATH] |
Export a Claude Code SKILL.md with frontmatter |
/config |
Show each setting and where it came from |
/permissions |
Permission mode, rules with their sources, session rules |
/permissions mode M |
Switch the permission mode |
/model [NAME] |
Show or save the model for the next run |
/model list [FILTER] |
List models reported by the active engine |
/packs |
List available packs and whether they are active |
/pack on/off NAME |
Enable or disable a pack (/pack NAME toggles) |
!CMD |
Run CMD in the shell only; nothing goes to the model |
?CMD |
Run CMD, then send it, its exit status and output to the model |
/quit /exit :q |
Leave |
!CMD and ?CMD run CMD with $SHELL -c (/bin/sh without SHELL) in the working
root, and Ctrl-C ends the command, not raider. !CMD has the terminal, so less or
vim work, and stays out of the conversation and the session. ?CMD shows the output as
it comes and then sends the command, its exit status and the output (stdout and stderr,
head and tail of anything past 20000 characters) to the model as your next prompt; a
command you end with Ctrl-C sends nothing. A line that is only ! or ? is a prompt.
/pack and /reload rebuild the mission, and mount or unmount the Perl tools when
a pack that requests them (the perl pack) comes or goes — the tools the model is
told about are always the tools it gets.
Full detail — every option, the environment variables, the machine-output document
schema and every exit status — is in perldoc raider.
Configuration — .raider/config.yml or .raider.yml
Configuration is per-project: .raider/config.yml in the working root, or else the
legacy .raider.yml there, over the home file ~/.raider/config.yml (see
Roadmap for the rest of the planned ~/.raider/ home model).
All take the same keys; below, .raider.yml stands for
whichever file is in use. When both exist, only .raider/config.yml is read —
raider warns that it ignores .raider.yml, and raider config explain shows the
conflict. What raider saves (/model, --claude, --openai, --skills) goes to
the file in use, and to .raider.yml when there is none. It is read in layers,
later ones winning:
- built-in defaults
~/.raider/config.yml(the same three layers as 3–5).raider.ymltop-level keys.raider.ymldefault:section.raider.yml<engine>:section (openai:,anthropic:, ...)- command-line
-o/ flags
A project value replaces a home value, with three exceptions: skills and
no_detect from both files add up, and detect: rules are replaced per pack.
raider never writes the home file; run in ~ itself, ~/.raider/config.yml is the
project file and is read once. raider config explain names home values home
(home default:, home openai:) and prints the home file's path.
project_tools in ~/.raider/config.yml maps a workspace selector — "*", a path
glob starting with / or ~/ (* stays within one directory, ** crosses them),
or a workspace name — to the home tools a project gets; all matching entries add up.
Only the home file grants: a project_tools in a project file is ignored and
reported. For now raider config explain only shows which selectors match and
which tools they grant (and which packs request them); nothing is mounted from it
yet, and workspace names never match.
# ~/.raider/config.yml
project_tools:
"*": [telegram]
"~/dev/**": [perl]
Flat form, or per-engine with a shared default: layer:
# .raider.yml
default:
temperature: 0.3
anthropic:
temperature: 0.7
response_size: 8192
openai:
temperature: 0.5
Two kinds of keys live in the file:
- Engine attributes (
temperature,response_size,seed,model, ...) go to the engine constructor.-o key=valueon the command line overrides them (values are auto-coerced:0.2→ Float,4096→ Int,true/false→ 1/0). - Raider's own keys —
engine,perl,packs,skills,detect,no_detect,preferred_lib_target,web_fetch_model(the model that answersweb_fetchprompts),project_tools(home file only),max_agent_depth,agent_models(subagents, ADR 0020) — configure raider itself and never reach the engine.skillsis merged across layers instead of replaced.
A file that does not parse, whose top level is not a mapping, or that puts a mapping
under one of raider's own keys (other than skills, project_tools, providers,
agent_models and detect,
whose detect: map holds per-pack detection rules) is a hard error naming the offending key —
raider stops instead of loading half of it.
.raider/instructions.md in the working root — or the legacy .raider.md there —
is the persona / mission file: drop one in to rename Langertha, reshape her, or
replace her entirely; /prompt builds one interactively (in the file in use, else
.raider.md) and /reload hot-swaps it. With both present only
.raider/instructions.md is read; raider warns about .raider.md and
raider config explain lists it as ignored. -M TEXT replaces the instructions for
one run without touching the file.
To see where every effective value came from — a flag, a .raider.yml layer, an
environment variable or the built-in default — without writing anything or calling a
model:
raider config explain # or /config inside the REPL
raider -e openai config explain # options may come first
To move a project to the new layout, raider config migrate turns .raider.yml into
.raider/config.yml and .raider.md into .raider/instructions.md (each only if it
exists) and shows what it does first; --dry-run stops there. The new files are
written atomically, the legacy ones are renamed to .raider.yml.bak / .raider.md.bak,
and .raider/ gets its .gitignore — afterwards raider config explain shows the
same settings from the new files. An api_key is not copied into
.raider/config.yml, which is meant to be committed: it is reported (never printed),
move it to ~/.raider/config.yml or the engine's *_API_KEY variable. Nothing is
merged — if a new file or a backup already exists, nothing is written.
raider config migrate --dry-run # show what would happen
raider config migrate -r ~/dev/app
Sessions
Every run is recorded in a session journal (JSONL) under the working directory:
.raider/sessions/<id>.jsonl, one JSON object per line. A one-shot run starts a new
session and names it on stderr; the REPL starts one with its first prompt.
--no-session records nothing. Creating .raider/ also writes a .raider/.gitignore
that excludes sessions/ and lib/ — a journal holds the full output of every tool,
so it is not committed by default. API keys never enter it.
raider session list # the project's sessions, newest first
raider session show ID # one session, event by event
raider session show ID --json # the whole journal as one document
raider session resume ID # the REPL, continuing session ID
raider --session ID "and now ..." # one more run in session ID
raider --continue "and now ..." # the same, newest session
raider -i --continue # the REPL on the newest session
raider session fork ID # a new session with ID's history
raider session rm ID # delete session ID
A session ID can be shortened to a unique start of it (20260925-08) or its last
four hex digits (3f2a); an ambiguous form is refused with the candidates listed.
One session has one writer at a time: while a raider writes a session it holds a
lock, and a second writer fails at once (exit status 4) instead of waiting.
Continuing a session replays the conversation — nothing recorded is executed again —
and reports what the crash rules found: damaged lines, runs that never ended
(counted as interrupted), and tool calls without a result, whose outcome is
unknown and which are never re-run.
Providers
A provider can describe itself in a manifest at /.well-known/langertha.json
(ADR 0007; schema and validator in Langertha core, Langertha::Manifest): its
endpoints with their wire dialect, the auth mechanism each needs, and its models
with the capabilities they claim. raider provider inspect fetches one, validates it
and shows it:
raider provider inspect provider.example # HOST, HOST:PORT or an https origin
raider provider inspect provider.example --json # one versioned document
raider provider inspect knarr.lan:8443 --allow-internal
It prints the provider id, the issuer, every endpoint (id, dialect, base URL, auth
reference), the auth entries (id, type) and the models (id, endpoint, claimed
capabilities), then warns about what this raider cannot use — a dialect it has no
adapter for, an auth type it cannot supply, a capability Langertha does not know
(treated as absent) — and notes that extensions are inert. A manifest carrying a
command, code, secret or prompt field is rejected as invalid.
Inspecting stores nothing, binds no credential and sends none: the fetch is https
only, at most 1 MiB, 10 seconds and 3 redirects within the origin; a redirect to
another origin is not followed but reported. The host is resolved once and every
address is checked, and the request goes to a checked address (TLS still verifies
the host name). Loopback, private, link-local and reserved addresses are refused
unless --allow-internal releases them for a knarr or skeid you run yourself; cloud
metadata, multicast and unspecified addresses are refused always.
raider --provider HOST runs on the endpoint a manifest declares, for one run and
with nothing stored — naming the host on the command line is the whole release, as
with -o url=:
raider --provider provider.example -m example-model -k "$KEY" "Summarize README.md"
raider --provider knarr.lan:8443 --allow-internal -k "$KEY" # the REPL
The rules are provisional:
- Model:
-mmust be a model id of the manifest; without it the manifest must list exactly one.model:in.raider.ymldoes not apply. - Engine: from the endpoint's dialect —
openai-chatruns asopenai,anthropic,geminiandollamaas themselves,responses,perplexity-agent,anthropic-compat(without native structured output) andakion their own Langertha engines, with the endpoint'sbase_urlas URL. An unknown dialect is an error, never a guess; so islmstudio(Langertha's native LM Studio engine has no tool calling). Other.raider.ymland-oengine options apply as with-e;-e,-o engine=and-o url=are refused next to--provider. - Key: only
-k(or-o api_key=), never.raider.ymlor an environment variable, so a key meant for another provider never reaches this one. An endpoint with an auth reference needs one; an endpoint without auth gets none. - Origin: the endpoint must be
httpsand of the manifest's own origin, and its host is checked again under the address rules above (--allow-internalreleases both). The engine connects to the first checked address, not to a new lookup of the name (TLS still verifies the host name), so a DNS answer that changes after the check cannot send the key elsewhere. Model requests are POSTs and are not redirected; the engine's other requests follow no redirect. - A model that does not declare
tools_nativeis a warning, not an error.
Stored aliases
raider provider add keeps a provider you have decided to trust under a name:
raider provider add acme provider.example --credential-env ACME_API_KEY
raider --provider acme -m example-model "Summarize README.md"
add fetches and validates the manifest as inspect does, prints its endpoints,
auth and what will be pinned, and asks on a terminal before it stores anything;
without a terminal it stores nothing. The binding goes under providers: in
~/.raider/config.yml (and nowhere else — a providers: in a project file is
ignored):
providers:
acme:
origin: https://provider.example:443
issuer: https://provider.example
auth: [api_key]
credential_env: ACME_API_KEY
allow_internal: 0
pinned_at: 2026-10-15T09:30:00Z
fingerprint: 3f2a...
fingerprint is a field of its own beyond origin, issuer and auth: the digest of
what you accepted, which --provider ACME compares.
raider provider list # the stored aliases, nothing fetched
raider provider show acme # every field, the fingerprint included
raider provider remove acme # asks; without a terminal it needs --yes
The aliases also show in raider config explain and the REPL banner.
- Credential: only the name of the environment variable is stored, never the
value; it is read at run time and sent to the pinned origin only (
-koverrides it for one run). It is required when the endpoints ask for auth and never guessed.*_API_KEYvariables of other providers never select or feed an alias. The name is pinned too: another variable is another secret going to the same origin, so a change needsprovider addagain and--provider ACMEstops until then. - Pinned: origin, issuer and auth types, the credential variable and
--allow-internal— and, in the fingerprint, each endpoint's origin and dialect and the provider id. No TLS pin: a certificate rotation changes nothing. A changed model list, capability or path does not matter; anything pinned that changed stops--provider ACMEuntil you runprovider addagain and accept. --allow-internalbelongs to the alias (set it atadd); it is part of what you accepted, is refused next to a stored alias on the command line, and a hand-edited entry no longer matches.- A
--providername without dot, port orhttps://is always an alias. One that is not stored stops raider with a usage error pointing toraider provider add, and nothing is fetched — a typo in an alias never becomes a network request. A host needs a dot (host.tld,host.tld:PORT), a port, brackets (an IPv6 literal such as[::1]or[2001:db8::1], with or without a port) or anhttps://origin;provider inspectandprovider addtake no bare name as a host either. - A model that the manifest lists on several usable endpoints is refused with the
endpoints named;
--provider-endpoint IDchooses one. - A
--providerthat cannot run is also onerefusedorfaileddocument on stdout with--json; the exit status is the same with and without it.
Tools
Every run assembles one toolbox, and the tool list in the model's prompt is generated from exactly the tools the engine is offered — a tool that is not mounted is not described. The built-ins:
| Tool | Notes |
|---|---|
list_files(path) |
Directory listing, dirs suffixed with / |
read_file(path, offset, limit, pages) |
Numbered text; PDF pages as text |
write_file(path, content) |
Creates parents, overwrites |
edit_file(path, old_string, new_string) |
Exact unique-match substitution |
bash(command, [compress], [timeout], [working_directory]) |
Real shell; stdout/stderr/exit code |
web_search(query, [limit]) |
Multi-provider, rank-fused |
web_fetch(url, [as_html]) |
HTML flattened to text by default |
glob(pattern, [path]) |
Files by pattern, newest first |
grep(pattern, [path], [glob], [type], [output_mode], …) |
Contents by regex; ripgrep if installed |
task_create, task_update, task_list, task_get |
The model's task list, by id |
ask_user(question, [options]) |
Asks you in the REPL; refused elsewhere |
enter_plan_mode() |
Plan mode, once you agree |
glob and grep follow Claude Code's Glob and Grep (output_mode
files_with_matches/content/count, -i, -A/-B/-C, glob, type, multiline,
head_limit, offset); they skip .git, symbolic links, binary files and files over
10 MB, and do not read .gitignore. The task tools follow Claude Code's TaskCreate,
TaskUpdate, TaskList and TaskGet, keep the list for the conversation and report
each change as a todo.updated event (journal and --stream-json);
RAIDER_ENABLE_TASKS=0 offers Claude Code's older TodoWrite as todo_write(todos)
instead. ask_user works
where a person can answer — the REPL on a terminal. In a one-shot run, the Hall, cron
or ACP the call is refused and the model decides itself.
Loadguard. bash refuses heavy commands (prove, make test, dzil test|build|release,
cpanm, docker|podman build|run, cargo build|test, npm test, claude -p|--bg,
codex exec) while the host is out of room: memory pressure
(/proc/pressure/memory full avg10 ≥ LOADGUARD_PSI_FULL, default 10 %; swap used ≥
LOADGUARD_SWAP_USED, default 90 %) or all heavy slots
(LOADGUARD_HEAVY_SLOTS, default half the CPUs) taken by commands of running raiders.
The refusal carries the figures and what to do instead; light commands always run, and
without /proc/pressure nothing is refused. LOADGUARD_THROTTLE=0 turns the gate off;
LOADGUARD_CONFINE=1 additionally starts raider inside a memory-limited systemd user
scope (off by default). The same variables serve the loadguard plugin for Claude Code.
Filesystem tools are confined to the -r/--root directory. bash starts there
(120 s per command unless the call sets timeout; compress shortens the output
for the model) but is a full shell, not confined to it. web_search always has
DuckDuckGo (keyless); Brave, Serper and Google are added automatically when
BRAVE_API_KEY, SERPER_API_KEY, or both GOOGLE_API_KEY + GOOGLE_CSE_ID are
set.
A raider started by the Hall also gets telegram_reply(bot, chat_id, text, [message_thread_id]) (bound to the chat of a Telegram mission, where only
text is needed), hall_status() and hall_spawn(name, mission).
raider config explain says whether the Perl tools are mounted and why;
--export-skill writes the current tool list as a table. You can add MCP tools
from Perl (see Using the engine from Perl).
Permissions
Every tool call passes a permission policy, as in Claude Code (ADR 0021). The mode decides what runs without a rule:
default— reading runs; writing files,bash, the network and messages ask.acceptEdits— also writes and edits files in the project and the additional directories;bashstill asks.plan— read and plan only: writing,bashand messages are refused, even with an allow rule, until the model presents its plan withexit_plan_modeand you accept it.bypassPermissions— everything runs, except what a deny rule names (Claude Code skips deny rules here; raider does not).
The mode is --permission-mode MODE (or --dangerously-skip-permissions), else
permissions.default_mode of the config files, else defaultMode of the Claude
settings, else default. Rules in Claude Code syntax come from the Claude
settings and from .raider/config.yml / ~/.raider/config.yml:
permissions:
allow: [ "Bash(npm run test:*)", "Edit(src/**)" ]
ask: [ "WebFetch" ]
deny: [ "Read(./.env)", "Bash(git push:*)" ]
default_mode: acceptEdits
additional_directories: [ ../docs ]
Deny wins over ask over allow, whatever file a rule is in. An allow rule covers a shell
command only when every part of it (&&, ;, |, ...) is covered and it has no $(...)
or redirection into a file; glob and grep leave out files a Read deny rule names.
In the REPL a call that asks is put to you: yes once, yes for this session (the rule it
adds is shown), or no with a reason for the model. With nobody to ask — a one-shot
run, --json, the Hall, ACP — such a call is refused, and the model is told which
rule or mode would allow it. raider config explain and /permissions show the mode,
the rules and their sources.
Perl-native tools
Three more tools come with --perl, with perl: true in .raider.yml, or — when
neither says otherwise — with an active pack that requests them: the bundled perl
pack, detected in a Perl workspace. perl: false keeps them off.
| Tool | Notes |
|---|---|
perl_eval(code, [stdin], [timeout]) |
Fresh interpreter per call; stdout/stderr/exit |
perl_check(code) |
perl -c — syntax check |
perl_cpanm(module, [options]) |
Install into the raider's private local::lib |
Installs land in a local::lib the raider owns — .raider/lib/ in the working
directory by default (preferred_lib_target in .raider.yml moves it) — which is on
PERL5LIB of every perl_eval and perl_check, so freshly-installed modules are
visible to the next call without a restart. perl_eval also auto-recovers from
Can't locate X/Y.pm in @INC: it installs the missing module once, retries the
eval, and reports what it installed. It never loops. (Note that perl -c runs
BEGIN/use, so perl_check is code execution too.)
Personas, packs and skills
- A persona is tone and style; the default is Langertha in a terse "caveman"
register. Replace it with a
.raider/instructions.md(or.raider.md) file or-M. - A pack is a small, toggleable bundle (a
SKILL.mdplus an optionalpack.yml) stacked on top of the mission. Bundled packs: caveman, polite, teacher (persona group, one active at a time) and git-guru, testing-fu, perl-hacker, perl (power group, stackable). Enable with--pack NAME, toggle in the REPL with/pack, persist underpacks:in.raider.yml. Your own packs go into.raider/packs/<name>/of the project,~/.raider/packs/<name>/or a directory listed inRAIDER_PACK_DIRS; apack.ymlmay setexclusive_group,enabled_by_default,tools: [perl]and adetect:rule. - A skill is know-how — instructions and maybe resources — loaded on demand,
as in Claude Code: the prompt lists every skill as
name: description, and the model loads one with theskilltool, which returns its body and its base directory. Skills come from--skills DIR/skills:directories,.raider/skills/and~/.raider/skills/, and in the Claude layout (below) also from~/.claude/skills/,.claude/skills/,.agents/skills/and the enabled Claude Code plugins (asplugin:skill). A skill withdisable-model-invocation: trueis not offered. Atype: fileentry inskills:is one skill file. A skill withpaths:frontmatter is listed only once a matching file is touched, and a.claude/skillsbelow the working directory is read the first time a file tool touches that subtree (both announced in the tool result).--openai/--codexloadsAGENTS.md.--claude,--openaiand--skillspersist to.raider.ymlon first use (the banner shows(saved)) —--claudeasclaude: true. - An agent is a subagent definition in Claude Code's format (Markdown with
frontmatter) in
.raider/agents/,~/.raider/agents/and, in the Claude layout,.claude/agents/,~/.claude/agents/and enabled plugins;general-purpose, and the read-onlyExploreandPlan(no CLAUDE.md in their prompt), are built in. The model starts one with theagenttool: it runs in the same process with an empty history, the agent file as its instructions and the caller's tools filtered bytools/disallowedTools(neverask_user), and its last text comes back as the tool result. With a session it journals into a child session of its own. Subagents nest up to three levels (max_agent_depth, orCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHin the Claude layout;1turns nesting off). The skills an agent declares (skills,briefing.skills) are put in front of its task as the briefing plugin does, and itsmodelapplies under the Anthropic API.
Claude Code projects
raider reads a project the way it was set up (ADR 0019):
.raider/present — a raider project:.raider/config.ymland.raider/instructions.mdapply; the Claude layout only withclaude: true(or--claude).- no
.raider/, butCLAUDE.mdor.claude/— Claude mode: raider reads the project like Claude Code does.~/.claude/CLAUDE.md, everyCLAUDE.mdandCLAUDE.local.mdfrom the repository top down to the working directory (a level withoutCLAUDE.mduses itsAGENTS.md),@pathimports inside them, and a nestedCLAUDE.mdbelow the working directory the first time a tool touches that subtree.~/.claude/settings.json,.claude/settings.jsonand.claude/settings.local.jsonare merged:envis applied to the tools,enabledPluginsselects plugin skills,permissionsapply (see Permissions),hooksare read (not run yet). There is no raider persona in this mode: the instructions are a neutral base text plus the memory, and no pack is on by default (--packstill works). - neither — raider-native, as before.
raider config explain shows the mode and why, the memory files, the settings
files and what was ignored in them, and every skill with its source.
Packs can also activate by workspace detection (ADR 0012): the bundled perl
pack turns its Perl tools on when it detects a Perl workspace (cpanfile,
dist.ini, Makefile.PL or lib/**/*.pm). --no-detect / detect: false turns
detection off; raider config explain shows what activated and why.
Machine interface
For scripting, six mutually-exclusive flags replace the human output with one format-independent model, written in three encodings:
--json/--msgpack/--yaml— one document, printed once when the run ends.--stream-json/--stream-msgpack/--stream-yaml— an event stream (run.started,tool.call,tool.result,message, ...), the last event (run.finished) carrying that same document.
The document is versioned (--json=N; version 1 is the only one), and within a
version fields are only ever added — a consumer must ignore fields it does not know.
With a machine flag, stdout carries only the machine output; the live trace, if
asked for, goes to stderr. Exit status distinguishes success (0), a failed run
(1), usage errors (2), configuration errors (3), a session in use (4) and
signal cancellation/interruption (130/143). The full schema is in
perldoc raider (ADR 0013).
Raider Hall
You don't need a daemon to use Raider. Raider Hall is the optional daemon for being reachable: it runs raiders on demand, on cron, on a Telegram message, or over the Agent Client Protocol, and supervises long-lived work.
raider hall init --name bjorn --engine anthropic --persona caveman
raider hall add-raider lagertha --engine openai --persona polite --pack git-guru
raider hall start --daemon # foreground: omit --daemon
raider hall ps
raider hall spawn bjorn "summarise yesterday's git log"
raider hall logs <id> --follow
raider hall kill <id>
raider hall stop
Subcommands: init, add-raider, start, stop, status, ps, spawn,
attach, logs, kill, session reset and install (systemd user unit, native
or Docker). Run raider hall <subcommand> --help for per-command options.
A hall is configured by a .raider-hall.yml in its directory:
longhouse: false # true: longhouse/lib of the hall on every raider's PERL5LIB
raiders:
bjorn: { engine: anthropic, persona: caveman, packs: [git-guru] }
lagertha: { engine: openai, model: gpt-4o-mini, persona: polite, packs: [testing-fu] }
ivar: { provider: acme, model: example-model } # an alias from raider provider add
cron:
- { name: 1bjorn, cron: '*/15 * * * *', mission: 'check CI, ping #eng-alerts if red' }
telegram:
bots:
ops: { token: '123456:ABC...', allowlist: [42, 99], routing: { 42: bjorn, '*': lagertha } }
# allowed_chats: [-1001234567890] # group chats to answer in
acp:
port: 38421
provider: takes only an alias stored with raider provider add (raider hall add-raider NAME --provider ALIAS writes it); the hall starts that raider with
--provider ALIAS. A host or https origin is refused, so is an alias that is not
stored, and so is provider next to engine — the hall runs unattended and never
fetches a provider nobody accepted.
Named raiders spawn as child processes; a 1name prefix (e.g. spawn 1bjorn)
forces at most one instance, queuing overlapping missions FIFO. Cron entries fire
non-blocking; Telegram bots long-poll with a per-bot allowlist (Telegram user ids;
empty lets nobody in, group chats must also be in allowed_chats) and routing map,
and answer through the hall. The hall reads .raider-hall.yml once at start, and
starts its raiders with the raider next to it or on PATH
(RAIDER_HALL_RAIDER_BIN overrides that); perldoc raider-hall and
perldoc Langertha::Raider::Hall have the details. There is a fuller walkthrough
under examples/multi-raider-hall/.
ACP (editors)
raider speaks the Agent Client Protocol (Zed's editor protocol), in two directions.
As a server, the Hall exposes ACP over TCP — start it with an ACP port:
raider hall start --acp-port 38421
The server implements initialize, session/new, session/prompt (text) and
session/cancel. A failed run ends session/prompt as a JSON-RPC error (code
-32000), so a client tells a broken run from a reply.
As a client, the bundled dispatcher drives any conforming ACP agent:
raider acp ping 127.0.0.1:38421 # handshake / capabilities
raider acp prompt 127.0.0.1:38421 --raider bjorn "..." # one-shot
raider acp connect 127.0.0.1:38421 --raider lagertha # interactive REPL
The endpoint is HOST:PORT, or just PORT for 127.0.0.1. --json also prints
every session/update notification as raw JSON on stderr for debugging. Under the
hood this is Langertha::Raider::ACP::Client, a small blocking JSON-RPC 2.0 client
you can embed in your own Perl.
The stdio ACP server an editor starts directly (
raider acpas the agent command), and driving remote raiders asraider NAME@HOST, are on the roadmap (ADR 0010).
Using the engine from Perl
use Langertha::Raider;
use Langertha::Engine::Anthropic;
use Future::AsyncAwait;
my $engine = Langertha::Engine::Anthropic->new(
api_key => $ENV{ANTHROPIC_API_KEY},
mcp_servers => [ $mcp ], # any Langertha engine with tool calling
);
my $raider = Langertha::Raider->new(
engine => $engine,
mission => 'You are a code reviewer.',
);
my $result = await $raider->raid_f('What files are in lib/?');
say $result;
raid_f runs one turn's worth of the agent loop and returns a
Langertha::Raider::Result (is_final, is_question, is_pause, is_abort,
is_cancelled);
respond_f answers back into the same conversation. Langertha::Raid orchestrates
several runnables (Raid::Sequential, Raid::Parallel, Raid::Loop). Attaching
MCP tools is covered in the Langertha docs.
Docker
A prebuilt image is on Docker Hub as
raudssus/raider. The bundled
Dockerfile is multi-stage with two runtime targets: runtime-root (the Docker Hub
default, tag :latest / :<version>) and runtime-user (non-root, uid/gid
matchable to the host for interactive use in real project trees).
runtime-root is the last stage, so a build without --target yields it.
docker pull raudssus/raider
docker run --rm -it -v "$PWD:/work" -e ANTHROPIC_API_KEY raudssus/raider
A convenient shell alias mounts $PWD into /work, keeps REPL history, and forwards
the API-key env vars:
raider() {
docker run --rm -it \
-v "$PWD:/work" \
-v "$HOME/.raider_history:/root/.raider_history" \
-e ANTHROPIC_API_KEY -e OPENAI_API_KEY -e DEEPSEEK_API_KEY \
-e GROQ_API_KEY -e MISTRAL_API_KEY -e GEMINI_API_KEY \
-e MINIMAX_API_KEY -e CEREBRAS_API_KEY -e OPENROUTER_API_KEY \
-e BRAVE_API_KEY -e SERPER_API_KEY -e GOOGLE_API_KEY -e GOOGLE_CSE_ID \
raudssus/raider "$@"
}
Build locally
The Dockerfile installs from the Dist::Zilla-built distribution directory (via
cpm with the MetaCPAN resolver), not from a
tarball in the build context. Build the dist directory first and use it as the
context:
dzil build
VERSION=$(perl -Ilib -MLangertha::Raider::CLI -E 'say $Langertha::Raider::CLI::VERSION')
docker build \
--build-arg RAIDER_VERSION=$VERSION \
--target runtime-user \
--build-arg RAIDER_UID=$(id -u) \
--build-arg RAIDER_GID=$(id -g) \
-t raider:local Langertha-Raider-$VERSION
Leave --target out (or use --target runtime-root) for a root image. With the
dist.ini as shipped, dzil build also builds the published raudssus/raider
image (stage runtime-root) through the container engine at DOCKER_HOST; run
DZIL_DOCKER_API_SKIP=1 dzil build to build only the dist directory. On
release, the [@Author::GETTY] bundle pushes that image to Docker Hub as
latest, <major> and <version> and publishes the GitHub release; that is
the maintainer's step (dzil release).
Binary (no Perl needed)
Prebuilt Linux binaries are attached to each
GitHub release:
raider-<version>-linux-x86_64 and raider-<version>-linux-aarch64, each as a raw
executable and a .tar.gz (binary, LICENSE, README); a single
raider-<version>-checksums.txt covers them all.
v=0.xxx # the release you want
curl -fLO https://github.com/Getty/langertha-raider/releases/download/$v/raider-$v-linux-x86_64
curl -fLO https://github.com/Getty/langertha-raider/releases/download/$v/raider-$v-checksums.txt
sha256sum -c --ignore-missing raider-$v-checksums.txt
install -m 755 raider-$v-linux-x86_64 ~/.local/bin/raider
The binary is a PAR::Packer build (~15 MB)
that carries its own Perl, every module and the shipped packs. Besides glibc 2.36 or
newer, the target needs only OpenSSL 3 — libssl and libcrypto (Debian/Ubuntu:
libssl3), present on any normal Linux. The first start unpacks into
/tmp/par-<user>/ and takes a few seconds; after that it starts about as fast as the
CPAN install. It is for distribution convenience, not speed. raider --version
shows which raider and Langertha it carries. Only raider ships as a binary — use
raider hall … where you would run raider-hall; a hall started from the binary
spawns its raiders with the binary itself (RAIDER_HALL_RAIDER_BIN still overrides
that).
To build one yourself from a checkout (needs PAR::Packer and the dependencies
installed): scripts/build-binary.sh, then scripts/verify-binary.sh ./raider and
scripts/check-binary-libs.sh ./raider. Release builds run in the
release-binaries GitHub workflow on perl:5.40-bookworm, so they run on older
distributions too.
Roadmap / Planned
The items below are not yet implemented — they are the decided direction, each
backed by an ADR in docs/adr/. The full target-state vision and
vocabulary live in CONTEXT.md; it lands in small vertical slices.
- The home assistant profile & directory model (ADR 0011) — a dedicated
~/.raider/home (config.yml,instructions.md,skills/,raiders/<name>.yml,sessions/,memory/) that never bleeds into projects, a<project>/.raider/config layer, and araider config migratefrom today's.raider.yml/.raider.md. Today: per-project.raider/config.ymland.raider/instructions.md(or the legacy.raider.ymland.raider.md, whichraider config migrateconverts) and the home~/.raider/config.ymlunder them. - Inspectable context & diagnostics (ADR 0004) — a per-call, itemized
ContextPlanyou can read withraider context explain, araider doctorhealth check, per-directory instruction walking, and an explicit workspace-trust decision. Today:raider config explain. - Permissions & policy (ADR 0005) — one active tool set with real capability
grants,
raider policy check/raider tools explain, approvals tied to the exact call, a "headless never allows all" rule, and a home-serviceproject_toolsmapping. Today: permission modes and rules like Claude Code, approvals of the exact call in the REPL (ADR 0021), filesystem tools confined to--rootand the additional directories. - Provider discovery (ADR 0007) —
raider --provider host.tldandraider provider addon top of the declarative.well-known/langertha.jsonmanifest, with a local credential binding and alias. Today:raider provider inspectfetches, validates and shows a manifest,raider --provider HOST -k KEYruns on its endpoint for one run, andraider provider add ALIAS HOSTstores a pinned alias that--provider ALIASruns on. - Delegates: Codex & Claude Code (ADR 0006) —
--use-codex/--use-claudeaddingask_codex/ask_claudetools driven through a narrow task contract, andraider delegate inspect; the official binaries own their own login. - Remote raiders & editor stdio (ADR 0010) —
raider NAME@HOST ...over SSH with ACP as the conversation, andraider acpas the stdio ACP server an editor starts directly. Today: ACP server via the Hall over TCP, ACP client viaraider acp. - Reviewed long-term memory (ADR 0008) — memory and lesson candidates proposed
after a session that only become active on review, with
raider memory list/explain/approve/forget. Today: the per-session journal plus automatic context compression.
License
This software is copyright (c) 2026 by Torsten Raudssus.
It is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

