The ShellAgents system is a purely shell-script–based multi-agent framework developed by Claus Siebeneicher that deliberately avoids external runtime environments such as Python, Node.js, or Java. Instead, it relies exclusively on standard Unix/Linux/macOS commands (bash, jq, curl, awk, sed).

This architectural decision provides fundamental security advantages:

• No packages need to be installed from npm, PyPI, or Maven repositories that could potentially be compromised.
• There are no hidden dependency chains (“dependency hell”), no automatic third-party library updates, and no interpreters capable of executing arbitrary code from unknown sources.

The only external dependency is the LLM API (e.g., OpenRouter, local LM Studio, etc.), and even here all LLM outputs pass through a multi-layer security filter (security_filter.sh) that prevents <script> tags, shell commands, or other unsafe constructs from entering the processing pipeline.

All code is fully transparent and human-readable (shell scripts), entirely auditable without compiler obfuscation, and runs inside a controlled sandbox environment, where system administrators know precisely which commands can be executed.

This is a critical property for enterprise environments and security-sensitive deployments, where supply chain attacks through compromised npm packages or Python libraries are an increasing risk.

Why shell-only helps

• No npm/PyPI/Maven installs → lower supply-chain exposure
• Transparent ops: plain shell scripts; auditable logs/history
• Air-gap friendly: local LLMs, offline mode supported

Risk Reduction

Why this is useful: Common Criteria / ITSEC Environments

• Shell-only systems simplify security certification (no external runtimes)
• Fully auditable code paths align with Common Criteria and NIST SP 800-53 principles
• Ideal for classified or restricted networks—no internet dependencies
• Supports ENISA risk management and controlled change management
• Facilitates evaluation and accreditation for ITSEC-compliant deployments

Why this is useful: Avoid npm incidents

• Supply-chain worm hit 100+ packages → Shai-Hulud analysis (Wiz)
• Worm replicated via stolen tokens → ReversingLabs brief
• Official post-mortem: event-stream backdoor → npm security note
• ua-parser-js published with malware → CISA alert
• Maintainer sabotage (colors.js / faker.js) → The Verge report

Why this is useful: Avoid risk mechanics

• Typosquatting & dependency chains → Google/Mandiant overview
• Prototype Pollution ⇒ RCE in Node.js → Peer-reviewed research
• Deep dive on event-stream attack → Snyk post-mortem

Why this is useful: GDPR compliance through local processing

• No data transmission to cloud LLM providers → complete control over personal data per Art. 5 GDPR
• Local LLMs eliminate third-country transfers → fulfillment of Art. 44-50 GDPR without additional safeguards
• Privacy by Design from the start → natural implementation of Art. 25 GDPR
• No Data Processing Agreements with LLM vendors required → simplified compliance per Art. 28 GDPR
• Local search instead of external APIs → avoidance of unintended data disclosure
• Complete audit trails and erasability → fulfillment of Art. 17 GDPR (Right to erasure)

ShellAgents – AI Orchestration Framework

The Challenge: Complex Tasks Require Multiple Experts

• ❌ Traditional AI: One model attempts to handle everything
• ❌ Result: Shallow analysis, missing expertise, inconsistent results

The ShellAgents Approach

• Modular Multi-Agent System: Coordinates multiple specialized AI agents
• Domain Expertise: Based on 20+ archetypes for adaptable specialization
• Quality Assurance: Built-in validation and fact-checking procedures
• Shell-Based: Runs on Unix tools, without Python or JS dependencies
• Full Transparency: Every step traceable and auditable

Intended Benefits

• Secure and transparent — suitable for local or offline operation
• Adaptable to any domain or data environment
• Integrates with project tools like OpenProject
• Reduces hallucination by enforcing real-source grounding
• Automates structured workflows from query to output

Typical Use Cases

• Market and policy research
• Compliance and audit support
• Technical documentation
• Strategic and organizational planning
• Fact-based content generation

Step 1 – Issue Submission

ShellAgents operates through simple, auditable commands executed in a Unix shell. Each command initializes a new issue or project folder with its own agent team, resources, and output structure.

./scripts/solve_issue.sh market_analysis "Analyze renewable energy trends in Germany for 2025"

What Happens

• Analyzes the input request and identifies required expertise domains
• Creates a local directory structure and workflow file

Brain/Issue/market_analysis/
├── staff/              # Agent workspaces
├── shared_knowledge/   # Cross-team resources
├── reports/            # Deliverables
└── laufzettel.json     # Task definitions and dependencies

Agents such as ResearchAnalyst, PolicyExpert, DataAnalyst, and TechnicalWriter are selected automatically based on the issue type. Each installation can define its own agent archetypes and task logic.

Step 2 – Task Planning & Optimization

ShellAgents generates a structured plan file (laufzettel.json) describing all required tasks, dependencies, and roles. This ensures clarity and reproducibility before any execution begins.

{
  "tasks": [
    {
      "id": "task_001",
      "name": "Market size analysis for the German renewable sector",
      "agent_responsible": "ResearchAnalyst",
      "dependencies": [],
      "raci_matrix": {
        "responsible": "ResearchAnalyst",
        "accountable": "Boss",
        "consulted": ["PolicyExpert"],
        "informed": ["TechnicalWriter"]
      }
    }
  ]
}

Optimization Features

• Dependency validation for logical sequencing
• Refinement of questions for precision
• Duplicate detection and cleanup
• Balanced task distribution among agents

This structured planning method can be customized or integrated with other project management systems.

Step 3 – Agent Execution

Each agent performs its tasks autonomously, using real-time data sources and command-line tools to ensure traceable results.

ResearchAnalyst

TOOL_REQUEST: web_search "German renewable energy statistics 2024"
TOOL_REQUEST: fetch_page "https://energy-charts.info"
TOOL_REQUEST: assess_credibility "https://bmwk.de/renewable-report"

Available Tools

• web_search / brave_search – external information gathering
• fetch_page – content retrieval
• assess_credibility – source validation
• smart_content – contextual content extraction

Each command produces verifiable output files and metadata, allowing full transparency and replay capability.

Step 4 – Quality Assurance & Synthesis

ShellAgents includes quality validation stages that score and verify results before final synthesis. These checks can be adapted to different organizational standards.

• Numerical quality scoring (0–10)
• URL and data source verification
• Fact-grounding and evidence traceability
• Content completeness and consistency

Outputs are merged through the DocumentSynthesizer process, which combines findings from all agents into structured summaries and full reports.

The QA and synthesis layers can be extended with custom scoring or compliance rules.

Step 5 – OpenProject Integration (Optional)

ShellAgents can export project data to OpenProject for visual task tracking and team collaboration. This feature is optional and can be enabled per installation.

./scripts/openproject/deploy_issue_to_openproject.sh market_analysis

• All tasks imported as work packages with dependencies
• Custom fields for results and metadata
• Agent roles mapped to RACI responsibilities
• Gantt and progress views supported

Integration scripts are adaptable for other project management systems as well.

Security & Transparency Principles

The ShellAgents architecture prioritizes verifiability and minimal dependencies. It is fully shell-based and avoids opaque runtime environments.

• No npm/pip dependencies — only native Unix tools (sed, curl, jq)
• All operations visible through shell history and logs
• Immediate manual control via system signals (Ctrl+C, etc.)
• Works offline with local LLMs such as LM Studio or Ollama
• Fully compatible with air-gapped and sensitive environments

ShellAgents can be deployed on macOS or Linux systems with standard Unix tools.

Example Applications

Each deployment is different. The examples below show typical applications where the ShellAgents approach has been tested or prototyped.

These examples demonstrate possible applications. Actual implementation depends on data access, task definition, and infrastructure.

Getting Started

ShellAgents is an evolving framework. You can experiment with the scripts and adapt them to your own workflow or request guidance for a tailored setup.

Quick Start

# Example command
./scripts/solve_issue.sh your_project "Your complex business question"

Implementation Options

• Local or remote installation (macOS/Linux)
• Integration with your own project tools or APIs
• Custom agent definitions for your domain

Support & Collaboration

• Technical documentation and examples available
• Community-driven improvements and feedback welcome
• Consulting and onboarding support upon request

ShellAgents is a project about collaboration, transparency, and trust in AI automation — not about selling software. Each setup is unique, and every user remains in full control of their data.

Examples

The examples are for demonstration only. They may contain errors, are not validated, and have known limitations. The links in the TOC are broken. Partly the model (mostly Gwen-30b) has hallucinated. All information is based on public research, no specialised agents or specialised databases or templates were used, therefore the quality is limited.

Input to the system and the results: (yes, only this)