discoclaw 0.1.0

package/.env.example.full

@@ -0,0 +1,378 @@
+# ============================================================
+# Discoclaw — Complete Environment Reference
+# ============================================================
+# This is the full reference for all ~90 env vars.
+# For quick start, see .env.example (only the essentials).
+# Primary guided setup: run `discoclaw init` (global install).
+# From source: run `pnpm setup` for guided interactive configuration.
+# ============================================================
+
+# ----------------------------------------------------------
+# REQUIRED — the bot won't start without these
+# ----------------------------------------------------------
+
+# Your Discord bot token (from https://discord.com/developers/applications)
+# Important: You must also enable Message Content Intent in the Discord Developer Portal
+# (Bot page → Privileged Gateway Intents). Without it, the bot silently receives empty messages.
+DISCORD_TOKEN=
+
+# Comma-separated Discord user IDs allowed to talk to the bot.
+# Empty = nobody can use it (fail-closed).
+DISCORD_ALLOW_USER_IDS=
+
+# Tasks forum channel ID (required when DISCOCLAW_TASKS_ENABLED=1; default on).
+DISCOCLAW_TASKS_FORUM=
+
+# Automations forum channel ID (cron subsystem; required when DISCOCLAW_CRON_ENABLED=1; default on).
+DISCOCLAW_CRON_FORUM=
+
+# ----------------------------------------------------------
+# CORE — most users will want to review these
+# ----------------------------------------------------------
+
+# Where the Claude CLI runs (its working directory).
+# Default: ./workspace (or $DISCOCLAW_DATA_DIR/workspace if DATA_DIR is set)
+#WORKSPACE_CWD=
+
+# Primary runtime adapter for bot messages, crons, summaries, and plan execution.
+# Valid values: claude | gemini | codex | openai | openrouter
+# - openai requires OPENAI_API_KEY
+# - openrouter requires OPENROUTER_API_KEY
+# - claude requires a working Claude CLI
+# - gemini requires the Gemini CLI (GEMINI_BIN)
+#PRIMARY_RUNTIME=claude
+
+# --- Primary models ---
+# Model tier: fast | capable (provider-agnostic).
+# Concrete model names (e.g. opus, sonnet, gpt-4o) are still accepted as passthrough.
+#RUNTIME_MODEL=capable
+
+# --- Fast-tier default ---
+# Sets the default model for all "small" tasks (summary, cron, cron auto-tag, task auto-tag).
+# Individual overrides (DISCOCLAW_SUMMARY_MODEL, etc.) still win when set.
+#DISCOCLAW_FAST_MODEL=fast
+
+# Output format for the Claude CLI. stream-json gives smoother streaming.
+#CLAUDE_OUTPUT_FORMAT=stream-json
+
+# Allow Claude to run without permission prompts. This is what makes
+# headless/Discord operation possible — the Discord allowlist above
+# is the security boundary instead.
+#CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1
+
+# --- Gemini CLI adapter ---
+# Path to the Gemini CLI binary (default: gemini).
+#GEMINI_BIN=gemini
+# Default model for the Gemini CLI adapter.
+#GEMINI_MODEL=gemini-2.5-pro
+
+# Log level: trace | debug | info | warn | error | fatal
+#LOG_LEVEL=info
+
+# ============================================================
+# CORE SUBSYSTEMS — enabled by default, configure as needed
+# ============================================================
+
+# ----------------------------------------------------------
+# Cron — forum-based scheduled tasks (enabled by default)
+# ----------------------------------------------------------
+# Forum channel ID is configured above in REQUIRED.
+# Model tier for cron execution: fast | capable (concrete names accepted as passthrough).
+#DISCOCLAW_CRON_MODEL=fast
+# Enable cron Discord actions (CRUD via Discord action blocks).
+#DISCOCLAW_DISCORD_ACTIONS_CRONS=1
+# Persistent stats directory (run counts, last run time, status).
+#DISCOCLAW_CRON_STATS_DIR=
+# AI auto-tagging for cron purpose + model tier (off until tags bootstrapped).
+#DISCOCLAW_CRON_AUTO_TAG=0
+#DISCOCLAW_CRON_AUTO_TAG_MODEL=fast
+# Runtime tag-map file (seeded from scripts/cron/cron-tag-map.json on first boot).
+#DISCOCLAW_CRON_TAG_MAP=
+# Set to 0 to disable cron entirely.
+#DISCOCLAW_CRON_ENABLED=1
+
+# ----------------------------------------------------------
+# Tasks — task tracking (enabled by default)
+# ----------------------------------------------------------
+# Forum channel ID is configured above in REQUIRED.
+# Guild ID — used for task sync bootstrap and system channel bootstrap.
+# Also used for System channel bootstrap when the bot is in multiple servers.
+DISCORD_GUILD_ID=
+# Runtime tag-map file (seeded from scripts/tasks/tag-map.json on first boot).
+#DISCOCLAW_TASKS_TAG_MAP=
+# Skip Phase 5 (thread reconciliation) during task sync. Useful for shared-forum deployments
+# where multiple instances share the same forum and you don't want cross-instance archival.
+#DISCOCLAW_TASKS_SYNC_SKIP_PHASE5=0
+# Enable/disable retries after sync failures.
+#DISCOCLAW_TASKS_SYNC_FAILURE_RETRY_ENABLED=1
+# Delay before failure retries (ms).
+#DISCOCLAW_TASKS_SYNC_FAILURE_RETRY_DELAY_MS=30000
+# Delay before deferred-close retries (ms).
+#DISCOCLAW_TASKS_SYNC_DEFERRED_RETRY_DELAY_MS=30000
+#DISCOCLAW_TASKS_MENTION_USER=
+# When 1 and MENTION_USER set, open task starters keep @mention for sidebar visibility; removed on close.
+#DISCOCLAW_TASKS_SIDEBAR=0
+#DISCOCLAW_TASKS_AUTO_TAG=1
+#DISCOCLAW_TASKS_AUTO_TAG_MODEL=fast
+# Set to 0 to disable tasks entirely.
+#DISCOCLAW_TASKS_ENABLED=1
+# Prefix for generated task IDs (e.g. ws-001).
+#DISCOCLAW_TASKS_PREFIX=ws
+
+# ----------------------------------------------------------
+# Discord actions — let Claude manage your server (enabled by default)
+# ----------------------------------------------------------
+# Master switch — must be 1 for any action category to work (default: 1).
+# Enabling it unlocks the defer command below (and all other action categories).
+#DISCOCLAW_DISCORD_ACTIONS=1
+# Per-category flags (only active when master switch is 1):
+#DISCOCLAW_DISCORD_ACTIONS_CHANNELS=1
+#DISCOCLAW_DISCORD_ACTIONS_MESSAGING=0
+#DISCOCLAW_DISCORD_ACTIONS_GUILD=0
+# Intentionally off — moderation actions require explicit opt-in.
+#DISCOCLAW_DISCORD_ACTIONS_MODERATION=0
+#DISCOCLAW_DISCORD_ACTIONS_POLLS=0
+#DISCOCLAW_DISCORD_ACTIONS_TASKS=1
+# Allow the AI to self-initiate forge runs (draft + audit loops) via action blocks.
+# Requires DISCOCLAW_FORGE_COMMANDS_ENABLED=1. Only one forge at a time. Default: 1.
+#DISCOCLAW_DISCORD_ACTIONS_FORGE=1
+# Allow the AI to create, inspect, approve, run, and close plans via action blocks.
+# Requires DISCOCLAW_PLAN_COMMANDS_ENABLED=1. Default: 1.
+#DISCOCLAW_DISCORD_ACTIONS_PLAN=1
+# Allow the AI to read/write durable memory (facts, preferences) via action blocks.
+# Requires DISCOCLAW_DURABLE_MEMORY_ENABLED=1. Default: 1.
+#DISCOCLAW_DISCORD_ACTIONS_MEMORY=1
+# Allow the AI to change status, activity, and nickname at runtime.
+#DISCOCLAW_DISCORD_ACTIONS_BOT_PROFILE=0
+
+# Allow the AI to defer another invocation (e.g., "check on the forge run in 10 minutes").
+# The scheduler enforces DISCOCLAW_DISCORD_ACTIONS=1, respects the requesting message's channel
+# permissions, and prevents chaining by disabling defer during the follow-up run.
+DISCOCLAW_DISCORD_ACTIONS_DEFER=1
+# Optional guard rails keep deferred invocations within safe bounds.
+# Maximum delay (seconds) the scheduler will accept for defer commands (default: 1800 / 30 min).
+#DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DELAY_SECONDS=1800
+# Maximum number of pending deferred invocations allowed at once (default: 5).
+#DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_CONCURRENT=5
+
+# ============================================================
+# OPTIONAL — uncomment sections you need
+# ============================================================
+
+# ----------------------------------------------------------
+# Channel restrictions
+# ----------------------------------------------------------
+# Restrict the bot to specific guild channel IDs (comma/space-separated).
+# DMs are still allowed. For threads, allowlist the parent channel ID.
+#DISCORD_CHANNEL_IDS=
+# Require a channel-context file to exist before responding in a channel.
+#DISCORD_REQUIRE_CHANNEL_CONTEXT=1
+# Auto-create channel context scaffold on first message in a new channel.
+#DISCORD_AUTO_INDEX_CHANNEL_CONTEXT=1
+# Auto-join threads so the bot can respond inside them.
+# Note: private threads still require manually adding the bot.
+#DISCORD_AUTO_JOIN_THREADS=0
+
+# ----------------------------------------------------------
+# Reaction handler (trigger AI via emoji reactions)
+# ----------------------------------------------------------
+# Master switch — when enabled, reacting to a message with any emoji
+# triggers the AI to respond to that message (allowlist still applies).
+#DISCOCLAW_REACTION_HANDLER=0
+# Ignore reactions on messages older than this many hours (prevents
+# accidental triggers when scrolling through old history).
+#DISCOCLAW_REACTION_MAX_AGE_HOURS=24
+# Reaction-remove handler — fires when a user removes a reaction.
+# Disabled by default; useful for workflows where un-reacting has meaning.
+#DISCOCLAW_REACTION_REMOVE_HANDLER=0
+# Note: 🛑 reactions on bot in-progress messages are reserved for aborting the active stream and will never trigger an AI invocation.
+
+# ----------------------------------------------------------
+# Memory & summaries
+# ----------------------------------------------------------
+# Rolling AI-generated summaries of past conversations.
+#DISCOCLAW_SUMMARY_ENABLED=1
+#DISCOCLAW_SUMMARY_MODEL=fast
+#DISCOCLAW_SUMMARY_MAX_CHARS=2000
+#DISCOCLAW_SUMMARY_EVERY_N_TURNS=5
+# Durable per-user facts/preferences (manual via !memory commands).
+#DISCOCLAW_DURABLE_MEMORY_ENABLED=1
+#DISCOCLAW_DURABLE_INJECT_MAX_CHARS=2000
+#DISCOCLAW_DURABLE_MAX_ITEMS=200
+#DISCOCLAW_MEMORY_COMMANDS_ENABLED=1
+# Cross-channel short-term memory (per-guild, per-user ring buffer).
+# Records recent exchanges across public channels for cross-channel awareness.
+#DISCOCLAW_SHORTTERM_MEMORY_ENABLED=0
+#DISCOCLAW_SHORTTERM_MAX_ENTRIES=20
+#DISCOCLAW_SHORTTERM_MAX_AGE_HOURS=6
+#DISCOCLAW_SHORTTERM_INJECT_MAX_CHARS=1000
+# Auto-extract notable facts from user messages into durable memory.
+# Runs after rolling summary generation. Default on.
+#DISCOCLAW_SUMMARY_TO_DURABLE_ENABLED=1
+# Character budget for recent conversation history in prompts (0 = disabled).
+#DISCOCLAW_MESSAGE_HISTORY_BUDGET=3000
+
+# ----------------------------------------------------------
+# Bot identity
+# ----------------------------------------------------------
+# Bot display name (server nickname). Falls back to workspace/IDENTITY.md name, then "Discoclaw".
+#DISCOCLAW_BOT_NAME=
+# Presence status on startup: online | idle | dnd | invisible (default: don't set)
+#DISCOCLAW_BOT_STATUS=
+# Activity text on startup (empty = no activity)
+#DISCOCLAW_BOT_ACTIVITY=
+# Activity type: Playing (default) | Listening | Watching | Competing | Custom
+#DISCOCLAW_BOT_ACTIVITY_TYPE=Playing
+# Avatar image: absolute file path or URL (applied once on startup; empty = don't change)
+#DISCOCLAW_BOT_AVATAR=
+
+# ----------------------------------------------------------
+# Status & observability
+# ----------------------------------------------------------
+# Channel name or ID to post status embeds (bot online/offline, errors).
+#DISCOCLAW_STATUS_CHANNEL=
+# Enable health commands (`!health`, `!health verbose`) for allowlisted users.
+#DISCOCLAW_HEALTH_COMMANDS_ENABLED=1
+# Optional subset allowlist for `!health verbose` (comma/space-separated IDs).
+# Empty = any allowlisted user can use verbose mode.
+#DISCOCLAW_HEALTH_VERBOSE_ALLOWLIST=
+
+# ----------------------------------------------------------
+# Advanced / debug
+# ----------------------------------------------------------
+# Data root — if set, workspace defaults to $DISCOCLAW_DATA_DIR/workspace.
+#DISCOCLAW_DATA_DIR=
+# Content directory override.
+#DISCOCLAW_CONTENT_DIR=
+# Enable per-session runtime isolation.
+#DISCOCLAW_RUNTIME_SESSIONS=1
+# Path to claude CLI binary (if not on $PATH).
+#CLAUDE_BIN=claude
+# Forward Claude CLI stderr to Discord (useful for debugging).
+#CLAUDE_ECHO_STDIO=0
+# Pass --verbose to the Claude CLI for increased output detail.
+# Requires CLAUDE_OUTPUT_FORMAT=stream-json (auto-disabled with text format).
+#CLAUDE_VERBOSE=0
+# Write Claude CLI debug logs to this file.
+#CLAUDE_DEBUG_FILE=
+# Skip slow MCP plugin init in headless/systemd contexts.
+#CLAUDE_STRICT_MCP_CONFIG=1
+# Dump resolved runtime config at startup.
+#DISCOCLAW_DEBUG_RUNTIME=0
+# Per-group working directories.
+#GROUPS_DIR=
+#USE_GROUP_DIR_CWD=0
+# Tools available to the runtime (Glob, Grep, Write now included by default).
+#RUNTIME_TOOLS=Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch
+# Fallback model tier when primary is overloaded (concrete names accepted as passthrough).
+#RUNTIME_FALLBACK_MODEL=fast
+# Max USD spend per Claude CLI process. One-shot: per invocation.
+# Multi-turn: per session lifetime (accumulates across turns). Recommend $5-10.
+#RUNTIME_MAX_BUDGET_USD=5.00
+# Append to Claude's system prompt (pre-loads PA identity, skips workspace PA file reads).
+# Max 4000 chars. Condense SOUL.md + IDENTITY.md + USER.md + TOOLS.md content here.
+# Note: Do not set this on first run before workspace/BOOTSTRAP.md has been consumed,
+# as the skip logic also bypasses BOOTSTRAP.md loading.
+#CLAUDE_APPEND_SYSTEM_PROMPT=
+# Override the default platform-detected restart command used by !restart and
+# !update apply. Useful for custom setups (e.g. Docker, non-standard service
+# managers, or running under a different user). If unset, the command is
+# auto-selected: systemctl --user on Linux, launchctl on macOS.
+#DC_RESTART_CMD=
+# Global cap on parallel runtime invocations across all Discord sessions (0 = unlimited).
+#DISCOCLAW_MAX_CONCURRENT_INVOCATIONS=3
+# Timeout for runtime invocations (ms).
+#RUNTIME_TIMEOUT_MS=1800000
+# Stream stall detection: kill one-shot process if no stdout/stderr for this long (ms). 0 = disabled.
+#DISCOCLAW_STREAM_STALL_TIMEOUT_MS=120000
+# Stream stall warning: show user-visible warning in Discord after this many ms of no events. 0 = disabled.
+# Enable DISCOCLAW_SESSION_SCANNING=1 for tool-aware stall suppression (warnings suppressed during tool execution).
+#DISCOCLAW_STREAM_STALL_WARNING_MS=60000
+
+# ----------------------------------------------------------
+# Plan & Forge — AI-assisted planning and implementation
+# ----------------------------------------------------------
+# Enable/disable !plan and !forge commands.
+#DISCOCLAW_PLAN_COMMANDS_ENABLED=1
+#DISCOCLAW_FORGE_COMMANDS_ENABLED=1
+# Phase decomposition for approved plans.
+#PLAN_PHASES_ENABLED=1
+# Max files per phase batch during decomposition.
+#PLAN_PHASE_MAX_CONTEXT_FILES=5
+# Per-phase execution timeout (ms). Default: 1800000 (30 min).
+#PLAN_PHASE_TIMEOUT_MS=1800000
+# Max audit-fix attempts per phase before marking failed.
+#PLAN_PHASE_AUDIT_FIX_MAX=2
+# Max draft-audit-revise loops before CAP_REACHED.
+#FORGE_MAX_AUDIT_ROUNDS=5
+# Model overrides for forge roles (fall back to RUNTIME_MODEL).
+#FORGE_DRAFTER_MODEL=
+#FORGE_AUDITOR_MODEL=
+# Per-agent timeout within forge (ms).
+#FORGE_TIMEOUT_MS=1800000
+# Min interval between Discord progress message edits (ms).
+#FORGE_PROGRESS_THROTTLE_MS=3000
+# Enabling this immediately approves/runs clean plans (no blocking/medium/minor severity markers);
+# disabling it keeps the manual `!plan approve` + `!plan run` prompts.
+#FORGE_AUTO_IMPLEMENT=1
+
+# ----------------------------------------------------------
+# Multi-provider auditor
+# ----------------------------------------------------------
+# Route the forge auditor to a non-Claude runtime.
+# Valid values: "codex" (Codex CLI), "openai" (OpenAI-compatible HTTP API), "openrouter" (OpenRouter).
+#FORGE_AUDITOR_RUNTIME=codex
+
+# --- Codex CLI adapter ---
+# Path to the Codex CLI binary (default: codex).
+#CODEX_BIN=codex
+# Optional: isolate Codex state/sessions from ~/.codex (helps avoid stale rollout DB issues).
+#CODEX_HOME=/absolute/path/to/.codex-home-discoclaw
+# Default model for the Codex CLI adapter. Used when FORGE_AUDITOR_MODEL is not set.
+#CODEX_MODEL=gpt-5.3-codex
+# WARNING: disables Codex approval prompts and sandbox protections (full-access mode).
+# Equivalent to passing --dangerously-bypass-approvals-and-sandbox to codex exec.
+#CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=0
+# Disable Codex session persistence/resume (workaround for session DB issues).
+#CODEX_DISABLE_SESSIONS=0
+
+# --- OpenAI-compatible HTTP adapter ---
+# API key for the OpenAI-compatible adapter. Required when FORGE_AUDITOR_RUNTIME=openai.
+#OPENAI_API_KEY=
+# Base URL (override for proxies, Azure OpenAI, Ollama, etc.).
+#OPENAI_BASE_URL=https://api.openai.com/v1
+# Default model when FORGE_AUDITOR_MODEL is not set.
+#OPENAI_MODEL=gpt-4o
+
+# --- OpenRouter adapter ---
+# API key for OpenRouter. Required when PRIMARY_RUNTIME=openrouter or FORGE_*_RUNTIME=openrouter.
+#OPENROUTER_API_KEY=
+# Base URL (default: OpenRouter API endpoint).
+#OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# Default model for the OpenRouter adapter.
+#OPENROUTER_MODEL=anthropic/claude-sonnet-4
+
+# ----------------------------------------------------------
+# Webhooks — inbound HTTP triggers from external services
+# ----------------------------------------------------------
+# TCP port the webhook server listens on (default: 9400).
+#DISCOCLAW_WEBHOOK_PORT=9400
+# Absolute path to the webhook source config file.
+# JSON object mapping source names to their config:
+#   {
+#     "github": { "secret": "hmac-secret", "channel": "123456789" },
+#     "gms":    { "secret": "hmac-secret", "channel": "987654321" }
+#   }
+# - secret: HMAC-SHA256 secret used to verify the X-Hub-Signature-256 header.
+# - channel: Discord channel name or ID where the webhook posts (reuses cron pipeline).
+#DISCOCLAW_WEBHOOK_CONFIG=
+# Set to 1 to enable the webhook server.
+#DISCOCLAW_WEBHOOK_ENABLED=0
+# To expose webhooks to external services, see docs/webhook-exposure.md
+
+# ----------------------------------------------------------
+# Browser automation (agent-browser)
+# ----------------------------------------------------------
+# Chromium path for agent-browser. Only needed if the bundled browser
+# (from `agent-browser install`) doesn't work.
+#AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium-browser

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Marsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+<p align="center">
+  <img src="discoclaw_splash.png" alt="DiscoClaw" width="700" />
+</p>
+
+# DiscoClaw
+
+A personal AI orchestrator that turns Discord into a persistent workspace — built on three pillars: **Memory**, **Tasks**, and **Crons**.
+
+DiscoClaw is an orchestrator: it coordinates between a user interface (Discord), one or more AI runtimes (Claude Code, OpenAI, Codex), and local system resources — managing conversation state, task routing, scheduling, and tool access. The intelligence is rented; the coordination is owned.
+
+It turns a private Discord server into a persistent AI workspace. Your assistant remembers you across sessions, tracks work in forum threads, and runs scheduled tasks autonomously — all through natural conversation.
+
+It's designed for a single user on a fresh, private server — your own sandbox. Not a shared bot, not a multi-user platform. Just you and your assistant in a space you control.
+
+No gateways, no proxies, no web UI to deploy — Discord *is* the interface. Run DiscoClaw on a Linux or macOS machine (see [Platform support](#platform-support)) and talk to your assistant from anywhere Discord works: desktop, mobile, browser.
+
+The codebase is intentionally small — small enough to read, audit, and modify directly. Customization means changing the code, not configuring a plugin system.
+
+## Why Discord?
+
+Discord gives you channels, forum threads, DMs, mobile access, and rich formatting for free. DiscoClaw maps its three core features onto Discord primitives so there's nothing extra to learn — channels become context boundaries, forum threads become task cards and job definitions, and conversation history is the raw material for memory.
+
+## Memory — the bot knows you
+
+Your assistant carries context across every conversation, channel, and restart.
+
+- **Durable facts** — `!memory remember prefers dark mode` persists across sessions and channels
+- **Rolling summaries** — Compresses earlier conversation so context carries forward, even across restarts
+- **Per-channel context** — Each channel gets a markdown file shaping behavior (formal in #work, casual in #random)
+- **Customizable identity** — Personality, name, and values defined in workspace files (`SOUL.md`, `IDENTITY.md`, etc.)
+- **Group chat aware** — Knows when to speak up and when to stay quiet in shared channels
+
+**Why Discord fits:** channels = context boundaries, DMs = private deep context, conversation history is the raw material.
+
+## Tasks — the bot tracks your work
+
+A lightweight in-process task store that syncs bidirectionally with Discord forum threads.
+
+- **Create from either side** — Ask your assistant in chat or use task commands
+- **Bidirectional sync** — Status, priority, and tags stay in sync between the task store and Discord threads
+- **Status emoji and auto-tagging** — Thread names show live status at a glance
+- **Discord actions** — Your assistant manages tasks through conversation: create channels, send messages, search history, run polls, and more
+
+**Why Discord fits:** forum threads = task cards, archive = done, thread names show live status.
+
+## Crons — the bot acts on its own
+
+Recurring tasks defined as forum threads in plain language — no crontab, no separate scheduler UI.
+
+- **Plain-language schedules** — "every weekday at 7am, check the weather and post to #general"
+- **Edit to change, archive to pause, unarchive to resume**
+- **Full workspace access** — File I/O, web search, browser automation, Discord actions
+- **Multi-turn sessions** — A live process persists between runs, so context carries across executions
+
+**Why Discord fits:** forum threads = job definitions, archive/unarchive = pause/resume, no separate scheduler UI needed.
+
+## How it works
+
+DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
+
+1. Checks the user allowlist (fail-closed — empty list means respond to nobody)
+2. Assembles context: per-channel rules, conversation history, rolling summary, and durable memory
+3. Routes to the appropriate runtime adapter, running in your workspace directory
+4. Streams the response back, chunked to fit Discord's message limits
+5. Parses and executes any Discord actions the assistant emitted
+
+### OpenRouter
+
+Set `PRIMARY_RUNTIME=openrouter` to route requests through [OpenRouter](https://openrouter.ai), which provides access to models from Anthropic, OpenAI, Google, and others via a single API key — useful if you want to switch models without managing multiple provider accounts.
+
+Required: `OPENROUTER_API_KEY`. Optional overrides: `OPENROUTER_BASE_URL` (default: `https://openrouter.ai/api/v1`) and `OPENROUTER_MODEL` (default: `anthropic/claude-sonnet-4`). See `.env.example` for the full reference.
+
+## Customization
+
+### Shareable integration recipes
+
+DiscoClaw supports a shareable markdown recipe format for passing integrations between users:
+
+- Spec: `docs/discoclaw-recipe-spec.md`
+- Template: `templates/recipes/integration.discoclaw-recipe.md`
+- Example files: `recipes/examples/*.discoclaw-recipe.md`
+- Skills:
+  - `skills/discoclaw-recipe-generator/SKILL.md`
+  - `skills/discoclaw-recipe-consumer/SKILL.md`
+- Install/refresh invocable skill symlinks:
+  - `pnpm claude:install-skills`
+
+Author one recipe file for an integration, share it, then let another user's DiscoClaw agent consume it and produce a local implementation checklist before coding.
+
+## Prerequisites
+
+**End users:**
+- **Node.js >=20** — check with `node --version`
+- One primary runtime:
+  - **Claude CLI** on your `PATH` — check with `claude --version` (see [Claude CLI docs](https://docs.anthropic.com/en/docs/claude-code) to install), or
+  - **Codex CLI** on your `PATH` — check with `codex --version`, or
+  - **OpenAI-compatible API key** via `OPENAI_API_KEY`, or
+  - **OpenRouter API key** via `OPENROUTER_API_KEY` (access to many providers)
+- Runtime-specific access for your chosen provider (Anthropic plan/API credits for Claude, OpenAI access for Codex/OpenAI models)
+
+**Contributors (from source):**
+- Everything above, plus **pnpm** — enable via Corepack (`corepack enable`) or install separately
+
+## Quick start
+
+### Discord setup (private server + bot)
+
+1. Create a **private Discord server** dedicated to DiscoClaw (not a shared/public server).
+2. In the [Discord Developer Portal](https://discord.com/developers/applications), create an application, then go to **Bot** -> **Add Bot**.
+3. Under **Bot** -> **Privileged Gateway Intents**, enable **Message Content Intent**.
+4. Copy the bot token and set it in `.env` as `DISCORD_TOKEN=...`.
+5. Invite the bot to your server:
+   - Go to **OAuth2** -> **URL Generator**
+   - Under **Scopes**, tick `bot`
+   - A **Bot Permissions** grid appears below. For a private server, tick `Administrator` (top-left, under General Permissions) — it's one checkbox and covers everything. For tighter permissions, see the [permission profiles](docs/discord-bot-setup.md#permission-profiles-choose-intentionally) in the full guide.
+   - Copy the generated URL at the bottom, open it, pick your server, and authorize
+6. In Discord, enable **Developer Mode** (User Settings -> Advanced), then copy IDs and set:
+   - `DISCORD_ALLOW_USER_IDS=<your user id>` (required; fail-closed if empty)
+   - `DISCORD_GUILD_ID=<server id>` (recommended; required for auto-creating forum channels)
+
+Full step-by-step guide: [docs/discord-bot-setup.md](docs/discord-bot-setup.md)
+
+### Install and run
+
+1. **Install globally:**
+   ```bash
+   npm install -g discoclaw
+   ```
+
+2. **Run the interactive setup wizard** (creates `.env` and scaffolds your workspace):
+   ```bash
+   discoclaw init
+   ```
+
+3. **Register the system service:**
+   ```bash
+   discoclaw install-daemon
+   ```
+
+#### From source (contributors)
+
+```bash
+git clone <repo-url> && cd discoclaw
+pnpm install
+pnpm setup            # guided interactive setup
+# Or manually: cp .env.example .env and fill in required vars:
+#   DISCORD_TOKEN
+#   DISCORD_ALLOW_USER_IDS
+# For all ~90 options: cp .env.example.full .env
+pnpm dev
+```
+
+## Updating
+
+**Global install:**
+
+```bash
+npm update -g discoclaw
+discoclaw install-daemon   # re-register the service after updating
+```
+
+**From source:**
+
+```bash
+git pull
+pnpm install
+pnpm build
+```
+
+Run `pnpm preflight` — it flags configuration options from `.env.example` that aren't in your `.env` yet.
+
+If running as a systemd service, restart it:
+
+```bash
+systemctl --user restart discoclaw.service
+```
+
+## Platform support
+
+- **All platforms** — `pnpm dev` works everywhere Node.js runs (Linux, macOS, Windows)
+- **Linux** — systemd service file provided for production deployment (see `.context/ops.md`)
+- **macOS / Windows** — use pm2, screen, or another process manager for long-running deployment; or just `pnpm dev` in a terminal
+
+> Windows is not tested for production use in v0.x. The session scanner has known path-handling issues on Windows, and the Claude CLI primarily targets Linux and macOS.
+
+## Safety
+
+DiscoClaw orchestrates powerful local tooling via AI runtimes, often with elevated permissions. Treat it like a local automation system connected to Discord.
+
+- Use a **private Discord server** — don't start in a shared or public server
+- Use **least-privilege** Discord permissions
+- Keep `DISCORD_ALLOW_USER_IDS` tight — this is the primary security boundary
+- Empty allowlist = respond to nobody (fail-closed)
+- Optionally restrict channels with `DISCORD_CHANNEL_IDS`
+- External content (Discord messages, web pages, files) is **data**, not instructions
+
+## Workspace layout
+
+The orchestrator runs AI runtimes in a separate working directory (`WORKSPACE_CWD`), keeping the repo clean while giving your assistant a persistent workspace.
+
+- Set `DISCOCLAW_DATA_DIR` to use `$DISCOCLAW_DATA_DIR/workspace` (good for Dropbox-backed setups)
+- Or leave it unset to use `./workspace` relative to the repo
+- Content (channel context, Discord config) defaults to `$DISCOCLAW_DATA_DIR/content`
+
+## Development
+
+```bash
+pnpm preflight  # preflight check (Node, pnpm, Claude CLI, .env)
+pnpm dev        # start dev mode
+pnpm build      # compile TypeScript
+pnpm test       # run tests
+```
+
+## Built with
+
+[Claude Code](https://claude.ai/claude-code), [OpenAI Codex](https://openai.com/index/openai-codex/), [discord.js](https://discord.js.org), and [Croner](https://github.com/hexagon/croner).
+
+## License
+
+[MIT](LICENSE). See [DISCLAIMER.md](DISCLAIMER.md) for important usage terms.

package/dist/beads/auto-tag.js

@@ -0,0 +1,2 @@
+import { autoTagTask, } from '../tasks/auto-tag.js';
+export const autoTagBead = autoTagTask;