/ 
App-Raider-0.003
/ App::Raider

NAME

App::Raider - Autonomous CLI agent that can browse directories, edit files, and run bash commands

VERSION

version 0.003

SYNOPSIS

use App::Raider;

my $app = App::Raider->new(
    # engine/model/api_key auto-detected from *_API_KEY env vars
    root           => '/path/to/project',
    skill_sources  => [
        { type => 'file',   path => 'CLAUDE.md' },
        { type => 'claude', path => '.claude/skills' },
    ],
    engine_options => { temperature => 0.2 },
);

my $result = $app->run('Explore the repo and summarize it.');
print $result;

DESCRIPTION

App::Raider wraps Langertha::Raider with a standard toolbox for a working coding/system agent:

The distribution intentionally stays small. It is the thin CLI-oriented layer on top of Langertha's engine/agent machinery. The CLI front-end is raider.

engine_name

Langertha engine class shortcut (e.g. 'anthropic', 'openai', 'deepseek', 'groq', 'mistral', 'gemini', 'ollama'). Defaults to 'anthropic'.

default_model_for_engine

Per-engine default model when "model" is not explicitly set.

model

Model identifier to pass to the engine. If unset, the engine picks its default.

api_key_env

Name of the environment variable used for the current engine's API key (for display / debugging). Returns undef for engines that don't use an API key (e.g. ollama).

api_key

API key for the engine. Defaults to an engine-appropriate environment variable.

mission

System prompt / mission statement for the Raider. Defaults to a generic assistant persona.

root

Working directory for tool operations. Defaults to the current process cwd. File tools are chrooted to this directory; bash commands inherit it as their default working directory.

allowed_commands

Optional arrayref restricting which bash commands may run (first word match). When undef, any command is allowed.

max_iterations

Maximum tool-calling iterations per raid. Defaults to 10_000 — effectively unlimited, so a raid only ends when the model itself stops emitting tool calls. The conversation history is preserved between raids, so the next user message in the REPL simply continues the same thread.

Set this to a smaller number if you want a hard safety cap.

trace

Emit live ANSI-colored progress output (iteration markers, tool calls, tool results) via App::Raider::Plugin::Trace. Defaults to on when STDOUT is a terminal.

max_context_tokens

Trigger history auto-compression once the last prompt exceeds context_compress_threshold * max_context_tokens. Defaults to 40_000, which keeps the running session comfortably under typical per-minute rate limits (Anthropic org default: 50k input tokens/min on Haiku).

context_compress_threshold

Fraction of "max_context_tokens" at which compression kicks in. Defaults to 0.7.

skill_sources

ArrayRef of skill-source specs to load and append to the mission. Each spec is a hashref:

{ type => 'claude', path => '.claude/skills' }  # Claude Code SKILL.md tree
{ type => 'dir',    path => 'my-skills', glob => '*.md' }

Settable via "skill_sources", via the skills key in .raider.yml, or via the CLI flags --claude / --skills PATH.

engine_options

HashRef of extra attributes forwarded to the engine constructor (e.g. temperature, response_size, seed). Merged on top of values loaded from .raider.yml in the working directory.

raid_f

my $result = await $app->raid_f($prompt);

Async variant: drives one raid iteration and returns the Langertha::Raider::Result.

run

my $result = $app->run($prompt);

Synchronous convenience wrapper around "raid_f". Runs the I/O loop until the raid completes and returns the result (which stringifies to the final text).

raider

Returns the underlying Langertha::Raider instance (lazily built).

trace_plugin

Returns the loaded App::Raider::Plugin::Trace instance, or undef if trace is disabled.

loaded_skill_names

Returns a list of skill names currently discoverable from the configured "skill_sources". Intended for banner/status display.

ignored_agent_files

Returns a list of per-tool agent files that exist in the working root but are NOT covered by the current "skill_sources". Intended to power the banner's "seeing AGENTS.md, ignoring" notice.

token_stats

Cumulative token counts for this session (hashref with prompt, completion, total, calls) — available when trace is enabled.

reload_mission

Rebuilds the mission (e.g. after .raider.md has been edited) and swaps it into the underlying Langertha::Raider.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-app-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.