miniClaw is a bilingual open-source project about AI agent systems design. It packages the reusable source, workspace templates, and maintenance scaffolding around a larger internal curriculum that spans tool use, context, routing, memory, scheduling, resilience, observability, and concurrency.

Rather than acting as a reduced clone of an existing framework, miniClaw breaks agent engineering ideas into small, readable, runnable teaching examples.

miniClaw is an open-source repository focused on readability, experimentation, and bilingual documentation. The public GitHub version contains the reusable source and workspace assets only. The 12-session course materials are intentionally excluded from the public release.

# Clone the repository
git clone <your-repo-url>
cd miniClaw

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment config
cp .env.example .env
# Edit .env with your API key

# Run repository health checks
python3 scripts/repo_health_check.py

• How an agent loop is driven by stop_reason and bounded state transitions
• How tool registries, message channels, and route binding fit into a gateway
• How session compaction, memory retrieval, and scheduler design interact
• How retries, protection, observability, and concurrency are layered in practice

• Included in this repository: workspace templates, support scripts, environment examples, and open-source project health files
• Excluded from this repository: the 12 lesson files and lecture notes under sessions/
• Goal of the public repo: publish the reusable project skeleton without shipping the full courseware

The full curriculum covers:

• Agent loop
• Tool use
• Sessions and context
• Channels
• Gateway and routing
• Intelligence
• Heartbeat and cron
• Delivery
• Resilience and retry
• Protection
• Observability
• Concurrency

The repository includes the community and maintenance files expected from a public project:

• CONTRIBUTING.md for contribution workflow and review expectations
• SUPPORT.md for usage questions and bug-report guidance
• SECURITY.md for private vulnerability reporting
• .github/ISSUE_TEMPLATE/* and .github/pull_request_template.md for consistent collaboration
• .github/workflows/ci.yml and scripts/repo_health_check.py for lightweight automated checks

miniClaw/
├── workspace/          # Agent workspace configuration (see below)
│   ├── README.md      # Workspace architecture guide
│   ├── SOUL.md        # Agent personality definition
│   ├── IDENTITY.md    # Role boundaries and capabilities
│   ├── TOOLS.md       # Tool registry with parameter types
│   ├── BOOTSTRAP.md   # Loading sequence specification
│   ├── USER.md        # User context template
│   ├── AGENTS.md      # Multi-agent coordination rules
│   ├── HEARTBEAT.md   # Heartbeat check protocol
│   ├── MEMORY.md      # Persistent memory store
│   ├── CRON.json      # Scheduled task definitions
│   └── skills/        # Auto-discovered skill extensions
│       └── example-skill/SKILL.md
│
├── .env.example        # Environment configuration template
├── scripts/            # Repository maintenance scripts
├── requirements.txt    # Python dependencies
├── README.md           # This file
├── README.zh.md        # Chinese version
├── LICENSE             # MIT License
├── CONTRIBUTING.md     # Contribution guidelines
├── CODE_OF_CONDUCT.md  # Community standards
├── SECURITY.md         # Security policy
└── CHANGELOG.md        # Version history

The workspace/ directory is a production-inspired Agent configuration template. It demonstrates how to structure the "system prompt" layer of an AI Agent using composable Markdown files.

Key concept: Instead of one monolithic system prompt, the workspace uses a layered loading chain:

1. SOUL.md → Personality foundation (tone, values, behavioral rules)
2. IDENTITY.md → Role scope (what the agent can/cannot do)
3. TOOLS.md → Available tool registry
4. BOOTSTRAP.md → Structural self-awareness
5. USER.md → User-specific overrides

Supplementary modules (AGENTS.md, HEARTBEAT.md, MEMORY.md, CRON.json) load after the core chain. Skills are auto-discovered from skills/*/SKILL.md.

This architecture enables:

• Separation of concerns — each file owns one aspect of behavior
• Layered override — later layers can override earlier ones
• Template-ready — USER.md uses {{PLACEHOLDER}} syntax for per-session customization
• Extensible — drop a new skill directory to add capabilities

See workspace/README.md for the complete architecture guide.

• Python 3.11+
• Dependencies: anthropic, python-dotenv, websockets, croniter, python-telegram-bot, httpx

• Chinese: root documentation and workspace guides are maintained in Chinese where applicable
• English: root documentation and workspace guides are maintained in English where applicable

• Use issues for bugs, lesson fixes, and feature requests
• Keep English and Chinese public documentation semantically aligned
• Run python3 scripts/repo_health_check.py before opening a pull request
• Read CONTRIBUTING.md, SUPPORT.md, and SECURITY.md before contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

See SECURITY.md for security policy and vulnerability reporting.

This project adheres to the Contributor Covenant Code of Conduct.

See CHANGELOG.md for version history.

MIT — see LICENSE