🤖 BotiasLoop

Think. Act. Repeat.

A minimal agentic AI application built on the ReAct (Reasoning + Acting) loop pattern.

BotiasLoop gives your AI agent full shell access and web search capabilities via multiple LLM providers. Designed for dedicated infrastructure following the Rails Doctrine — beautiful code, sensible defaults, sharp knives.

🚀 Installation

Prerequisites

Ruby 3.4 or higher
API key from your preferred LLM provider (see supported providers below)
(Optional) SearXNG instance for web search

Via RubyGems

gem install botiasloop

From Source

git clone https://github.com/0x7466/botiasloop.git
cd botiasloop
bundle install
bundle exec rake install

Using mise (Recommended)

# Install mise if not already installed
curl https://mise.run | sh

# Install Ruby and dependencies
mise install

# Run with mise-managed Ruby
mise exec ruby -- bundle install

⚡ Quick Start

# 1. Configure your API key
export BOTIASLOOP_API_KEY="your-api-key"

# 2. Start chatting
botiasloop cli

# 3. Ask anything!
You: What's the weather in Tokyo?

Agent: I'll search for the current weather in Tokyo for you.

[Tool] Executing web_search with arguments: {"query"=>"current weather Tokyo Japan"}

The weather in Tokyo is currently...

✨ Features

🧠 Core Capabilities

ReAct Loop — AI reasons, acts using tools, observes results, and repeats
12+ LLM Providers — OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Perplexity, Ollama, and more
Shell Access — Execute any shell command (full system access)
Web Search — Search the web via SearXNG integration
Token Tracking — Monitor input/output tokens per conversation

💬 Channels & Interfaces

CLI Mode — Interactive REPL for local usage
Telegram Bot — Chat with your agent anywhere
Multi-Channel — Run CLI + Telegram simultaneously
One-Shot Mode — Single command execution

🗄️ Conversation Management

Persistent Storage — JSONL-backed conversation history
UUID Tracking — Every conversation has a unique ID
Auto-Labeling — Conversations get human-readable names
Conversation Switching — Jump between active chats
Archiving — Keep your workspace clean

🛠️ Built-in Tools

Tool	Description
🔧 `shell`	Execute any shell command
🔍 `web_search`	Search the web via SearXNG

📚 Skills System

Skills follow the agentskills.io specification:

Load default skills from data/skills/
Load custom skills from ~/skills/
Progressive disclosure: name/description in system prompt, full content on demand
Includes skill-creator skill for creating new skills

⌨️ Slash Commands

Manage conversations with intuitive commands:

Command	Description
`/new`	Start a new conversation
`/switch <label\	uuid>`
`/label <name>`	Label the current conversation
`/conversations`	List all conversations
`/reset`	Clear current conversation history
`/compact`	Summarize and archive old messages
`/status`	Show current model, token usage
`/archive`	Archive old conversations
`/system_prompt`	Show current system prompt
`/verbose`	Toggle verbose mode (show tool calls)
`/help`	Show available commands

🎨 Philosophy

Sharp Knives 🔪

BotiasLoop intentionally provides full shell access without restrictions. This is a feature, not a bug. It's designed for dedicated infrastructure where raw power is needed, not personal devices.

The agent can:

Execute any shell command
Read, write, and delete any file
Install software
Modify system configuration
Access network resources

Rails Doctrine 🚂

Following the Rails Doctrine:

Optimize for programmer happiness — Beautiful, readable Ruby code
Convention over Configuration — Sensible defaults, minimal setup required
The menu is omakase — Curated stack (ruby_llm, StandardRB, RSpec)
No one paradigm — Practical over pure - use what works

📖 Usage

CLI Mode

Start interactive REPL:

botiasloop cli

Exit with: exit, quit, \q, or Ctrl+C

One-Shot Mode

Send a single message:

botiasloop "What's the weather in Tokyo?"

Gateway Mode (Telegram Bot)

Start the gateway to enable Telegram and other channels:

# Run in foreground
botiasloop gateway

# Systemd service management (boot auto-start)
botiasloop gateway enable   # Install and enable boot auto-start
botiasloop gateway start    # Start the service now
botiasloop gateway status   # Check service status
botiasloop gateway stop     # Stop the service
botiasloop gateway logs     # View service logs
botiasloop gateway disable  # Disable boot auto-start and uninstall

Example Session

$ botiasloop cli

botiasloop v0.0.1 - Interactive Mode
Type 'exit', 'quit', or '\q' to exit

You: What files are in this directory?

Agent: I'll check what files are in the current directory for you.

[Tool] Executing shell with arguments: {"command"=>"ls -la"}

Exit: 0
Stdout:
total 128
drwxr-xr-x  10 user  staff   320 Feb 22 14:00 .
drwxr-xr-x   5 user  staff   160 Feb 22 13:00 ..
-rw-r--r--   1 user  staff  2345 Feb 22 14:00 README.md
...

Here are the files in your current directory...

You: /label my-project

Agent: **Conversation labeled as `my-project`**

You: /verbose

Agent: **Verbose mode enabled** — You will now see reasoning and tool execution details.

You: exit

Goodbye!

⚙️ Configuration

Create ~/.config/botiasloop/config.yml:

OpenRouter (Recommended)

providers:
  openrouter:
    api_key: "your-openrouter-api-key"
    model: "moonshotai/kimi-k2.5"

OpenAI

providers:
  openai:
    api_key: "your-openai-api-key"
    model: "gpt-4o"

Anthropic

providers:
  anthropic:
    api_key: "your-anthropic-api-key"
    model: "claude-3-5-sonnet-20241022"

Ollama (Local)

providers:
  ollama:
    api_base: "http://localhost:11434/v1"
    model: "llama3.2"

Full Configuration Example

# Required: Provider configuration
providers:
  openrouter:
    api_key: "your-api-key"
    model: "moonshotai/kimi-k2.5"

# Optional: Web search configuration
tools:
  web_search:
    searxng_url: "http://localhost:8080"

# Optional: Maximum ReAct iterations (default: 20)
max_iterations: 20

# Optional: Telegram channel
channels:
  telegram:
    bot_token: "your-telegram-bot-token"
    allowed_users: ["your_telegram_username"]  # Required: must contain at least one username

# Optional: Logging
logger:
  level: "info"  # debug, info, warn, error
  destination: "stdout"  # stdout, stderr, or path to log file

Environment Variables

Environment variables override config file values:

Variable	Description
`BOTIASLOOP_API_KEY`	API key for the active provider
`BOTIASLOOP_SEARXNG_URL`	SearXNG URL for web search
`BOTIASLOOP_LOG_LEVEL`	Log level (debug, info, warn, error)

🔒 Security

⚠️ IMPORTANT: BotiasLoop provides full shell access. The AI agent can:

Execute any shell command
Read, write, and delete any file
Install software
Modify system configuration
Access network resources

Use only on dedicated infrastructure, never on personal devices or production systems containing sensitive data.

Future Security Features (Roadmap)

Sandboxed execution (Docker/Firejail)
Command whitelist/blacklist
Confirmation for destructive operations
Read-only mode option
Secret management integration

🛠️ Development

Setup

# Clone repository
git clone https://github.com/0x7466/botiasloop.git
cd botiasloop

# Install dependencies
bundle install

Testing

Test-first development is required:

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/unit/agent_spec.rb

# Run specific test by line number
bundle exec rspec spec/unit/agent_spec.rb:42

# Check coverage (after running tests)
open coverage/index.html

Linting

Code must pass StandardRB with zero offenses:

# Check for offenses
bundle exec standardrb

# Auto-fix offenses
bundle exec standardrb --fix

Default Rake Task

# Run tests + linting
bundle exec rake

📁 Architecture

botiasloop/

🗺️ Roadmap

See ROADMAP.md for detailed planned features:

Persistent Memory — Vector database for semantic search
Custom Tools — Load tools from ~/tools/
Conversation Compaction — Automatic summarization
Subagents — Specialized agent instances
Streaming Responses — Real-time token display
Multi-Modal — Image analysis, audio transcription
Web Dashboard — Browser-based management UI
Plugin System — Load plugins from gems

🤝 Contributing

Fork the repository
Create a feature branch
Write tests first (TDD required)
Implement the feature
Ensure all tests pass: bundle exec rspec
Ensure zero linting offenses: bundle exec standardrb
Commit with descriptive message
Push to your fork
Create a Pull Request

Development Principles

Test-First — All features built using TDD
Sharp Knives — Keep raw power, minimal restrictions
Rails Doctrine — Optimize for programmer happiness
Privacy First — Local-first, user-controlled data
Unix Philosophy — Do one thing well, compose with other tools

📜 License

MIT License — see LICENSE file for details.

🙏 Credits

Built by Tobias Feistmantl with inspiration from nanobot and the Ruby on Rails doctrine.

ruby_llm — Unified LLM API
OpenRouter — Unified LLM API gateway
SearXNG — Privacy-respecting metasearch

⚡ Built with sharp knives. Use responsibly.