# rikul/anotherbot architecture

> Architecture diagram of the GitHub repository rikul/anotherbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rikul/anotherbot
- Repository: https://github.com/rikul/anotherbot

## Overview

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: [`app/core/tool_calls.py`](https://github.com/rikul/anotherbot/blob/main/app/core/tool_calls.py) (tool calls), [`app/core/agent.py`](https://github.com/rikul/anotherbot/blob/main/app/core/agent.py) (agent), [`app/infra/startup.py`](https://github.com/rikul/anotherbot/blob/main/app/infra/startup.py) (startup), [`app/main.py`](https://github.com/rikul/anotherbot/blob/main/app/main.py) (main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI"]
  node_cli["CLI<br/>interactive shell<br/>[cli.py]"]
  node_cli_agent["CLI agent<br/>cli orchestration<br/>[cli_agent.py]"]
end

subgraph group_grp_bg["Background"]
  node_bg_server["bg server<br/>daemon entrypoint<br/>[bg_server.py]"]
  node_channel["channel<br/>transport contract<br/>[channel.py]"]
  node_discord["Discord<br/>channel adapter<br/>[discord.py]"]
  node_telegram["Telegram<br/>channel adapter<br/>[telegram.py]"]
  node_msg_queue["queue<br/>[message_queue.py]"]
end

subgraph group_grp_core["Core"]
  node_agent["agent<br/>reasoning loop<br/>[agent.py]"]
  node_bg_agent["bg agent<br/>background loop"]
  node_helper_agent["helper agent<br/>sub-agent<br/>[helper_agent.py]"]
  node_client["LLM client<br/>model boundary<br/>[client.py]"]
  node_tool_calls["tool calls<br/>dispatcher<br/>[tool_calls.py]"]
  node_scheduled_tasks["schedules<br/>task engine<br/>[scheduled_tasks.py]"]
  node_tool["tool base<br/>tool interface<br/>[tool.py]"]
end

subgraph group_grp_tools["Tools"]
  node_tools_fs["files<br/>[read_file.py]"]
  node_tools_shell["shell<br/>execution tool<br/>[bash.py]"]
  node_tools_web["web<br/>network tools<br/>[web_fetch.py]"]
  node_tools_util["utils<br/>utility tools<br/>[calculator.py]"]
  node_tools_tasks["task tools"]
end

subgraph group_grp_infra["Infra"]
  node_main["main<br/>entrypoint<br/>[main.py]"]
  node_message_history[("history<br/>persistence<br/>[message_history.py]")]
  node_setup["setup<br/>bootstrap<br/>[setup.py]"]
  node_startup["startup<br/>runtime bootstrap<br/>[startup.py]"]
  node_config["config<br/>[config.py]"]
  node_log["logging<br/>observability<br/>[app_logging.py]"]
end

subgraph group_grp_skills["Skills"]
  node_skills["skills dir<br/>skill discovery<br/>[get_skills_dir.py]"]
  node_puppeteer["puppeteer<br/>skill package<br/>[SKILL.md]"]
end

node_main -->|"boots"| node_startup
node_startup -->|"loads"| node_config
node_startup -->|"wires"| node_setup
node_startup -->|"initializes"| node_log
node_main -->|"runs"| node_cli
node_main -->|"runs"| node_bg_server
node_cli -->|"drives"| node_cli_agent
node_cli_agent -->|"invokes"| node_agent
node_bg_server -->|"starts"| node_bg_agent
node_bg_server -->|"listens"| node_channel
node_channel -->|"implements"| node_discord
node_channel -->|"implements"| node_telegram
node_discord -->|"queues"| node_msg_queue
node_telegram -->|"queues"| node_msg_queue
node_msg_queue -->|"feeds"| node_bg_agent
node_agent -->|"queries"| node_client
node_agent -->|"dispatches"| node_tool_calls
node_tool_calls -->|"uses"| node_tool
node_tool_calls -->|"routes"| node_tools_fs
node_tool_calls -->|"routes"| node_tools_shell
node_tool_calls -->|"routes"| node_tools_web
node_tool_calls -->|"routes"| node_tools_util
node_tool_calls -->|"routes"| node_tools_tasks
node_agent -->|"spawns"| node_helper_agent
node_agent -->|"reads/writes"| node_message_history
node_bg_agent -->|"executes"| node_scheduled_tasks
node_scheduled_tasks -->|"persists"| node_message_history
node_tools_tasks -->|"manages"| node_scheduled_tasks
node_skills -->|"exposes"| node_puppeteer
node_agent -->|"discovers"| node_skills

click node_main "https://github.com/rikul/anotherbot/blob/main/app/main.py"
click node_cli "https://github.com/rikul/anotherbot/blob/main/app/cli/cli.py"
click node_cli_agent "https://github.com/rikul/anotherbot/blob/main/app/cli/cli_agent.py"
click node_bg_server "https://github.com/rikul/anotherbot/blob/main/app/bg_server.py"
click node_channel "https://github.com/rikul/anotherbot/blob/main/app/channels/channel.py"
click node_discord "https://github.com/rikul/anotherbot/blob/main/app/channels/discord.py"
click node_telegram "https://github.com/rikul/anotherbot/blob/main/app/channels/telegram.py"
click node_msg_queue "https://github.com/rikul/anotherbot/blob/main/app/channels/message_queue.py"
click node_agent "https://github.com/rikul/anotherbot/blob/main/app/core/agent.py"
click node_bg_agent "https://github.com/rikul/anotherbot/blob/main/app/core/background_agent.py"
click node_helper_agent "https://github.com/rikul/anotherbot/blob/main/app/core/helper_agent.py"
click node_client "https://github.com/rikul/anotherbot/blob/main/app/core/client.py"
click node_tool_calls "https://github.com/rikul/anotherbot/blob/main/app/core/tool_calls.py"
click node_scheduled_tasks "https://github.com/rikul/anotherbot/blob/main/app/core/scheduled_tasks.py"
click node_message_history "https://github.com/rikul/anotherbot/blob/main/app/infra/message_history.py"
click node_setup "https://github.com/rikul/anotherbot/blob/main/app/infra/setup.py"
click node_startup "https://github.com/rikul/anotherbot/blob/main/app/infra/startup.py"
click node_config "https://github.com/rikul/anotherbot/blob/main/app/config.py"
click node_log "https://github.com/rikul/anotherbot/blob/main/app/infra/app_logging.py"
click node_tool "https://github.com/rikul/anotherbot/blob/main/app/core/tool.py"
click node_tools_fs "https://github.com/rikul/anotherbot/blob/main/app/tools/read_file.py"
click node_tools_shell "https://github.com/rikul/anotherbot/blob/main/app/tools/bash.py"
click node_tools_web "https://github.com/rikul/anotherbot/blob/main/app/tools/web_fetch.py"
click node_tools_util "https://github.com/rikul/anotherbot/blob/main/app/tools/calculator.py"
click node_tools_tasks "https://github.com/rikul/anotherbot/blob/main/app/tools/sched_tasks_tool.py"
click node_skills "https://github.com/rikul/anotherbot/blob/main/app/tools/get_skills_dir.py"
click node_puppeteer "https://github.com/rikul/anotherbot/blob/main/app/skills/puppeteer/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_agent toneBlue
class node_bg_server,node_channel,node_discord,node_telegram,node_msg_queue toneAmber
class node_agent,node_bg_agent,node_helper_agent,node_client,node_tool_calls,node_scheduled_tasks,node_tool toneMint
class node_tools_fs,node_tools_shell,node_tools_web,node_tools_util,node_tools_tasks toneRose
class node_main,node_message_history,node_setup,node_startup,node_config,node_log toneIndigo
class node_skills,node_puppeteer toneTeal
```

## Components

### CLI

Interactive human-in-the-loop execution path.

- [CLI](https://github.com/rikul/anotherbot/blob/main/app/cli/cli.py): interactive shell · Human-facing REPL and single-shot command flow. · `app/cli/cli.py`
- [CLI agent](https://github.com/rikul/anotherbot/blob/main/app/cli/cli_agent.py): cli orchestration · Drives interactive prompting, permissions, and tool iterations. · `app/cli/cli_agent.py`

### Background

Persistent bot runtime and channel adapters.

- [bg server](https://github.com/rikul/anotherbot/blob/main/app/bg_server.py): daemon entrypoint · Starts the persistent background process. · `app/bg_server.py`
- [channel](https://github.com/rikul/anotherbot/blob/main/app/channels/channel.py): transport contract · Shared interface for transport adapters. · `app/channels/channel.py`
- [Discord](https://github.com/rikul/anotherbot/blob/main/app/channels/discord.py): channel adapter · Discord transport into the shared agent loop. · `app/channels/discord.py`
- [Telegram](https://github.com/rikul/anotherbot/blob/main/app/channels/telegram.py): channel adapter · Telegram transport into the shared agent loop. · `app/channels/telegram.py`
- [queue](https://github.com/rikul/anotherbot/blob/main/app/channels/message_queue.py): message queue · Buffers inbound channel messages for processing. · `app/channels/message_queue.py`

### Core

Shared agent loop, model boundary, and scheduling.

- [agent](https://github.com/rikul/anotherbot/blob/main/app/core/agent.py): reasoning loop · Primary LLM-driven agent loop. · `app/core/agent.py`
- [bg agent](https://github.com/rikul/anotherbot/blob/main/app/core/background_agent.py): background loop · Agent variant used by the long-running server. · `app/core/background_agent.py`
- [helper agent](https://github.com/rikul/anotherbot/blob/main/app/core/helper_agent.py): sub-agent · Auxiliary agent used for specialized tasks. · `app/core/helper_agent.py`
- [LLM client](https://github.com/rikul/anotherbot/blob/main/app/core/client.py): model boundary · OpenAI-compatible model client boundary. · `app/core/client.py`
- [tool calls](https://github.com/rikul/anotherbot/blob/main/app/core/tool_calls.py): dispatcher · Resolves model function calls to tool execution. · `app/core/tool_calls.py`
- [schedules](https://github.com/rikul/anotherbot/blob/main/app/core/scheduled_tasks.py): task engine · Durable scheduled-task tracking and execution. · `app/core/scheduled_tasks.py`
- [tool base](https://github.com/rikul/anotherbot/blob/main/app/core/tool.py): tool interface · Common tool abstraction used by the agent. · `app/core/tool.py`

### Tools

Action layer exposed to the model.

- [files](https://github.com/rikul/anotherbot/blob/main/app/tools/read_file.py): filesystem tools · Read and write file capabilities. · `app/tools/read_file.py`
- [shell](https://github.com/rikul/anotherbot/blob/main/app/tools/bash.py): execution tool · Shell command execution capability. · `app/tools/bash.py`
- [web](https://github.com/rikul/anotherbot/blob/main/app/tools/web_fetch.py): network tools · Fetch and search web content. · `app/tools/web_fetch.py`
- [utils](https://github.com/rikul/anotherbot/blob/main/app/tools/calculator.py): utility tools · Datetime, calculator, and location helpers. · `app/tools/calculator.py`
- [task tools](https://github.com/rikul/anotherbot/blob/main/app/tools/sched_tasks_tool.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](https://github.com/rikul/anotherbot/blob/main/app/main.py): entrypoint · Top-level launcher that selects runtime mode. · `app/main.py`
- [history](https://github.com/rikul/anotherbot/blob/main/app/infra/message_history.py): persistence · Persistent conversation and message storage. · `app/infra/message_history.py`
- [setup](https://github.com/rikul/anotherbot/blob/main/app/infra/setup.py): bootstrap · Application initialization and wiring. · `app/infra/setup.py`
- [startup](https://github.com/rikul/anotherbot/blob/main/app/infra/startup.py): runtime bootstrap · Loads config, initializes services, and selects mode. · `app/infra/startup.py`
- [config](https://github.com/rikul/anotherbot/blob/main/app/config.py): runtime config · Configuration loading and defaults. · `app/config.py`
- [logging](https://github.com/rikul/anotherbot/blob/main/app/infra/app_logging.py): observability · Application logging setup. · `app/infra/app_logging.py`

### Skills

Packaged higher-level capabilities.

- [skills dir](https://github.com/rikul/anotherbot/blob/main/app/tools/get_skills_dir.py): skill discovery · Exposes packaged skills to the runtime. · `app/tools/get_skills_dir.py`
- [puppeteer](https://github.com/rikul/anotherbot/blob/main/app/skills/puppeteer/SKILL.md): skill package · Packaged workflow skill. · `app/skills/puppeteer/SKILL.md`

## Connections

- 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.
