Skillget

discoclaw

agent
SUMMARY

Discoclaw: CLI-first Discord bridge for agent runtimes

README.md

DiscoClaw

DiscoClaw

A personal AI orchestrator that turns Discord into a persistent workspace — built on three pillars: Memory, Tasks, and Automations.

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) 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
  • Cold storage — Semantic search over past conversations using vector embeddings + keyword search. Relevant history is automatically retrieved and injected into the prompt (see docs/memory.md)
  • 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.

YouTube transcripts

When you share a YouTube link in a message, DiscoClaw automatically fetches the video's transcript and injects it into the AI's context. This lets the bot answer questions about video content, summarize talks, or reference specific points — without you needing to copy-paste anything. Up to 3 videos per message are processed, with a 15-second timeout per fetch. Transcripts are sanitized before injection to prevent prompt manipulation.

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 (see docs/discord-actions.md)

Why Discord fits: forum threads = task cards, archive = done, thread names show live status.

Automations — 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.

For the managed Chrome/Chromium profile flow used by browser automation, see the managed browser launcher guide.

Voice — the bot talks back

DiscoClaw can join Discord voice channels for real-time conversation: listen via speech-to-text, think with the AI runtime, and speak the response via text-to-speech.

  • STT — Deepgram Nova-3 streaming transcription (WebSocket)
  • TTS — Cartesia Sonic-3 speech synthesis (WebSocket, 24 kHz PCM)
  • Barge-in — interrupt the bot mid-sentence by speaking; playback stops immediately
  • Auto-join — optionally join/leave channels automatically when you enter or leave
  • Transcript mirror — voice conversations are mirrored to a text channel for persistence
  • Voice actions — the AI can execute a restricted action subset (messaging, tasks, memory) during voice

Voice is off by default. Enable with DISCOCLAW_VOICE_ENABLED=1 plus API keys for your STT/TTS providers. Requires Node 22+ (for native WebSocket used by Cartesia TTS) and C++ build tools (for the @discordjs/opus native addon).

Full setup guide: docs/voice.md

How it works

DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with gemini-api, OpenAI, Codex, and OpenRouter adapters available via PRIMARY_RUNTIME). For 1.0, Claude CLI on a source checkout is the explicitly supported default path, and Codex CLI on a source checkout is the explicitly supported secondary path. See docs/audit/provider-auth-1.0-matrix.md for the full consolidated matrix. The OpenAI-compatible and OpenRouter adapters can expose optional tool use when OPENAI_COMPAT_TOOLS_ENABLED=1 is set, but OpenRouter support claims stop at the narrower audited boundary described below. 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

Instruction precedence

Prompt assembly has two layers, each with its own ordering contract.

Preamble precedence — the front of every prompt, in strict priority order:

  1. Immutable security policy (hard-coded root rules)
  2. Tracked defaults (runtime-injected from templates/instructions/SYSTEM_DEFAULTS.md)
  3. Tracked tools (runtime-injected from templates/instructions/TOOLS.md)
  4. User rules override (workspace/AGENTS.md)
  5. User tools override (workspace/TOOLS.md, optional)
  6. Memory/context layers (workspace identity files, channel context, durable/rolling memory, etc.)

Post-preamble section ordering — the sections between the preamble and the user message are arranged to exploit primacy bias (high-signal sections first) and recency bias (action schemas and constraints near the end, just before the user message). Low-signal data sections sit in the middle. See docs/prompt-ordering.md for the canonical order and rationale.

workspace/DISCOCLAW.md is no longer a managed or authoritative instruction source.
If you still have a legacy copy, treat it as historical reference only.

Message batching

When multiple messages arrive while the bot is thinking (i.e., an AI invocation is already active for that session), they're automatically combined into a single prompt rather than queued individually. This means rapid follow-up messages are processed together, giving the bot full context in one shot. Commands (!-prefixed messages) bypass batching and are always processed individually.

OpenRouter

Set PRIMARY_RUNTIME=openrouter to route requests through OpenRouter, which provides access to models from Anthropic, OpenAI, Google, and others via a single API key.

Required: OPENROUTER_API_KEY. Optional overrides: OPENROUTER_BASE_URL (default: https://openrouter.ai/api/v1), OPENROUTER_MODEL (default: anthropic/claude-sonnet-4.6), and OPENROUTER_PROVIDER_PREFERENCES (OpenRouter-only JSON routed through the request provider field). Treat .env presence, PRIMARY_RUNTIME=openrouter, and !models set chat openrouter as config/routing intent only until the running instance proves the shipped OpenRouter path with !status or the startup credential report showing openrouter-key: ok.

For source checkouts, workload evidence beyond that key-visibility proof exists only through the repo smoke path, and read-only tool coverage is the only validated tool subset today. DiscoClaw now ships built-in OpenRouter tier defaults: fast → openai/gpt-5-mini, capable → anthropic/claude-sonnet-4.6, deep → anthropic/claude-opus-4.6. Override them with DISCOCLAW_TIER_OPENROUTER_<TIER> only when you need instance-specific routing. See docs/audit/openrouter-api-key-support-boundary.md for the support boundary that npm installs and source checkouts both ship.

Model Overrides

The !models command lets you view and swap AI models per role at runtime — no restart needed. Per-role model values persist to models.json under the data dir, while fast/voice runtime overlays persist separately to runtime-overrides.json. Live runtime swaps like !models set chat openrouter are still live-only until the next restart, but they affect the main runtime path broadly, not just chat.

For the full operator guide to install-mode detection, persistent adapter switches, OpenRouter tier overrides, fast/voice runtime behavior, and !models reset semantics, see docs/runtime-switching.md.

Roles: chat, fast, forge-drafter, forge-auditor, summary, cron, cron-exec, voice

Command Description
!models Show current model assignments
!models set <role> <model> Change the model for a role
!models reset Revert all roles to startup defaults and clear overrides
!models reset <role> Revert a specific role to its startup default

Examples:

  • !models set chat claude-sonnet-4 — use Sonnet for chat
  • !models set chat openrouter — live-switch the main runtime to OpenRouter until restart
  • !models set cron-exec haiku — run crons on a cheaper model
  • !models set cron-exec default — clear the cron-exec override and use the startup default again
  • !models set voice sonnet — use a specific model for voice
  • !models reset — clear all overrides and revert to startup defaults

Setting chat to a runtime name (openrouter, openai, gemini-api, codex-cli, claude-cli) live-switches the main runtime path until restart; setting voice to a runtime name switches only voice. Legacy aliases (claude, codex, anthropic) are still accepted. Exact model-string runtime auto-switching is only implemented for fast and voice.

Secret Management

The !secret command lets you manage .env entries from Discord without touching the file directly. It works in DMs only — values are never echoed back.

Command Description
!secret set KEY=value Add or update a .env entry
!secret unset KEY Remove a .env entry
!secret list List key names in .env (values hidden)
!secret help Show usage

Changes take effect after a restart (!restart). Writes are atomic — a partial write can't corrupt your .env.

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.

MCP (Model Context Protocol)

When using the Claude runtime, you can connect external tool servers via MCP. Place a .mcp.json file in your workspace directory to configure servers — their tools become available during conversations. See docs/mcp.md for the config format, examples, and troubleshooting.

Managed browser launcher

Browser automation uses a Discoclaw-managed Chrome/Chromium profile directly. There is no companion service, long-lived helper daemon, or localhost control service to keep running in the background.

Use the launcher flow when you need a real browser profile for login-gated sites or later headless reuse:

  • discoclaw browser setup checks storage rules, browser discovery, and current managed-profile readiness
  • discoclaw browser launch opens the managed profile headed for one-time login and verifies CDP against that same browser instance
  • discoclaw browser launch --headless reuses the same verified profile later without opening a visible window
  • !browser help in Discord prints the same operator-facing setup, doctor, and launch commands

For source checkouts, repo-local managed browser storage is supported only at the ignored default data/browser/ path. Custom in-repo data dirs are refused for this feature; if you need a different browser data location, move DISCOCLAW_DATA_DIR outside the repo.

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 to install), or
    • Gemini API via PRIMARY_RUNTIME=gemini-api plus GEMINI_API_KEY, or
    • Codex CLI on your PATH — check with codex --version (binary presence only; session auth is a separate proof gate), or
    • OpenAI-compatible API key via OPENAI_API_KEY (config presence only; live auth is a separate proof gate), or
    • OpenRouter API key via OPENROUTER_API_KEY (config presence only until !status or the startup credential report shows openrouter-key: ok)
  • Runtime-specific access for your chosen provider (Anthropic access for Claude CLI, Google API access for gemini-api, OpenAI access for Codex/OpenAI models)

1.0 provider/auth policy: Claude CLI on a source checkout is the explicitly supported default path, and Codex CLI on a source checkout is the explicitly supported secondary path. For every current provider/auth path, including openai, openrouter, gemini-api, and direct Anthropic, use the consolidated verdicts in docs/audit/provider-auth-1.0-matrix.md rather than inferring readiness from setup/config alone.

discoclaw init scaffolds Claude CLI, Codex CLI, OpenAI, OpenRouter, and Gemini API runtime paths.

For Codex and OpenAI paths, treat binary/key presence as readiness prerequisites only. The install-mode-specific support claims live in the provider/auth 1.0 matrix, Codex source-checkout audit, and Codex npm-managed audit. For OpenRouter, the shipped support claim is narrower: docs/audit/openrouter-api-key-support-boundary.md documents only the runtime-visible env-key proof boundary, with source-checkout workload evidence limited to the repo smoke path.

Contributors (from source):

  • Everything above, plus pnpm — enable via Corepack (corepack enable) or install separately

Model capability requirement

DiscoClaw assumes reliable structured output for several runtime paths (for example: Discord actions, cron JSON routing, and tool-call loops).

  • For OpenAI-compatible and OpenRouter adapters, pick models that reliably support JSON-shaped output and function calling.
  • For OpenRouter-backed source-checkout workloads, treat repo smoke-path validation as the workload proof surface, and treat read-only tool coverage as the only validated tool subset today.
  • "OpenAI-compatible" API shape alone is not a capability guarantee.
  • If a model fails JSON/tool-call smoke tests, treat it as unsupported for DiscoClaw runtime use.
  • Use the model validation smoke test checklist before adopting a new model.

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, 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 Installation (left sidebar) → set Install Link to Discord Provided Link
    • Under Default Install Settings, add scope bot under Guild Install
    • A Permissions selector appears. For a private server, pick Administrator — it's one selection and covers everything. For tighter permissions, see the permission profiles in the full guide.
    • Save Changes, then open the install link, 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> (required for pnpm release:rehearsal; also required for auto-creating forum channels)

Full step-by-step guide: docs/discord-bot-setup.md

Documentation

Getting Started

Features & Usage

  • Memory system — five-layer memory architecture, tuning, and troubleshooting
  • Plan & Forge — autonomous planning and code generation
  • Discord actions — channels, messaging, moderation, tasks, crons
  • Cron / automations — recurring task setup, advanced options, debugging
  • Tasks — task lifecycle, bidirectional sync, tag maps
  • Voice — real-time voice chat setup (STT/TTS)
  • Shareable recipes — integration recipe format spec

Development

  • Philosophy — design principles and trade-offs
  • Releasing — npm publish workflow and versioning
  • Inventory — full component inventory and MVP status

Operations

Install and run

  1. Install globally:

    npm install -g discoclaw

    Fedora 43+ / GCC 14+ — @discordjs/opus build failure (resolved)

    This was fixed upstream in @discordjs/opus 0.10.0. If you are pinned to an older version, set the flag before installing:

    CFLAGS="-Wno-error=incompatible-pointer-types" npm install -g discoclaw

  2. Run the interactive setup wizard (creates .env and scaffolds your workspace):

    discoclaw init

  3. Register the system service:

    discoclaw install-daemon

    Optional: pass --service-name <name> to use a custom service name (useful on macOS when running multiple instances, or to match your own naming convention):

    discoclaw install-daemon --service-name personal

  4. Open the local operator dashboard:

    discoclaw dashboard

    By default this listens on 127.0.0.1. To reach it from a phone over Tailscale,
    set DISCOCLAW_DASHBOARD_TRUSTED_HOSTS to your tailnet IP or MagicDNS hostname.
    See docs/dashboard-tailscale.md.

If you are validating runtime auth, keep the install mode and auth method separate:

  • Claude: global installs use the npm-managed path (discoclaw init guidance plus discoclaw claude auth-smoke), while source checkouts use pnpm release:rehearsal for the blessed full-path rehearsal or collect the same gates manually in order with pnpm preflight:blank-machine, pnpm claude:auth-smoke, pnpm discord:smoke-test -- --guild-id <repo-local DISCORD_GUILD_ID>, and pnpm build.
  • Codex from source: pnpm preflight* is config-only; prove the Codex session separately with codex exec ..., and prove any OpenAI fast/alternate path separately with OPENAI_SMOKE_TEST_TIERS=... pnpm test.
  • Codex from npm/global install: discoclaw doctor is config-only and no shipped discoclaw codex auth-smoke exists yet; use the same-shell codex exec --skip-git-repo-check -- "Reply with OK" login check, then confirm openai-key: ok separately if you enabled an OpenAI fast/alternate path.

Current npm-managed blocker for both Claude and Codex daemon claims: discoclaw install-daemon still renders services with /usr/bin/node and a fixed service PATH. The interactive shell check can therefore pass while the installed daemon resolves different Node or runtime binaries.

From source (contributors)

git clone <repo-url> && cd discoclaw
pnpm install --frozen-lockfile
pnpm run setup        # guided interactive setup that writes a real clone-local .env
# 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 preflight:blank-machine
pnpm claude:auth-smoke  # if PRIMARY_RUNTIME=claude-cli, before login, from a shell/account with no active Claude session
claude                  # if PRIMARY_RUNTIME=claude-cli, complete login in that same shell/account
pnpm claude:auth-smoke  # if PRIMARY_RUNTIME=claude-cli, rerun after login in that same shell/account
pnpm release:rehearsal  # blessed Claude 1.0 source-checkout rehearsal; requires repo-local .env with PRIMARY_RUNTIME=claude-cli
codex exec -m gpt-5.4 --skip-git-repo-check --ephemeral -s read-only -- "Reply with OK"  # if PRIMARY_RUNTIME=codex-cli
OPENAI_SMOKE_TEST_TIERS=fast pnpm test  # if any source-checkout path routes through OpenAI
pnpm build && pnpm dev

Fresh clone is not enough evidence by itself for the Claude stranger path. A source checkout still needs a real clone-local .env, and the first-login claim only closes when the pre-login failure, interactive claude login, and post-login pnpm claude:auth-smoke rerun all happen in the same shell/account with no active Claude session. If the host shell was already logged into Claude, the passing smoke proves only the fresh-clone post-login path. When you want stranger-run evidence from a machine with existing DiscoClaw state, isolate DISCOCLAW_DATA_DIR, WORKSPACE_CWD, GROUPS_DIR, and BEADS_DIR to throwaway paths before you claim anything about the clone.

pnpm release:rehearsal is the blessed source-checkout entrypoint for the full Claude 1.0 operational rehearsal. Its source of truth is the checkout's own .env: the harness reads the repo-local file, requires PRIMARY_RUNTIME=claude-cli, strips repo-local persistence/config path overrides that would escape the rehearsal temp root, and then applies explicit child-process overrides for DISCOCLAW_DATA_DIR, WORKSPACE_CWD, GROUPS_DIR, BEADS_DIR, and the rehearsal task prefix. The live operator loop it holds includes the first reply, a same-conversation follow-up reply, task sync, cron execution, and restart/recovery. Fresh-clone and first-login stranger evidence are established separately by the fresh-clone QA and auth-smoke path above; the rehearsal harness accepts checkout provenance as operator context when supplied, but it does not try to prove or gate on that provenance in code.

If PRIMARY_RUNTIME=claude-cli, run pnpm preflight:blank-machine, capture the separate Claude auth evidence in the order shown above, then run pnpm discord:smoke-test -- --guild-id <repo-local DISCORD_GUILD_ID> and pnpm build before pnpm dev, or run the full pnpm release:rehearsal harness once the repo-local .env is ready. If PRIMARY_RUNTIME=codex-cli, treat pnpm preflight:blank-machine as config/bootstrap evidence only, then capture separate Codex session-auth evidence with the codex exec ... prompt. If any source-checkout route uses OpenAI, capture separate OPENAI_API_KEY evidence with OPENAI_SMOKE_TEST_TIERS=... pnpm test.

Claude runtime validation

Source-checkout 1.0 support status: SUPPORTED FOR 1.0 for the repo-owned Claude path within the audited boundary: the same no-session shell or account recorded the pre-login unauthenticated result, completed interactive Claude CLI login, and then passed the post-login pnpm claude:auth-smoke rerun. The current closeout memo is Claude source-checkout status, and the deeper audit record remains docs/audit/claude-blank-machine-readiness.md.

Npm-managed 1.0 audit verdict: NOT YET SUPPORT-CLAIMABLE. The installed CLI now has a shell-level Claude check, but the daemon path still is not claimable because discoclaw install-daemon hardcodes /usr/bin/node plus a fixed service PATH, and discoclaw init does not persist CLAUDE_BIN. See docs/audit/claude-npm-managed-path.md.

  1. Create a throwaway clone, run pnpm install --frozen-lockfile, and supply a real clone-local .env (pnpm run setup or copy from .env.example / .env.example.full).
  2. If you are validating from a machine that already has DiscoClaw or Claude state, isolate DISCOCLAW_DATA_DIR, WORKSPACE_CWD, GROUPS_DIR, and BEADS_DIR to throwaway paths before claiming stranger-run evidence.
  3. Run the automated config/bootstrap check:
    pnpm preflight:blank-machine
    Optional:
    pnpm preflight:blank-machine:online
  4. Treat the result correctly:
    • pnpm preflight:blank-machine proves the local prerequisites against the current .env only, ignoring inherited shell env from the host machine.
    • pnpm preflight:blank-machine:online adds a live Discord login/gateway-intent check on top of that same blank-machine env boundary.
    • Plain pnpm preflight keeps its broader contributor-oriented behavior and can still be useful for checking the current shell environment.
    • Neither command proves Claude login/auth state.
  5. From a shell or account with no active Claude session, run the required pre-login failure check:
    pnpm claude:auth-smoke
    Confirm it returns Claude CLI appears installed but not authenticated.
  6. Log in interactively in that same shell or account:
    claude
  7. Rerun the happy-path check in that same shell or account:
    pnpm claude:auth-smoke
    Confirm it returns Claude CLI answered the minimal prompt.
  8. If step 7 was captured only from an already-logged-in shell or account, record that limitation and downgrade the claim to fresh-clone post-login path only.
  9. For the full blessed source-checkout path, run the rehearsal harness and record whether the checkout was throwaway or reused:
    pnpm release:rehearsal
    The harness enforces the repo-local .env plus explicit child-process isolation overrides, writes a closeout under docs/release-audit/, and treats unresolved rehearsal-owned cleanup as a blocked verdict.
  10. Start DiscoClaw after the source-checkout gates pass:
pnpm build && pnpm dev

Codex runtime validation

Codex 1.0 support matrix:

Install mode Config/bootstrap evidence only Separate auth proof gates 1.0 verdict
Source checkout pnpm preflight:blank-machine / pnpm preflight prove local prerequisites only. They do not invoke Codex or OpenAI. 1. Prove the Codex CLI session in the same shell with codex exec -m gpt-5.4 --skip-git-repo-check --ephemeral -s read-only -- "Reply with OK" before and after codex login. 2. If any source-checkout path routes through OpenAI, run OPENAI_SMOKE_TEST_TIERS=fast pnpm test or replace fast with your intended tier/model. PASS for the repo-owned source path. See docs/audit/codex-blank-machine-readiness.md.
npm / global install discoclaw doctor, !doctor, and discoclaw init detection stay config-only. No shipped discoclaw codex auth-smoke exists yet. 1. Run codex exec --skip-git-repo-check -- "Reply with OK" before and after codex login in the same installed shell. 2. If you enabled an OpenAI fast/alternate path, start DiscoClaw and confirm !status or the startup credential report shows openai-key: ok. NOT YET SUPPORT-CLAIMABLE for the daemon path. See docs/audit/codex-npm-managed-path.md.

Do not treat codex --version, OPENAI_API_KEY presence, pnpm preflight*, or discoclaw doctor as full Codex readiness proof by themselves. Those are prerequisite/config surfaces only.

Updating

Global install:

If DiscoClaw is running, update from Discord:

!update apply

Or from the command line:

npm update -g discoclaw
discoclaw install-daemon   # re-register the service after updating
# If you used a custom service name, pass it again:
# discoclaw install-daemon --service-name personal

For Claude on npm-managed installs, keep using the installed-shell validation path after updates: rerun discoclaw init if you need the manual login guidance, and use discoclaw claude auth-smoke if you want the shipped shell-level smoke check. Do not treat pnpm preflight* or pnpm claude:auth-smoke as npm-managed evidence; those remain source-checkout-only. Re-registering the daemon also does not remove the current service-path blocker: the generated service still pins /usr/bin/node and a fixed PATH, so a passing interactive shell smoke test does not yet prove the daemon will resolve the same Node and Claude binaries.

For Codex on npm-managed installs, discoclaw doctor remains config-only and there is still no shipped discoclaw codex auth-smoke. Repeat the same-shell codex exec --skip-git-repo-check -- "Reply with OK" login check after updates, and if you enabled an OpenAI fast/alternate path confirm the restarted instance reports openai-key: ok. Re-registering the daemon still does not remove the service-path blocker: the generated service pins /usr/bin/node and a fixed PATH, and init does not persist CODEX_BIN, so interactive shell success is not yet daemon-proof.

From source:

git pull
pnpm install
pnpm build

Run pnpm preflight after changes to validate the automated contract again. It checks the local prerequisites Discoclaw can prove today: Node, pnpm, runtime binary presence/version, .env presence, env formatting, forum bootstrap eligibility, and config-doctor findings. It does not verify Codex session auth, OpenAI runtime auth, or Claude login/auth. Use pnpm preflight:blank-machine when you need the audit to ignore inherited shell env and inspect only the current .env, pnpm preflight:blank-machine:online if you also want a live Discord token/intents check, pnpm claude:auth-smoke for the Claude login/auth smoke step, and the Codex/OpenAI proof gates above for those runtime paths.

You can also run discoclaw doctor to inspect config drift and related issues, discoclaw doctor --fix to apply safe remediations, or use !doctor / !doctor fix from Discord (!health doctor / !health doctor fix remain supported). Restart the service afterward for fixed config to take effect.

For a local operator console, run discoclaw dashboard in the project directory. It shows the active service target, current model assignments, runtime overrides, config doctor status, and quick actions for status/logs/restart. It binds to 127.0.0.1 by default; configure DISCOCLAW_DASHBOARD_TRUSTED_HOSTS to allow Tailscale access via a tailnet IP or MagicDNS hostname while keeping Host-header checks in place for all other names. See docs/dashboard-tailscale.md.

Restart and recovery verification

Treat restart/recovery as a later closeout stage, not as a substitute for the source-checkout auth proof above. Record it only after the throwaway/source-checkout flow has already captured the correct Claude auth evidence and at least one normal reply. A clean restart from an already-authenticated shell does not retroactively prove the first-login stranger path.

If running as a systemd service, restart it:

systemctl --user restart discoclaw.service

Then verify the recovery path in order:

  1. Confirm the service is back:
    systemctl --user status discoclaw.service
  2. Inspect recent logs for a clean startup:
    journalctl --user -u discoclaw.service -n 50 --no-pager
  3. Send a short Discord message and confirm the already-validated runtime path answers normally after restart.
  4. If a long-running reply was interrupted by the restart and DISCOCLAW_COMPLETION_NOTIFY=1, confirm startup recovery posts either:
    • the persisted recovery summary text, or
    • a generic completion notice ending with Recovered after restart.
  5. Keep this evidence paired with the earlier Claude validation record; restart success does not close the separate first-login stranger gate by itself.

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

pnpm preflight         # automated prerequisite check; Claude auth remains manual
pnpm preflight:blank-machine         # same check, but ignore inherited shell env and use only .env
pnpm preflight:online  # adds live Discord login/intents validation
pnpm preflight:blank-machine:online  # blank-machine check plus live Discord login/intents validation
pnpm claude:auth-smoke # Claude CLI login/auth smoke check
pnpm release:rehearsal # full Claude source-checkout release rehearsal
pnpm dev        # start dev mode
pnpm build      # compile TypeScript
pnpm test       # run tests

Built with

Claude Code, OpenAI Codex, discord.js, and Croner.

License

MIT. See DISCLAIMER.md for important usage terms.

Yorumlar (0)

Sonuc bulunamadi