minibot

A locally-hosted bot for your terminal, powered by Ollama tool calling. Type natural language — the model picks tools, your bot eats, plays, recharges, and can read/write code files in a restricted sandbox.

Zero third-party dependencies: pure Python stdlib. Runs on Termux, Linux, macOS and Windows.

   .---. Pixel the bot · mood: happy · age 3d
  / o o \ Hunger    [██░░░░░░░░]  20/100
  \  w  / Happiness [███████░░░]  72/100
   '---' Energy     [██████░░░░]  65/100
          Health    [██████████] 100/100
❯ write a file hello.py that prints hello
» tools: write_file
Pixel: wrote hello.py (21 bytes), want me to run the idea past you?

Requirements

• Python 3.10+

• Ollama running locally (or on another machine on your LAN)

Related MCP server: veriloop

Install Ollama

Pull a tool-calling-capable model (7B recommended on desktops):

ollama pull qwen2.5:7b        # or llama3.1:8b
# phones / weak CPUs:
ollama pull qwen2.5:3b
ollama pull qwen2.5:1.5b

Verify: curl http://127.0.0.1:11434/api/tags should list your models.

Install minibot

git clone https://github.com/karun99/minibot.git && cd minibot
pip install .          # installs the `minibot` command
# — or run without installing:  python -m minibot

No pip install step needed beyond that — there are no runtime dependencies.

Quick start

minibot doctor        # check python/config/sandbox/ollama/model
minibot run           # interactive terminal bot

Then chat, or use direct commands (they work even with Ollama stopped):

/feed  /play  /rest  /treat  /status  /stats
/ls  /read notes.md  /write notes.md  /history  /undo notes.md
/needle on   /doctor   /clear   /help   /quit

Caring for the bot earns treats (feed and rest earn 1, play earns 2, capped at 20); /treat spends one for a small happiness/health/energy boost. /stats charts the recent stat history, /history lists recent sandbox writes and /undo [file] reverts one.

Type minibot run --offline to start anyway when Ollama is down (direct /commands only).

One-shot commands (scriptable)

minibot status            # human readable
minibot status --json     # machine readable
minibot feed              # feed once
minibot treat             # spend a treat
minibot stats --points 20 # recent stat chart (also --json)
minibot ls src/
minibot read src/app.py
echo "print('hi')" | minibot write hello.py
minibot history           # recent sandbox writes
minibot undo src/app.py   # restore the previous version
minibot chat "read hello.py and tell me what it does"

Use it from any MCP client

minibot mcp serves the bot's tools over stdio using the Model Context Protocol, so Claude Desktop, Cursor, OpenCode or any other MCP client can feed your bot, read and write sandbox files, and undo writes:

{
  "mcpServers": {
    "minibot": {
      "command": "minibot",
      "args": ["mcp"]
    }
  }
}

Exposed tools: feed_bot, play_with_bot, rest_bot, give_treat, get_bot_status, read_file, write_file, list_dir, file_history, undo_write. The same sandbox rules apply — a client outside your machine still cannot escape the sandbox directory.

Configuration

Search order: --config PATH → ./config.json → $XDG_CONFIG_HOME/minibot/config.json → ~/.config/minibot/config.json → defaults. Precedence: CLI flags > environment > config file > defaults.

Copy config.example.json to config.json and edit. Every key is optional:

MINIBOT_HOME (default ~/.minibot) overrides where state/sandbox/logs live.

The Needle pre-filter (optional)

When enabled, input is classified first into bot_action / file_action / chat / unknown:

• heuristic mode — regex/keyword classifier, no model, instant, offline.

• ollama mode — a tiny classifier model (needle.model); any failure silently falls back to the heuristic, and any total failure falls back to the main loop (graceful degradation).

• Only high-confidence, unambiguous bot-care phrases ("feed my bot", "status") execute directly without the LLM; everything else — including vague or mixed requests — goes through the normal tool-calling loop.

Sandbox safety

• All paths are resolved (symlinks followed) and must stay inside the sandbox.

• .. traversal, absolute paths outside the root, escaping symlinks and null bytes are rejected with a safe error.

• Read/write capped at max_file_bytes (default 1 MB).

• Every write is logged with timestamp, path and size.

Tests

pip install pytest
pytest

180+ tests: sandbox traversal attacks, state decay/persistence, treat inventory, stat-history samples, the write journal (history/undo), tool schemas, the ReAct loop (malformed-JSON retry, max iterations, history trimming), Needle routing, the Ollama client against a local fake server, the MCP server over stdio, and CLI acceptance tests.

Troubleshooting

Layout

minibot/
  config.py          config file + env + CLI precedence
  state.py           bot stats, time decay, atomic JSON persistence
  sandbox.py         path containment, size limits, write audit
  tools.py           tool schemas + handlers (add a tool in ~10 lines)
  ollama_client.py   stdlib HTTP client for /api/chat and /api/tags
  needle.py          optional intent pre-filter (heuristic | ollama)
  orchestrator.py    ReAct loop, malformed-retry, history trimming
  mcp_server.py      stdio MCP server: expose the tools to other agents
  tui.py             terminal UI: sprite, bars, slash commands
  cli.py             run/status/feed/treat/stats/history/undo/chat/mcp/doctor
  checks.py          health checks shared by doctor and /doctor
docs/SRS.md          the requirements this implements
tests/               pytest suite (run on a fast disk, not an SD card)

License

MIT — see LICENSE.