Background

In the previous post WeChat Fragmented Diet Records — Handed Over to Agent, I mentioned that CC's loop cycles don't last long and need rebuilding every so often; OpenClaw and WorkBuddy are too heavy, and my old Mac struggles to run them. So I said at the time that I'd consider building a custom Agent based on pi later.

I've recently made that happen — built a lightweight personal Agent framework and named it botler-agent (bot + butler, acting as a data steward).

Source code: https://github.com/crossoverJie/botler-agent

Here's what it looks like in use:

Backend page:

This post serves as an introduction, and I'll also talk through the design trade-offs I made.

What exactly is it

botler-agent is a lightweight personal Agent framework: it receives messages from Telegram / Feishu / WeChat (iLink), autonomously completes short tasks within sub-projects under the data directory DATA_ROOT, and sends the results back. It also has optional modules for scheduled tasks, a local WebUI, and health monitoring.

The framework does nothing business-related. It only does three things:

• Manages an allowlist of operable directories
• Gives the Agent five tools: read / write / edit / run / schedule
• Validates that written JSON is legal, and auto git-commits any changes (mainly for data backup)

All specific business rules are delegated to the AGENTS.md file at the root of each data sub-project. The Agent reads it before taking action; only then does it know what the project's data looks like and how to write it.

Adding a new data project means creating a directory and writing an AGENTS.md — no framework source code changes needed. Conversely, changing business rules only requires editing that directory's AGENTS.md, without touching the framework. Framework and business are completely decoupled.

The framework defines "what can be touched and what tools are available"; the business defines "how exactly to record things". The two don't interfere with each other.

For example, I currently have six projects running, used to record:

• Vehicle maintenance items
• Diet records
• Daily logs
• Financial bookkeeping data
• My English learning data
• Travel data — photos, impressions, etc.

You can see these are all very specific vertical business data. After a week of heavy use, these are the data points I've found I need to care about.

I've also open-sourced these apps; you can download and use them directly, or contribute apps you find useful.

Five tools, no bash

Many Agent frameworks come with a big toolbox right out of the gate — filesystem, shell, browser, everything. botler goes the opposite way and strips down to just five:

Tool	What it does	Restrictions
read	Read files	Only allowlisted directories
write	Write files	Ensures serialized legal JSON
edit	Edit files	Only allowlisted directories
run	Run scripts	Only existing python3/node scripts within the project
schedule	Create scheduled tasks	Only writes to the fixed schedules.json

run and schedule are the two most easily misunderstood. Neither is arbitrary shell. run can only execute .py / .js scripts already present in the project; the interpreter is fixed by extension, arguments are passed directly without going through a shell, and there's a 60-second timeout. schedule has no file path parameter and can only write to that one fixed schedules.json.

The reason for this design is simple: this thing is meant to run long-term on my machine with external entry points, so permissions should be as minimal as possible. If the Agent goes off the rails and spouts nonsense, the worst it can do is mess up the JSON in the data directory — it can't touch the rest of your private data.

How a single task runs

WeChat / Feishu / Telegram
      │ message
      ▼
 Dispatcher (dedup + serial queue)
      ▼
 Runner (two-phase: routing → execution)
      ├─ Routing: determine which sub-project, ask user if unsure
      ├─ Execution: only concatenates the selected sub-project's AGENTS.md
      └─ Tools read / write / edit / run / schedule
      ▼
 Validate JSON legality (self-healing retry on failure)
      ▼
 git commit (only if there are changes)
      ▼
 Reply to user (WeChat also sends images)

The thing I care about most is saving tokens. General-purpose assistant-style Agents often carry a huge system prompt and burn a lot per run. botler goes the opposite way:

• Each message spawns a brand-new short-lived Agent with no cross-task memory
• The routing phase uses only a small prompt with "project name + summary" to decide which sub-project this message belongs to
• The execution phase only then concatenates the selected sub-project's AGENTS.md into the system prompt

So even if DATA_ROOT has ten projects, running one message won't stuff all ten projects' conventions in — only the selected one gets loaded. For most tasks, the cost per run is a fraction of a general-purpose assistant's.

When routing can't decide, it replies with "Which project are you referring to?" and asks you to clarify, rather than guessing and writing into the wrong one.

Comparison with peers

	botler-agent	General Agent (OpenClaw / WorkBuddy)	Coding Agent (Claude Code / Codex)
Positioning	Lightweight personal data assistant	General task automation	Software engineering in a codebase
Install footprint	Single tsx process, seconds to install	Large install package	Depends on full dev environment
Built-in tools	5 controlled tools	Big and comprehensive	Full shell + filesystem
File operations	Allowlisted first-level subdirectories	Relatively open	Entire workspace
Machine permissions	Very restrained	Relatively open	Highly open
Best at	Daily records, reminders	General automation	Coding, refactoring, debugging

OpenClaw and WorkBuddy are positioned as "can do anything" — complex functionality, large install packages, unfriendly to older machines. CC and Codex are workhorses, but desktop-oriented and operate across your entire computer. botler sits in the middle: lightweight recording aimed at mobile, with very low permission requirements.

There's also the category of cloud chatbots (Doubao, Yuanbao, etc.) — data lives in their cloud as loose, unstructured chat logs, inconvenient for long-term maintenance and reuse. botler keeps all data local; you can organize it into structured data whenever you want.

You can also build any visualization pages you like.

Of course, if you don't need visualization pages, fetching data through chat each time works too. But either way, the raw data is stored in a structured format, making maintenance easy.

Security boundaries

I've dedicated a section to security in the README. A few key points:

• Separation of app and data: framework code and DATA_ROOT are in two different locations. The data directory only contains the operated projects, no source code or secrets.
• Path allowlist: safePath() only permits first-level subdirectories under DATA_ROOT, with prefix matching and realpath to prevent directory traversal like /agent2 and symlink escapes.
• Externalized config: system prompt, .env, and providers.json all live in ~/.botler-agent/, reusable across machines and clones.

What it can do right now

The data projects I've set up for myself are that template set: cook (diet records), daily-log (daily logs), ledger (bookkeeping), travel (travel). The fat-loss pipeline from the previous post could theoretically be ported entirely onto botler: send "ate a steamed bun" via WeChat, it looks up the table, calculates calories, writes into intake.json, commits, and sends me back a notification.

After data updates, the web page gets hosted directly on GitHub, and a Telegram notification is sent upon successful deployment so you can click the link to view it.

Scheduled tasks work too: tell it "remind me to drink water every morning at 8," and it uses the schedule tool to write into schedules.json, pushes back to me at the appointed time, and automatically delays late-night reminders to avoid disturbance.

Summary

It's not fully polished yet — some things need further refinement — but it's already sufficient for my daily recording and reminder needs. If you also want a lightweight Agent that runs on your own machine, connects to WeChat/Feishu, and keeps data local, come check out botler-agent.

After heavy use for a while, it genuinely solves my daily fragmented recording. Many app features — photo calorie recognition, photo bookkeeping, AI (natural language) bookkeeping — can all be achieved, and the data is highly controllable. No more worrying that those apps might suddenly stop being maintained one day; data security is also assured.

For more on deployment — how to configure Feishu and Telegram tokens, how to configure the LLM, etc. — check the README for detailed instructions. Any questions or suggestions, feel free to message me directly.