MacroAgent

English | 简体中文

Turn repeatable agent work into reusable skills, so you spend fewer tokens and get more stable results.

MacroAgent is for people who want to turn recurring agent tasks into reusable workflows, without paying for the same kind of reasoning over and over again.

It works best when you want to lock a proven flow into a skill: a user sends a routing command from an IM app or the CLI, the runtime matches the right skill, assembles a customizable prompt for that skill, runs it with the provider/model chosen by that skill, and then calls the local or external toolchain needed to finish the job.

A more compelling example is a content pipeline where a Telegram message triggers a skill, the skill turns raw text into image-ready sentences, sends those sentences plus a prepared ComfyUI flow template to a local Windows ComfyUI instance, uses the local GPU for image generation, and returns the final image back to the user. The point is not one giant prompt and one global model. The point is that each skill can own its own prompt, model, output contract, and toolchain.

Instead of asking a general-purpose agent to rethink every step on every run, MacroAgent reuses flows that already work. The result is practical: lower token waste, less output drift, clearer failure boundaries, and a better way to orchestrate local GPU resources, existing scripts, and model-specific workflows.

This README is meant to be enough for a first CLI deployment. For Telegram, Feishu, and deeper configuration details, continue to the linked docs at the end.

Prerequisites

• Python 3.10 or 3.11 is the recommended target for first deployment.
• The project metadata currently declares >=3.10 in pyproject.toml.
• A checked-out copy of this repository.
• Optional: Ollama, if you want /compact to work with the default maintenance model.

Recommended Install Path

Use this as the primary path for a first local deployment.

1. Create a virtual environment:

python -m venv .venv

2. Activate it:

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS / Linux:

source .venv/bin/activate

3. Install the core dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Install optional channel adapters only if you need them:

pip install "python-telegram-bot>=21.0"
pip install "lark-oapi>=1.4.8"

Run MacroAgent directly from the checked-out repository:

• python src/macro_agent/main.py --channel cli

Do not rely on pip install -e . or an installed console entry point for this repository. The runtime expects local repo config such as config/base_config.json, .env, and generated skills to stay in the checkout.

Minimal CLI Setup

Copy the environment template first:

Windows:

copy .env.example .env

macOS / Linux:

cp .env.example .env

There are three different provider layers you need to distinguish:

• Runtime default in config/base_config.json: anthropic / claude-4-5-sonnet-latest
• Built-in /read and experimental /skill_writer: currently pinned in their skill configs to google / gemini-3-flash-preview
• /compact: uses maintenance.compact, currently ollama / qwen2.5:7b

That means:

• Starting the CLI itself requires no API key.
• Running a built-in LLM-backed command does require the provider that skill is configured to use.
• For the first successful /read https://example.com run, the minimum useful env var is GOOGLE_API_KEY.
• Long-term user profile data is maintained through /compact + /memory, not through shared prompt files.

If GOOGLE_API_KEY is missing, the CLI still starts, but /read https://example.com will fail when invoked and print a warning similar to:

LLM summary generation failed: API key required for Gemini Developer API. Provide api_key parameter or set GOOGLE_API_KEY/GEMINI_API_KEY environment variable.

If you want to change providers instead of using Google for the built-in skills, edit the relevant skill config.yml files under src/macro_agent/skills.

First Successful Run

The shortest first-run path for the current codebase is:

1. Copy .env.example to .env.
2. Set GOOGLE_API_KEY in .env.
3. Start the CLI from the activated virtual environment:

python src/macro_agent/main.py --channel cli

If you followed the install steps above, that usually means the virtual environment directory is .venv, while .env is only the environment variable file.

4. Wait for this startup shape:

MacroAgent CLI — type a command or 'exit' to quit
   Auto-confirm: OFF
...
> 

If you see the > prompt, MacroAgent is waiting for input. It is not hung.

5. Enter:

/read https://example.com

6. A successful run should look like this shape:

Processing: /read https://example.com

**...**
• ...
• ...
> ...

That output means:

• the CLI adapter is running
• the event worker and executor are processing commands
• the /read skill completed successfully
• the crawler and summarizer path is working end to end

Built-In Skills And Their Dependencies

Skill	Required for basic success	Optional additions	Important note
/read <url>	Crawl4AI from core dependencies and a working LLM provider	Search enrichment via SEARCH_ENABLED=true plus BRAVE_API_KEY or TAVILY_API_KEY	The built-in skill config currently uses google / gemini-3-flash-preview
/skill_writer <brief>	A working LLM provider	None	Experimental. Generates an initial skill scaffold in src/macro_agent/skills and should still be reviewed manually.
/compact	A working maintenance model	None	Writes candidate user facts and a session summary; by default this is ollama / qwen2.5:7b, not the runtime default model
/memory ...	None beyond SQLite availability	Namespace filtering and batch review	Maintains confirmed/candidate user facts, health checks, and review flow

/compact Prerequisite

/compact uses maintenance.compact in config/base_config.json, which currently points to:

• provider: ollama
• model: qwen2.5:7b

Before using /compact, make sure one of these is true:

• Ollama is running and the model qwen2.5:7b is available.
• You changed maintenance.compact to a provider/model that exists in your environment.

If you want to keep the current default, the usual local preparation is:

ollama pull qwen2.5:7b

Optional Channels: Telegram / Feishu

You can configure CLI, Telegram, and Feishu in the same repository at the same time.

Channel selection works like this:

• --channel <name> wins when you pass it explicitly
• if you pass neither, MacroAgent uses defaults.channel from config/base_config.json

channels.<name>.enabled exists in config and should be set to true when that channel is part of your deployment intent. In the current implementation, startup is selected by --channel or defaults.channel, and missing credentials are what actually block Telegram or Feishu startup.

Telegram

Minimum path:

1. Create a bot with BotFather and get the token.
2. Install the adapter dependency:

pip install ".[telegram]"

3. Set these values:

• TELEGRAM_TOKEN
• optional: ALLOWED_TG_USER_IDS
• recommended for config clarity: set channels.telegram.enabled to true

4. Start it from the activated virtual environment:

python src/macro_agent/main.py --channel telegram

5. Verify it:

• Send /start to the bot.
• A healthy bot replies with MacroAgent ready and the command list.
• Then send /read https://example.com and expect a task completion reply.

If TELEGRAM_TOKEN is missing, startup logs an error and Telegram mode does not start.

Feishu

Minimum path:

1. Create a Feishu app with message receive capability.
2. Install the adapter dependency:

pip install ".[feishu]"

3. Set these values:

• FEISHU_APP_ID
• FEISHU_APP_SECRET
• optional for webhook validation: FEISHU_VERIFICATION_TOKEN
• optional for encrypted events: FEISHU_ENCRYPT_KEY
• optional allowlists: FEISHU_ALLOWED_USER_IDS, FEISHU_ALLOWED_CHAT_IDS
• recommended for config clarity: set channels.feishu.enabled to true

4. For the simplest first integration, keep Feishu mode as websocket in config/base_config.json.

5. Start it from the activated virtual environment:

python src/macro_agent/main.py --channel feishu

6. Verify it:

• Send a text command such as /read https://example.com from an allowed chat or user.
• A healthy setup sends back the skill result as a Feishu message.

If FEISHU_APP_ID or FEISHU_APP_SECRET is missing, startup logs an error and Feishu mode does not start.

Feishu Websocket vs Webhook

• websocket is the recommended minimal path for first integration.
• webhook is better when you already have a public ingress and want Feishu to call back into your deployment.

Config: .env vs base_config.json

Use the two config layers for different jobs.

• .env: secrets and fast-changing addresses, such as API keys, tokens, hostnames, and local service endpoints
• config/base_config.json: stable defaults, provider definitions, channel definitions, maintenance model selection, and trim settings
• user_facts SQLite store: reviewed long-term user profile memory

For first-time setup, the usual workflow is:

1. Edit .env first.
2. Only edit config/base_config.json when you want to change stable defaults such as:

• the default channel
• the maintenance model for /compact
• channel mode such as Feishu websocket vs webhook

Precedence is:

1. environment variable
2. fallback value in config/base_config.json

One more boundary matters: skill-local config.yml files can still pin a provider/model for that skill, so changing runtime defaults does not automatically retarget every built-in skill.

Testing

After activating the same virtual environment, run:

python -m pytest

This is the correct generic test command for the repository. It does not assume any specific virtual environment directory name.

Memory Review Loop

MacroAgent's current memory model is:

• /compact proposes candidate facts
• /memory reviews and maintains facts
• skills read confirmed facts only

Useful commands:

/memory list
/memory list profile.
/memory candidates
/memory doctor
/memory approve 3
/memory approve-all profile.
/memory reject 4
/memory reject-all interest.
/memory update 2 profile.style dense Prefer dense output

The runtime validates namespaces and values through an internal registry. Current built-in namespace families include:

• profile.*
• interest.*
• learning.*
• workflow.*
• tool.*

Links To Deeper Docs

• Startup Guide
• Base Config Guide
• Skill Writer Guide
• Skill Writer Walkthrough
• Contributing
• Security