Skip to content
BranchesTags

Repository files navigation

Wee-Orchestrator Starter Kit

A skeleton repository for building a new bot that works with Wee-Orchestrator.

What Is This?

This starter kit gives you a clean foundation for creating your own AI agent home — a configuration hub where your Claude, Gemini, and Copilot CLI agents all share the same behavior settings, skills, and project structure.

It is modeled after the Fosterbot pattern: one repository that acts as the "brain" configuration for a multi-agent orchestration system.

Quick Start

1. Fork or Clone This Repository

# Option A: Fork on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/wee-orchestrator-starter-kit.git /opt/my-bot-home
cd /opt/my-bot-home

# Option B: Clone directly and point to your own remote
git clone https://github.com/leprachuan/wee-orchestrator-starter-kit.git /opt/my-bot-home
cd /opt/my-bot-home
git remote set-url origin https://github.com/YOUR-USERNAME/YOUR-REPO.git

2. Run Setup Script

chmod +x setup.sh && ./setup.sh

This will:

  • Create symlinks (CLAUDE.md → AGENTS.md, GEMINI.md → AGENTS.md)
  • Initialize .claude/skills/ directory
  • Create .gitignore entries for sensitive files
  • Prompt you to configure your user profile in AGENTS.md

3. Configure Your Profile

Edit AGENTS.md and fill in:

  • Your location and timezone
  • Your repository purpose
  • Your projects (see Projects section below)

4. Fork & Connect Wee-Orchestrator

# Clone Wee-Orchestrator (production)
git clone https://github.com/leprachuan/Wee-Orchestrator.git /opt/n8n-copilot-shim

# Clone Wee-Orchestrator (dev environment)
git clone https://github.com/leprachuan/Wee-Orchestrator.git /opt/n8n-copilot-shim-dev
cd /opt/n8n-copilot-shim-dev && git checkout -b dev

# Configure your bot credentials (NOT committed to git)
cp /opt/n8n-copilot-shim/webex_config.json.example /opt/n8n-copilot-shim/webex_config.json
# Edit with your bot tokens

5. Start Your Bot Services

# Copy systemd service files
sudo cp wee-orchestrator.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable wee-orchestrator
sudo systemctl start wee-orchestrator

Repository Structure

my-bot-home/
├── AGENTS.md              # ← Single source of truth for ALL agents
├── CLAUDE.md              # → symlink to AGENTS.md
├── GEMINI.md              # → symlink to AGENTS.md
├── README.md              # This file
├── SKILL_DEVELOPMENT.md   # Guide for creating new skills
├── setup.sh               # Bootstrap script
│
├── skills/                # Public, production-ready skills (separate git repo)
├── my-skills/             # Private/experimental skills (separate git repo)
│
├── .claude/
│   └── skills/            # Symlinks for Claude Code skill discovery
│
├── projects/              # Your sub-agent/sub-project folders
│   └── README.md
│
├── memory/                # Agent knowledge base (PARA methodology)
│   ├── INDEX.md
│   ├── projects/
│   ├── areas/
│   ├── resources/
│   └── archive/
│
└── bin/                   # Helper scripts
    └── install-skill.sh   # Skill install helper with security scan

The AGENTS.md File

AGENTS.md is the single source of truth for all your agents. It defines:

  • Your user profile (location, timezone)
  • Projects and sub-agents
  • Skill management rules (including security protocol)
  • Code style preferences
  • Agent behavior rules

Important: CLAUDE.md and GEMINI.md are symlinks to AGENTS.md. This means you only ever edit one file and all agents pick up the changes automatically.

# Create symlinks (done by setup.sh)
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

If you're on a MacBook or different host, re-run the symlink commands after cloning.

Projects (Sub-Agents)

Projects live in the projects/ folder. Each project is:

  • Its own git repository (independently managed)
  • Listed in .gitignore so it doesn't get committed to this parent repo
  • Referenced in AGENTS.md so agents know about it

Adding a New Project

# Create and init a new project
mkdir projects/my-email-bot
cd projects/my-email-bot
git init
git remote add origin https://github.com/YOUR-USERNAME/my-email-bot.git

# Add to parent .gitignore
echo "projects/my-email-bot/" >> /opt/my-bot-home/.gitignore

Then add the project to AGENTS.md in the Project Directories table.

Example Projects

Project Purpose
email-bot Email triage and processing
smart-home Home automation control
knowledge-base Personal knowledge management
devops-agent Infrastructure management

Skills

Skills extend your agents' capabilities. They are modular, self-contained packages with specialized workflows.

⚠️ Security Rule

NEVER use a skill that hasn't been:

  1. Copied to skills/ or my-skills/
  2. Scanned with skill-security-scanner
  3. Approved by you

Installing a Skill

# Step 1: Copy skill to your skills directory
cp -r /path/to/skill skills/my-new-skill

# Step 2: MANDATORY - Run security scan
python3 skills/skill-security-scanner/scripts/scan.py --path skills/my-new-skill --format json

# Step 3: Review findings, accept if clean
# Step 4: Symlink for Claude Code
ln -s /opt/my-bot-home/skills/my-new-skill /opt/my-bot-home/.claude/skills/my-new-skill

Or use the helper script:

./bin/install-skill.sh /path/to/skill

Recommended First Skills

From anthropic/skills (scan before installing!):

Skill Purpose
skill-creator Helps you build new skills
pdf Read/create/edit PDF files
docx Word document manipulation
xlsx Spreadsheet manipulation
mcp-builder Build MCP servers

Skill Discovery Locations

Runtime Location
Claude Code .claude/skills/ (symlinks)
Copilot CLI skills/ and my-skills/
Gemini Configured in GEMINI.md

Connecting to Wee-Orchestrator

Wee-Orchestrator handles the bot communication layer (WebEx, Telegram, etc.) and routes messages to your agents.

Architecture

User (WebEx/Telegram)
       ↓
Wee-Orchestrator (/opt/n8n-copilot-shim)
       ↓
Agent Manager → Copilot CLI / Claude / Gemini
       ↓
Your Bot Home (AGENTS.md config)

WebUI Features

When using the Web UI (https://localhost:8000/ui), you'll see:

  • 🔧 Expandable Tool Calls — Tool invocations appear as collapsible blocks. Click ▶ to expand and view tool output with markdown rendering, error highlighting, and dark/light theme support.
  • 📊 Real-time Streaming — Responses stream in real-time with markdown formatting
  • 🔐 Session Persistence — Full conversation history with search and resume
  • ⚙️ Session Settings — Toggle silent mode to hide tool call blocks

For details, see Wee-Orchestrator README — Tool Call Visualization.

Configuration Files (NOT committed to git)

# WebEx bot
/opt/n8n-copilot-shim/webex_config.json

# Telegram bot
/opt/n8n-copilot-shim/telegram_config.json

WebEx Bot Configuration — Managed AMQP Brokers

If your RabbitMQ broker grants only CONSUME permission (e.g., Cisco CX-HOSTED-BOTS-PROD or other hosted AMQP services), add this to webex_config.json:

{
  "webex": {
    "token": "your-webex-bot-token",
    "rabbitmq_host": "your-rabbitmq-host",
    "rabbitmq_port": 5671,
    "rabbitmq_user": "bot_user",
    "rabbitmq_password": "...",
    "rabbitmq_queue": "webex_queue",
    "rabbitmq_queue_passive": true,
    "rabbitmq_ssl": true
  }
}

Purpose: Setting "rabbitmq_queue_passive": true performs a passive queue assertion instead of attempting to create/modify the queue. This prevents ACCESS_REFUSED (403) errors on brokers where your bot user lacks queue management permissions.

Default: false (no change needed for standard RabbitMQ setups)

WebEx Bot Configuration — Nested Payload Unwrap (Issue #268)

Some WebEx gateways (e.g., Cisco CX-HOSTED-BOTS-PROD) wrap the actual message in a nested structure. Use rabbitmq_payload_key to extract the inner message before processing:

{
  "webex": {
    "token": "your-webex-bot-token",
    "rabbitmq_host": "your-rabbitmq-host",
    "rabbitmq_queue": "webex_queue",
    "rabbitmq_payload_key": "data"
  }
}

For deeply nested payloads, use dot-notation to reach the target field:

{
  "rabbitmq_payload_key": "data.message_data"
}

Purpose: When a gateway delivers {"data": {"personEmail": "...", "text": "hello"}}, setting rabbitmq_payload_key: "data" extracts the inner object before routing. Without this, the outer wrapper reaches the agent unparsed.

Default: "" (empty — no unwrapping; standard single-level payloads work as before)

Context Window Management (Wee Native Runtime)

The wee runtime automatically tracks context window usage and warns when approaching model limits.

Automatic warning at 75% usage:

⚠️  Context window at 78.3% — consider /compact to free space.

/tokens command — view live token stats:

/tokens
# Tokens — prompt: 45,231, completion: 12,442, total: 57,673, turns: 14
# Context window: 9,450/128,000 tokens (7.4% used)

/compact command — triggered manually or proactively:

/compact       # Compact conversation history to 50% of context window (default)
/compact 40    # Compact to 40% of context window

Context sizes are resolved automatically for 20+ model families (GPT-4.1: 1M tokens, Claude 3: 200K, Llama 3: 128K, etc.). Unknown models default to 4,096 tokens.

See Context Window Management in the main repo for the full model registry, TokenTracker API, and compact_messages() reference.

Environment Variables (Wee Native Runtime)

When using the wee runtime (Ollama, OpenRouter, LM Studio), these env vars control behavior:

Variable Default Description
WEE_API_BASE Ollama preset Override API base URL
WEE_API_KEY From keyring API key for authenticated endpoints
WEE_DEFAULT_MODEL — Default model when not specified in config
WEE_SEARXNG_URL http://192.168.1.100:8888 SearXNG URL for the native search tool

Set in your shell profile or systemd service environment, never in committed files:

export WEE_SEARXNG_URL="http://your-searxng-host:8888"  # optional, if self-hosting SearXNG

The search tool lets agents perform web searches via SearXNG. If WEE_SEARXNG_URL is not set, it defaults to http://192.168.1.100:8888. Skip this if you don't have a SearXNG instance — the tool will return a graceful error.

Delegating Tasks

python3 /opt/n8n-copilot-shim/agent_manager.py \
  --agent <agent_name> \
  --runtime copilot \
  --model gpt-5 \
  --config /opt/agents.json \
  "task description" \
  <session_id>

Memory System

Agents store knowledge in memory/ using the PARA methodology:

memory/
├── projects/     # Active multi-step initiatives
├── areas/        # Ongoing responsibilities
├── resources/    # Reference material
└── archive/      # Completed items

Never store secrets in memory files.

Development Workflow

# Make changes
# Add and commit
git add .
git commit -m "your change"
git push

Always push immediately after committing so all agents stay in sync.

License

MIT — fork it, modify it, make it your own.

About

Skeleton starter kit for building bots with Wee-Orchestrator — multi-agent AI orchestration for Claude, Gemini, and Copilot CLI

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages