Wee-Orchestrator

2. Install dependencies

pip install -r requirements.txt

Requirements

This project requires one or more of the following AI CLI tools to be installed:

Bot Setup Guide

Wee-Orchestrator enables you to create custom bots — specialized AI agents with their own configuration, knowledge base, and capabilities. Each bot is a self-contained repository that can be integrated with Wee-Orchestrator.

🚀 New here? Use the Wee-Orchestrator Starter Kit to scaffold a new bot in minutes — includes AGENTS.md, skill management with security scanning, memory structure, and setup scripts.

Getting Started

💡 Recommended: Fork the Wee-Orchestrator Starter Kit instead of starting from scratch — it includes everything below pre-configured with best practices, security scanning, and setup scripts.

1. Create your bot repository:

   mkdir my-bot && cd my-bot
   git init
   git remote add origin https://github.com/username/my-bot.git
   

2. Add AGENTS.md: Copy and customize the AGENTS.md template from Wee-Orchestrator with your bot's preferences

3. Create memory directory:

   mkdir -p memory/{projects,areas,resources,archive}
   echo "# Knowledge Base" > memory/INDEX.md
   

4. Add .env and .gitignore:

   cp /opt/n8n-copilot-shim-dev/.env.example .env
   echo ".env" >> .gitignore
   echo "*.key" >> .gitignore
   echo "secrets.json" >> .gitignore
   

5. Link or implement skills:

   mkdir skills
   ln -s /opt/pot-o-skills skills/cisco-meraki
   

6. Register with Wee-Orchestrator: Update Wee-Orchestrator's agents.json to include your bot:

   {
     "agents": [
       {
         "name": "my-bot",
         "path": "/opt/my-bot",
         "enabled": true
       }
     ]
   }
   

Setup

1. Copy the agent manager script:

   cp agent_manager.py /usr/local/bin/agent-manager
   chmod +x /usr/local/bin/agent-manager
   

2. Configure your agents: - Copy agents.example.json to agents.json - Edit agents.json with your actual repository paths - Place agents.json in the same directory as the script or current working directory

3. Optional: Specify config location via environment variable

   export AGENTS_CONFIG=/path/to/custom/agents.json
   

⚡ Quick Start

```bash

Example Bot Structure

my-bot/
├── README.md                  # Bot overview & usage
├── AGENTS.md                  # Agent behavior & configuration
├── .env                       # Credentials (git-ignored)
├── .gitignore                 # Protect secrets
│
├── memory/                    # Knowledge base (PARA methodology)
│   ├── projects/              # Active multi-step initiatives
│   ├── areas/                 # Ongoing responsibility areas
│   ├── resources/             # Reference material & best practices
│   └── archive/               # Completed/deprecated items
│
├── skills/                    # Custom skill implementations
│   ├── custom-skill-1/
│   └── custom-skill-2/
│
└── domain-folders/            # Domain-specific organization
    ├── email/                 # Email processing
    ├── home-automation/       # Smart home tasks
    └── infrastructure/        # Infrastructure management

Usage

Basic usage

python agent_manager.py "List all files in the current directory"

Quick Start

```bash

📸 Screenshots

Chat Interface	Task Scheduler
Secure Pairing Login	Architecture Overview

---

3. Configure your environment

cp .env.example .env # Edit with your API keys and bot tokens

6. (Optional) Start channel connectors

python3 telegram_connector.py # Telegram bot python3 webex_connector.py # WebEx bot ```

Then open http://localhost:8000/ui in your browser and pair via Telegram or WebEx.

🚀 Want to create your own bot? Use the Wee-Orchestrator Starter Kit to scaffold one in minutes.

---

Permission Configuration by Runtime

#### GitHub Copilot CLI - Flags Used: --allow-all-tools --allow-all-paths - Enables: - All MCP tools and shell commands without approval - Read/write/execute permissions for all files and directories - Security Note: Gives Copilot the same permissions as your user account

#### Claude Code CLI - Flags Used: --permission-mode bypassPermissions - Enables: - Auto-approve all file edits, writes, and reads - Execute shell commands without approval - Access web/network tools without prompts - Also Known As: YOLO mode or dontAsk mode

#### OpenCode CLI - Configuration: Uses opencode.json file for permission settings - Required Setup: 1. Copy the example config: cp opencode.example.json opencode.json 2. Place opencode.json in your agent directories or project root - Permissions Enabled: - edit: allow - write: allow - bash: allow - read: allow - webfetch: allow - Reference: OpenCode Permissions Documentation

#### Google Gemini CLI - Flags Used: --yolo - Enables: - Read/write file operations without confirmation - Shell command execution without approval - All built-in tools with unrestricted access - Built-in Tools: read_file, write_file, run_shell_command

#### OpenAI Codex CLI - Flags Used: --dangerously-bypass-approvals-and-sandbox - Enables: - Disables all approval prompts - Removes sandbox restrictions (full file system access) - Allows all shell commands and tools without confirmation - Security Note: Only use in trusted, controlled environments

#### Claude Agent SDK (Python) - Package: claude-agent-sdk>=0.1.0 (install via pip install claude-agent-sdk) - Enables: - In-process async execution (no subprocess spawn) - Structured error types (CLINotFoundError, CLIConnectionError, ProcessError) - Native permission_mode field instead of CLI flags - Session continuity via ResultMessage.session_id capture - Permission Modes: - elevated → bypassPermissions (full access, no prompts) - sandboxed → plan (read-only + approval for writes) - restricted → default (standard safety checks) - Streaming: Real-time text chunks pushed to WebUI SSE consumers via _StreamBuffer - Tool Calls: ToolUseBlock/ToolResultBlock detection emits standardized tool_call events - Usage: /runtime set claude-agent-sdk - Issues: #77, #87, #91, #94

#### GitHub Copilot SDK (Python) - Package: github-copilot-sdk>=0.1.0 (install via pip install github-copilot-sdk) - Enables: - In-process async execution via CopilotClient - Real-time streaming via ASSISTANT_STREAMING_DELTA/ASSISTANT_MESSAGE_DELTA events - Tool call tracking via TOOL_EXECUTION_START/COMPLETE and COMMAND_EXECUTE events - Session resumption and structured error handling - Usage: /runtime set copilot-sdk - Issues: #76, #87, #91

#### Wee Native Runtime - Also Known As: wee — OpenAI-compatible API backend runtime - Description: Connects to any OpenAI-compatible API endpoint (Ollama, OpenRouter, LM Studio, etc.) without depending on external CLI tools like GitHub Copilot CLI, Claude Code, or OpenCode. - Supported Backends: - Ollama at http://192.168.1.101:11434/v1 — local, free (Kubuntu) - OpenRouter at https://openrouter.ai/api/v1 — cloud fallback, 100+ models - LM Studio at http://localhost:1234/v1 — local alternative - Model Format: Uses provider/model_name prefix syntax for auto-resolving API base URL and API key: - ollama/gemma4:e4b — Ollama on Kubuntu (default) - openrouter/meta-llama/llama-4-scout — OpenRouter cloud - lmstudio/qwen2.5-7b — LM Studio local - Configuration Example:

  {
    "runtime": "wee",
    "model": "ollama/gemma4:e4b"
  }
  

• Features & Improvements:
• OpenRouter integration: Full UI support for cloud-based models with 300s cached discovery & keyring-based API key management (Issue #119)
• Global notification toggle: Suppress all background task notifications with /notifications off; critical alerts always deliver (Issue #146)
• Model grouping in UI: Ollama and OpenRouter models displayed in separate dropdown optgroups
• All OpenRouter models in model listing: Removed hardcoded filter to show 350+ OpenRouter models instead of ~12 (Issue #145)

• Bug Fixes:
• Wrong Ollama port corrected: 11436 → 11434 (Issue #105)
• httpx.Timeout(connect=15s) and max_retries=0 added to OpenAI client for fast-fail on bad endpoints (Issue #105)
• Model resolution fixed: get_models_for_runtime('wee') returns flat strings; get_model_from_name() strips provider prefix (ollama/) and prefers exact/shortest match (Issue #105)
• Bug Fixes (continued):
• OpenRouter 401 auth fixed: OPENROUTER_API_KEY env var + keyring resolution replaces silent 'ollama' fallback; raises clear error when no key found (Issue #153)
• Issues: #88, #105, #119, #146, #153, #255

Configuration

Agent Configuration

The system loads agents from agents.json or a custom config file. Each agent represents a repository context where the AI CLI will operate.

Config Format:

{
  "agents": [
    {
      "name": "devops",
      "description": "DevOps and infrastructure management",
      "path": "/path/to/MyHomeDevops"
    },
    {
      "name": "projects",
      "description": "Software development projects",
      "path": "/path/to/projects"
    }
  ]
}

Configuration Fields: - name (required): Short identifier for the agent (used in /agent set commands) - description (required): Brief human-readable description of the agent - path (required): Full path to the repository or project directory

Environment Configuration

⚠️ API_HOST Security Warning Never set API_HOST=0.0.0.0 — this exposes the server on every network interface including your LAN and any public NIC. Always bind to specific trusted interfaces (e.g. 127.0.0.1,<tailscale-ip>). See Network Binding & Secure Access.

The default agent, model, and runtime can be customized via environment variables. This is useful for: - Different users having different defaults - Docker container configuration - CI/CD pipeline customization - Development vs. production setups

Available Environment Variables:

```bash

Edit .env with your defaults

```

When environment variables are not set, the system uses these hardcoded defaults: - Agent: orchestrator - Model: gpt-5-mini - Runtime: copilot

With custom config file

python agent_manager.py "Deploy the app" "session-456" "/etc/agents.json"

#### Advanced Usage (Named Arguments)

**Options:**

Agent Options:
- `--agent NAME` - Set the agent to use (e.g., devops, family, projects)
- `--list-agents` - List all available agents and exit

Model Options:
- `--model NAME` - Set the model to use (e.g., gpt-5, sonnet, gemini-1.5-pro)
- `--list-models` - List all available models for current runtime and exit

Runtime Options:
- `--runtime NAME` - Set the runtime to use (choices: copilot, opencode, claude, claude-agent-sdk, gemini, copilot-sdk, codex, devin)
- `--list-runtimes` - List all available runtimes and exit

Configuration:
- `--config FILE` or `-c FILE` - Path to agents.json configuration file

**Examples:**

List available agents with custom config

python agent_manager.py --list-agents --config my-agents.json

Combine multiple options

python agent_manager.py --agent family --runtime claude --model sonnet "Find recipes for dinner"

Use custom configuration file

python agent_manager.py --config /etc/my-agents.json --agent projects "Review pull requests"

All options together

python agent_manager.py --config my-agents.json --agent devops --runtime claude --model haiku "Deploy to production" "session-123"

**Getting Help:**

5. Start the API server

python3 agent_manager.py --api

Or using the CLI wrapper

pip install gemini-cli

**Authentication:**

Set your API key as an environment variable:

Or configure it in your shell profile:

Supported Systems: Windows, macOS, Linux

Reference: Google Gemini API Documentation

Key Components

#### AGENTS.md Defines the bot's behavior, preferences, and runtime configuration: - Agent name, purpose, and timezone - Preferred models and runtimes (Claude, Copilot, Gemini) - Tool permissions and access control - Sub-agent delegation rules - Skill definitions and repository locations - Security and credential management

Example excerpt:

N8N Integration

Use in an N8N workflow:

#### Basic N8N Integration (Positional Arguments)

// Execute the agent manager from N8N
const { exec } = require('child_process');
const prompt = "Your prompt here";
const sessionId = "n8n_session_123";
const configFile = "/path/to/agents.json";

exec(`python agent_manager.py "${prompt}" "${sessionId}" "${configFile}"`,
  (error, stdout, stderr) => {
    if (error) console.error(error);
    console.log(stdout);
  }
);

#### Advanced N8N Integration (Named Arguments)

// Execute with specific agent, runtime, and model
const { exec } = require('child_process');
const agent = "devops";
const runtime = "claude";
const model = "sonnet";
const prompt = "Check production status";
const sessionId = "n8n_session_123";

const cmd = `python agent_manager.py --agent ${agent} --runtime ${runtime} --model ${model} "${prompt}" "${sessionId}"`;

exec(cmd, (error, stdout, stderr) => {
  if (error) console.error(error);
  console.log(stdout);
});

#### List Agents from N8N

// Get available agents dynamically
const { exec } = require('child_process');
const configFile = "/path/to/agents.json";

exec(`python agent_manager.py --list-agents --config ${configFile}`,
  (error, stdout, stderr) => {
    if (error) console.error(error);
    // Parse stdout to get agent list
    console.log(stdout);
  }
);