mybot

A local, tool-using personal assistant for Windows. It talks to any OpenAI-compatible LLM (DeepSeek, OpenAI, OpenRouter, Groq, Ollama, ...) and can read/write files, run shell commands, control the desktop, manage scheduled tasks, and solve GitHub issues.

Why mybot

opencode is a coding agent in a terminal. mybot is a general assistant with full-machine control, and it goes further:

• Remembers you — remember/recall and sessions that persist across restarts.
• Real undo — /undo reverts the files a turn wrote, with reviewable diffs.
• Local-first — auto-falls back to local Ollama if your provider is down, routes simple turns to a cheap model, and blocks past a spend cap (MAX_SESSION_COST).
• Automates in the background — triggers that fire on a schedule or when a file changes.
• Sees and hears — attach images for vision models; /voice transcribes locally.
• Drives your desktop — screenshot → think → click/type, like a computer-use agent.
• opencode-style TUI — home screen, sidebar with context/cost, thinking blocks, slash menu, command palette, themes.

Requirements

• Python 3.10+ (tested on 3.13)
• An API key for an OpenAI-compatible provider (or a local Ollama)

Setup

git clone https://github.com/AyinkxLab/mybot.git
cd mybot
python -m pip install -r requirements.txt

Then start it and connect a provider:

python main.py
you> /connect

/connect asks for the provider (default deepseek), your API key, and then lists the models the provider actually offers for your key so you can pick one. Credentials are saved to .mybot_config.json (gitignored). You can also set LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL in a .env file instead — see .env.example.

Running it

• Full-screen TUI (default): type mybot from any directory. The repo folder is added to your PATH; mybot.cmd (cmd/PowerShell), the extensionless mybot (Git Bash), and a PowerShell profile function all launch it. You can also run python tui.py.
• Plain CLI: python main.py (or mybot-cli).
• Desktop app: mybot-gui.cmd (or the desktop shortcut) opens a tkinter chat window.

TUI

Opens on an opencode-style home screen: a centered logo, a centered prompt box, the active agent mode + model line, key hints, and a version tag. The first message switches to the chat view:

• scrollable chat with per-role colored borders and streaming markdown
• inline tool-call rows and a per-message meta line (▪ Build · model · 2.3s)
• a right sidebar showing the session title, Context (tokens, % used, $ spent), Tools, and a live todo list the model keeps updated
• a bottom status line (mode · model · provider, workspace, context, cost, ctrl+p commands)
• an approval modal for gated actions

Keys: tab agent mode · ctrl+p command palette · ctrl+x leader (n new, l sessions, u undo, r redo, t theme, m models, c compact, x export, q quit) · ctrl+t theme · ctrl+o toggle sidebar · ctrl+n new session · esc cancel run · ctrl+c quit

Commands: /connect, /models, /theme (/themes), /mode, /thinking, /details, /compact (/summarize), /export, /sessions (/resume, /continue), /undo, /redo, /new (/clear), /reset, /exit (/help in the TUI).

Sessions persist to disk and survive restarts; /sessions switches between them. /undo removes the last turn and reverts files it wrote; /redo restores both. Overwriting an existing file shows a diff and asks for approval when REQUIRE_APPROVAL=true.

Prefixes: !command runs a shell command; @path attaches a file's contents to your message.

For models that stream reasoning (e.g. deepseek-reasoner), a Thinking block is shown and can be toggled with /thinking. /details expands tool args/results. A spinner shows while waiting for the first token.

Agent modes: build (default, full access) and plan (read-only; the model plans but does not modify files or run mutating commands).

Themes (default opencode): opencode, mybot, catppuccin, one-dark, matrix, dracula, tokyo-night, gruvbox, nord, plus Textual's built-ins. Switch with /theme.

The TUI is built with Textual (textual + rich in requirements.txt). The model uses a todo_write tool to plan multi-step work; those items appear in the sidebar as they change.

This is an opencode-style interface, not a pixel-perfect clone of opencode's Go/Bubble Tea UI.

Configuration (.env)

See .env.example for the full list. Highlights:

Variable	Purpose
BOT_WORKSPACE	Root the file/shell tools may use. Default workspace/.
REQUIRE_APPROVAL	When true, pushes / PRs / GitHub writes / scheduled tasks pause for approval.
ALLOW_SHELL	Set false to disable shell execution entirely.
GITHUB_TOKEN	Fine-grained PAT (Contents + Issues + Pull requests) for issue solving.
ALLOW_PRIVATE_HTTP	Allow http_get to reach localhost/private IPs (SSRF risk).
LLM_FALLBACK_*	Local-first fallback (defaults to Ollama) used if the primary provider fails.
LLM_MODEL_FAST	Optional cheap model for short/simple turns.
MAX_SESSION_COST	Session spending cap in USD (0 = off); turns are blocked past it.
TELEGRAM_ALLOWED_IDS / DISCORD_ALLOWED_IDS	User IDs allowed to use the chat adapters.

Full-machine access

To give the bot more reach, set BOT_WORKSPACE=C:\ and REQUIRE_APPROVAL=false. This is a powerful and risky configuration and is entirely at your own discretion.

Tools

read_file, write_file, list_dir, run_shell, http_get, github_request, launch_app, gui_click, gui_type, gui_hotkey, gui_screenshot, take_screenshot, schedule_task, list_tasks, delete_task, todo_write, remember, recall, add_trigger, list_triggers, remove_trigger.

Computer use

The bot can operate your desktop. take_screenshot captures the screen and attaches it so the vision model can see it; it then uses gui_click / gui_type / gui_hotkey to act. Coordinates are read off the screenshot and mapped back to the real screen. Example: "open Settings and turn off notifications". Needs pyautogui; use with care.

Plugins

Drop a .py file in plugins/. It may define register(api) to add:

def register(api):
    api.register_tool("now", lambda: "2026-01-01",
                      "Current date", {"type": "object", "properties": {}, "required": []})
    api.register_command("hello", lambda text: "hi from my plugin", "greet")
    api.on("startup", lambda: api.log("loaded"))
    api.on("user_message", lambda text: None)      # also: assistant_message, turn_end

• Tools become available to the model automatically.
• Commands show up in the / menu and run with /name args.
• Hooks fire on events: startup, user_message, assistant_message, turn_end.
• /plugins lists installed and available plugins. See plugins/example.py.

Installing plugins

A small registry ships with a few ready plugins (web-search, clipboard, weather, generators). Install by name, from a local file, or from a raw .py URL.

In the TUI:

/plugins                      # installed + available
/install web-search           # by name
/install https://raw.githubusercontent.com/<user>/<repo>/main/myplugin.py
/enable <name>  /disable <name>

From a terminal (the mybot-plugin launcher is on your PATH):

mybot-plugin available
mybot-plugin search weather
mybot-plugin install web-search
mybot-plugin install .\myplugin.py
mybot-plugin list

The installer refuses files without a top-level register(api), downloads/copies them into plugins/, and activates them immediately. Add your own registry entries to plugin_registry.json, or point MYBOT_PLUGIN_REGISTRY_URL at a remote JSON registry.

Plugins run with full app privileges — only install ones you trust.

Triggers (background automation)

While mybot is running, a small daemon checks background triggers every 2s and runs their command when they fire:

when ./src changes  -> run tests       (watch)
every 300 seconds   -> check the queue  (interval)

The model can create them with add_trigger; list them with /triggers. For automation when mybot is not running, use schedule_task (Windows Task Scheduler) or a .cmd that runs mybot.

Images & voice

Reference an image (e.g. @diagram.png, or drag a file into the terminal) and it's attached to your message as an image_url part for vision models (DeepSeek V4.1 Flash, GPT-4o, etc.).

/voice records 5 seconds and transcribes locally with Whisper, then fills the prompt. Enable it (optional) with:

pip install faster-whisper sounddevice numpy

Chat adapters

python adapters\telegram_bot.py   # set TELEGRAM_TOKEN and TELEGRAM_ALLOWED_IDS
python adapters\discord_bot.py    # set DISCORD_TOKEN and DISCORD_ALLOWED_IDS

Discord requires the privileged Message Content Intent in the developer portal. Always set the allowlists — otherwise anyone who finds the bot can run commands on your machine.

Safety notes

• The LLM still applies its own safety behavior; this project does not (and cannot) remove that.
• run_shell executes real commands. Keep REQUIRE_APPROVAL=true and a sandboxed BOT_WORKSPACE unless you fully accept the risk.
• The destructive-command gate is a best-effort blocklist, not a hard sandbox.
• Use a narrowly scoped GitHub token. Never a classic repo-scope token.

License

MIT — see LICENSE.