huskies/website/app/docs/commands/page.tsx

/** Bot commands reference — full list of chat transport commands. */
import type { Metadata } from 'next'

/** Page metadata for the bot commands reference. */
export const metadata: Metadata = {
  title: 'Bot Commands — Huskies Docs',
  description:
    'Full reference of huskies bot commands available in Matrix, Slack, WhatsApp, Discord, and the web UI.',
}

/** Renders the full bot commands reference page. */
export default function CommandsPage() {
  return (
    <>
      <h1 className="page-title">Bot Commands</h1>
      <p className="page-subtitle">
        Commands available in every chat transport (Matrix, Slack, WhatsApp, Discord) and the built-in web
        UI. Commands are case-insensitive. Run <code>help</code> in any chat to see the list.
      </p>

      <div className="note">
        <strong>How to invoke:</strong> In chat rooms, address the bot first (e.g.{' '}
        <code>@huskies start 42</code>) or enable ambient mode so it responds to all messages. In the web
        UI, type commands directly.
      </div>

      <h2>Pipeline management</h2>
      <div className="cmd-grid">
        <div className="cmd-row">
          <div className="cmd-name">status</div>
          <div className="cmd-desc">
            Show pipeline status and agent availability. Use <code>status &lt;number&gt;</code> for a
            detailed triage dump on a specific story.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">start</div>
          <div className="cmd-desc">
            Start an agent on a story: <code>start &lt;number&gt;</code>. To use the opus model:{' '}
            <code>start &lt;number&gt; opus</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">move</div>
          <div className="cmd-desc">
            Move a work item to a pipeline stage: <code>move &lt;number&gt; &lt;stage&gt;</code>. Stages:{' '}
            <code>backlog</code>, <code>current</code>, <code>qa</code>, <code>merge</code>,{' '}
            <code>done</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">show</div>
          <div className="cmd-desc">
            Display the full text of a work item: <code>show &lt;number&gt;</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">delete</div>
          <div className="cmd-desc">
            Remove a work item from the pipeline: <code>delete &lt;number&gt;</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">unblock</div>
          <div className="cmd-desc">
            Reset a blocked story: <code>unblock &lt;number&gt;</code>. Clears the blocked flag and resets
            the retry count.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">assign</div>
          <div className="cmd-desc">
            Pre-assign a model to a story before starting: <code>assign &lt;number&gt; &lt;model&gt;</code>{' '}
            (e.g. <code>assign 42 opus</code>).
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">backlog</div>
          <div className="cmd-desc">
            Show all items in the backlog with dependency satisfaction status &mdash; which are ready to
            start and which are still waiting on other stories.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">depends</div>
          <div className="cmd-desc">
            Set story dependencies: <code>depends &lt;number&gt; [dep1 dep2 ...]</code>. Call with no deps
            to clear all dependencies.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">timer</div>
          <div className="cmd-desc">
            Schedule a deferred agent start: <code>timer &lt;number&gt; HH:MM</code>. List all timers:{' '}
            <code>timer list</code>. Cancel: <code>timer cancel &lt;number&gt;</code>. Times are interpreted
            in the project timezone.
          </div>
        </div>
      </div>

      <h2>Worktrees</h2>
      <div className="cmd-grid">
        <div className="cmd-row">
          <div className="cmd-name">rmtree</div>
          <div className="cmd-desc">
            Delete the worktree for a story without removing the story from the pipeline:{' '}
            <code>rmtree &lt;number&gt;</code>. Useful for freeing disk space on a story that needs to be
            restarted.
          </div>
        </div>
      </div>

      <h2>Observability</h2>
      <div className="cmd-grid">
        <div className="cmd-row">
          <div className="cmd-name">cost</div>
          <div className="cmd-desc">
            Show token spend: 24h total, top stories, breakdown by agent type, and all-time total.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">coverage</div>
          <div className="cmd-desc">
            Show test coverage from the cached baseline. Use <code>coverage run</code> to rerun the full
            test suite and regenerate the report.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">git</div>
          <div className="cmd-desc">
            Show git status for the main repository: current branch, uncommitted changes, and ahead/behind
            remote.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">htop</div>
          <div className="cmd-desc">
            Live system and agent process dashboard. Use <code>htop</code> to start,{' '}
            <code>htop 10m</code> to run for 10 minutes, <code>htop stop</code> to stop.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">run_tests</div>
          <div className="cmd-desc">
            Run the project&apos;s test suite (<code>script/test</code>) and show a pass/fail summary with
            output. Use <code>run_tests &lt;number&gt;</code> to run tests inside a specific story&apos;s
            worktree instead of the project root.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">loc</div>
          <div className="cmd-desc">
            Show top source files by line count: <code>loc</code> (top 10), <code>loc &lt;N&gt;</code> for
            N files, or <code>loc &lt;filepath&gt;</code> for a specific file.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">overview</div>
          <div className="cmd-desc">
            Show an implementation summary for a merged story: <code>overview &lt;number&gt;</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">unreleased</div>
          <div className="cmd-desc">
            Show stories merged to master since the last release tag.
          </div>
        </div>
      </div>

      <h2>Server management</h2>
      <div className="cmd-grid">
        <div className="cmd-row">
          <div className="cmd-name">rebuild</div>
          <div className="cmd-desc">Rebuild the huskies server binary and restart the process.</div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">reset</div>
          <div className="cmd-desc">
            Clear the current Claude Code session and start a fresh context window.
          </div>
        </div>
      </div>

      <h2>Setup &amp; configuration</h2>
      <div className="cmd-grid">
        <div className="cmd-row">
          <div className="cmd-name">setup</div>
          <div className="cmd-desc">
            Show setup wizard progress. Drive the wizard from chat: <code>setup generate</code>,{' '}
            <code>setup confirm</code>, <code>setup skip</code>, <code>setup retry</code>.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">ambient</div>
          <div className="cmd-desc">
            Toggle ambient mode for the current room: <code>ambient on</code> or{' '}
            <code>ambient off</code>. In ambient mode the bot responds to all messages, not just addressed
            ones.
          </div>
        </div>
        <div className="cmd-row">
          <div className="cmd-name">help</div>
          <div className="cmd-desc">Show the list of available commands.</div>
        </div>
      </div>
    </>
  )
}