How rikul/anotherbot works
1. What this repo is
- A Python 3.12 AI-agent runtime that wraps an OpenAI-compatible LLM client with tool use, persistence, and multiple interaction surfaces.
- The architecture is split into two execution modes: an interactive CLI and a long-running background bot.
2. Top-level execution paths
- app/main.py is the main entry point.
- app/cli/cli.py and app/cli/cli_agent.py drive the interactive REPL / single-shot CLI flow.
- app/bg_server.py starts the persistent background process that consumes channel messages and scheduled tasks.
3. Core agent loop
- app/core/agent.py, background_agent.py, and helper_agent.py implement the LLM-driven reasoning loop.
- app/core/client.py is the model client boundary; the README indicates it targets an OpenAI-compatible API, defaulting to OpenRouter.
- app/core/tool.py and tool_calls.py connect model tool calls to concrete Python tool implementations.
4. Tooling boundary
- Tools are discrete capabilities under app/tools/ and are the main action layer exposed to the model.
- The tool set includes filesystem ops (read_file, write_file), shell execution (bash), web access (web_fetch, web_search), utility functions (calculator, get_datetime, get_city_state), data sources (hackernews), and task/todo helpers.
- app/core/tool_calls.py acts as the registry/dispatcher boundary between model-generated function calls and tool execution.
5. Skills subsystem
- app/skills/ is an extensibility boundary for higher-level capability bundles.
- The existing puppeteer skill suggests the system can delegate complex workflows to packaged instructions or playbooks rather than hardcoding every behavior into tools.
- app/tools/get_skills_dir.py indicates the runtime can discover and expose the skills directory to the agent.
6. Interactive CLI flow
- The CLI is a human-in-the-loop interface for prompt execution, iterative tool use, and optional permission prompts.
- It supports multi-turn REPL sessions, auto-approve mode, and silent/non-REPL modes as described in the README.
- This path is optimized for local operator control rather than external messaging.
7. Background agent and channel adapters
- app/channels/channel.py defines the channel abstraction; concrete adapters live in discord.py and telegram.py.
- message.py and message_queue.py indicate each channel feeds messages into a queue before the agent processes them.
- This creates a clean boundary between transport-specific APIs and the shared agent logic.
8. Per-channel isolation
- The background architecture is explicitly multi-tenant by channel: each channel gets its own queue and message history.
- Discord and Telegram are handled as separate transports, but they converge into the same agent loop and tool stack.
- The README notes scheduled-task results are routed back to the originating channel, with Discord owner DM fallback when context is missing.
9. Persistence and state
- app/infra/message_history.py and app/core/scheduled_tasks.py suggest SQLite-backed persistence for conversation history and task definitions.
- The README describes persistent storage under ~/.crafterscode/ and shared state between history and scheduled tasks.
- This persistence layer is an important architectural boundary because it survives restarts and supports long-lived background operation.
10. Scheduled task subsystem
- app/tools/sched_tasks_tool.py exposes task management to the agent, while app/core/scheduled_tasks.py likely executes and tracks scheduled runs.
- Tasks can be one-shot or recurring, and they are executed by the background process rather than the CLI.
- This subsystem bridges LLM-driven task creation with durable, delayed execution.
11. Infrastructure and startup
- app/infra/setup.py, startup.py, helpers.py, app_logging.py, and term_display.py handle bootstrap, configuration, logging, and terminal UX.
- app/config.py plus app/config.toml define runtime configuration, while app/env.example and the README describe env-var precedence.
- These modules form the application wiring layer: loading config, initializing persistence, and preparing the correct runtime mode.
12. Deployment and external boundaries
- The repo is containerized with a Dockerfile, and the README shows separate deployment shapes for CLI and background bot use.
- External dependencies that materially shape the architecture are the LLM provider, Telegram, Discord, the local filesystem, shell execution, and SQLite.
- CI and tests cover the main boundaries: agent loop, tool execution, channels, startup, and the background server.
13. How to draw the architecture
- A useful diagram would center on the shared agent/core layer, with three major inputs: CLI, Telegram, and Discord.
- All inputs flow through a message queue / agent loop into tools and persistence, while scheduled tasks form a parallel trigger path into the same agent and delivery pipeline.
- The main separation lines are: transport adapters, agent reasoning, tool execution, and durable state.
Main entry points: tool_calls.py tool calls · agent.py agent · startup.py startup · main.py main
Components 27
CLI
Interactive human-in-the-loop execution path.
Background
Persistent bot runtime and channel adapters.
- bg server · Starts the persistent background process.
app/bg_server.py - channel · Shared interface for transport adapters.
app/channels/channel.py - Discord · Discord transport into the shared agent loop.
app/channels/discord.py - Telegram · Telegram transport into the shared agent loop.
app/channels/telegram.py - queue · Buffers inbound channel messages for processing.
app/channels/message_queue.py
Core
Shared agent loop, model boundary, and scheduling.
- agent · Primary LLM-driven agent loop.
app/core/agent.py - bg agent · Agent variant used by the long-running server.
app/core/background_agent.py - helper agent · Auxiliary agent used for specialized tasks.
app/core/helper_agent.py - LLM client · OpenAI-compatible model client boundary.
app/core/client.py - tool calls · Resolves model function calls to tool execution.
app/core/tool_calls.py - schedules · Durable scheduled-task tracking and execution.
app/core/scheduled_tasks.py - tool base · Common tool abstraction used by the agent.
app/core/tool.py
Tools
Action layer exposed to the model.
- files · Read and write file capabilities.
app/tools/read_file.py - shell · Shell command execution capability.
app/tools/bash.py - web · Fetch and search web content.
app/tools/web_fetch.py - utils · Datetime, calculator, and location helpers.
app/tools/calculator.py - task tools · Task and todo management exposed to the agent.
app/tools/sched_tasks_tool.py
Infra
Startup, config, logging, and persistence wiring.
- main · Top-level launcher that selects runtime mode.
app/main.py - history · Persistent conversation and message storage.
app/infra/message_history.py - setup · Application initialization and wiring.
app/infra/setup.py - startup · Loads config, initializes services, and selects mode.
app/infra/startup.py - config · Configuration loading and defaults.
app/config.py - logging · Application logging setup.
app/infra/app_logging.py
Skills
Packaged higher-level capabilities.
- skills dir · Exposes packaged skills to the runtime.
app/tools/get_skills_dir.py - puppeteer · Packaged workflow skill.
app/skills/puppeteer/SKILL.md
Connections 30
- main → startup: boots · Entry point initializes the selected runtime.
- startup → config: loads · Startup reads runtime configuration.
- startup → setup: wires · Startup prepares services and dependencies.
- startup → logging: initializes · Logging is configured during boot.
- main → CLI: runs · Main can launch the interactive CLI path.
- main → bg server: runs · Main can launch the background server path.
- CLI → CLI agent: drives · CLI delegates prompt handling and iteration.
- CLI agent → agent: invokes · Interactive flow uses the shared agent loop.
- bg server → bg agent: starts · Background server uses the long-running agent variant.
- bg server → channel: listens · Server consumes messages from channel adapters.
- channel → Discord: implements · Discord is a concrete transport adapter.
- channel → Telegram: implements · Telegram is a concrete transport adapter.
- Discord → queue: queues · Inbound Discord messages are buffered for processing.
- Telegram → queue: queues · Inbound Telegram messages are buffered for processing.
- queue → bg agent: feeds · Queued channel messages are handed to the agent.
- agent → LLM client: queries · Agent asks the model client for responses.
- agent → tool calls: dispatches · Agent routes model tool calls to execution.
- tool calls → tool base: uses · Dispatcher relies on the shared tool abstraction.
- tool calls → files: routes · Filesystem actions are dispatched to file tools.
- tool calls → shell: routes · Shell actions are dispatched to execution tools.
- tool calls → web: routes · Web actions are dispatched to network tools.
- tool calls → utils: routes · Utility actions are dispatched to helper tools.
- tool calls → task tools: routes · Task actions are dispatched to scheduling tools.
- agent → helper agent: spawns · Primary agent can delegate to a helper agent.
- agent → history: reads/writes · Agent persists conversation state.
- bg agent → schedules: executes · Background agent handles delayed and recurring work.
- schedules → history: persists · Scheduled task state shares durable storage.
- task tools → schedules: manages · Task tools create and modify scheduled work.
- skills dir → puppeteer: exposes · Skills directory discovery surfaces packaged skills.
- agent → skills dir: discovers · Agent can discover available skills at runtime.