metaclaw-examples

Runnable end-to-end examples and starter templates for MetaClaw.

Repository Boundary

This repo contains only example projects.

• includes: demo agent.claw, sample bot code, example build/run scripts
• excludes: engine internals, reusable skill library governance, registry backend services

Ecosystem Repo Map

Repo	Primary Responsibility	URL
metaclaw	Engine core: compiler, runtime adapters, lifecycle/state	https://github.com/fpp-125/metaclaw
metaclaw-examples	Runnable end-to-end examples and starter templates	https://github.com/fpp-125/metaclaw-examples
metaclaw-skills	Reusable capabilities (SKILL.md + capability.contract)	https://github.com/fpp-125/metaclaw-skills
metaclaw-registry	Publish/distribution backend for skill/capsule metadata	https://github.com/fpp-125/metaclaw-registry

Included

• examples/obsidian-bot/
  • minimal Obsidian + LLM starter generated by metaclaw wizard
• examples/obsidian-terminal-bot-advanced/
  • advanced terminal bot with image-layer business code, host-side TUI, scoped retrieval, controlled save flow, and optional Tavily web search
• examples/capsule-release/
  • minimal release/verify sample

Quick Start

Advanced Obsidian terminal bot

cd examples/obsidian-terminal-bot-advanced
# 1) edit mount source paths in agent.claw
# 2) build image and pin digest
./build_image.sh
# 3) run chat
export OPENAI_FORMAT_API_KEY=...
export TAVILY_API_KEY=...   # optional
./chat.sh

Tip: once in chat, run /llm setup to choose providers/models and (optionally) store keys into .env (gitignored).

Engine + Advanced Bot

# 0) Clone both repos
git clone https://github.com/fpp-125/metaclaw.git
git clone https://github.com/fpp-125/metaclaw-examples.git

# 1) Build the engine binary
cd metaclaw
go build -o ./metaclaw ./cmd/metaclaw

# 2) Enter the advanced Obsidian bot example
cd ../metaclaw-examples/examples/obsidian-terminal-bot-advanced

# 3) Prepare host data directories
BOT_DATA="$HOME/.metaclaw/obsidian-terminal-bot"
mkdir -p "$BOT_DATA"/{config,logs,runtime,workspace}

Then do two things:

• Edit agent.claw.
• Replace /ABS/PATH/TO/OBSIDIAN_VAULT with your friend's vault path.
• Replace /ABS/PATH/TO/BOT_HOST_DATA with the absolute path of BOT_DATA.
• Build and run:

# 4) Build image (choose one runtime)
RUNTIME_BIN=container ./build_image.sh
# RUNTIME_BIN=docker ./build_image.sh
# RUNTIME_BIN=podman ./build_image.sh

# 5) Set API keys and run
export OPENAI_FORMAT_API_KEY='...'
export TAVILY_API_KEY='...'   # optional

METACLAW_BIN="/ABS/PATH/TO/metaclaw/metaclaw" \
RUNTIME_TARGET=apple_container \
./chat.sh
# or set RUNTIME_TARGET=docker / podman

If metaclaw is already in your PATH, you can omit METACLAW_BIN=....

Minimal Obsidian starter

# Replace /ABS/PATH/TO/obsidian-bot/* in agent.claw first
export OPENAI_FORMAT_API_KEY=...
metaclaw run examples/obsidian-bot/agent.claw --llm-api-key-env=OPENAI_FORMAT_API_KEY

Validate Examples

./scripts/validate_examples.sh

Related Repos

• engine: https://github.com/fpp-125/metaclaw
• skills: https://github.com/fpp-125/metaclaw-skills
• registry backend: https://github.com/fpp-125/metaclaw-registry