Inside Clawdbot: CLI Boot Sequence, Command Architecture, and the Terminal UI

export async function runCli(argv: string[] = process.argv) {
  const normalizedArgv = stripWindowsNodeExec(argv);
  loadDotEnv({ quiet: true });
  normalizeEnv();
  ensureClawdbotCliOnPath();
  assertSupportedRuntime();

  // Fast-path: route known commands without full program build
  if (await tryRouteCli(normalizedArgv)) return;

  enableConsoleCapture();

  const { buildProgram } = await import("./program.js");
  const program = buildProgram();

  installUnhandledRejectionHandler();

  const parseArgv = rewriteUpdateFlagArgv(normalizedArgv);
  const primary = getPrimaryCommand(parseArgv);
  if (primary) {
    const { registerSubCliByName } = await import("./program/register.subclis.js");
    await registerSubCliByName(program, primary);
  }

  if (!shouldSkipPluginRegistration) {
    const { registerPluginCliCommands } = await import("../plugins/cli.js");
    registerPluginCliCommands(program, loadConfig());
  }

  await program.parseAsync(parseArgv);
}

┌────────────────────────────────────────────────────┐
│                  clawdbot <args>                   │
└──────────────────────┬─────────────────────────────┘
                       │
         ┌─────────────▼──────────────┐
    1.   │  Environment Normalization  │
         │  .env, normalize, PATH     │
         └─────────────┬──────────────┘
                       │
         ┌─────────────▼──────────────┐
    2.   │  Runtime Guard              │
         │  assertSupportedRuntime()   │
         └─────────────┬──────────────┘
                       │
         ┌─────────────▼──────────────┐
    3.   │  Fast Route                 │──── hit ──→ execute & exit
         │  tryRouteCli()             │
         └─────────────┬──────────────┘
                       │ miss
         ┌─────────────▼──────────────┐
    4.   │  Console Capture            │
         │  Redirect to structured log │
         └─────────────┬──────────────┘
                       │
         ┌─────────────▼──────────────┐
    5.   │  Build Commander Program    │
         │  buildProgram()             │
         └─────────────┬──────────────┘
                       │
         ┌─────────────▼──────────────┐
    6.   │  Lazy Subcommand Loading    │
         │  registerSubCliByName()     │
         └─────────────┬──────────────┘
                       │
         ┌─────────────▼──────────────┐
    7.   │  Plugin CLI Registration    │
         │  Parse & Execute            │
         └─────────────────────────────┘

export async function tryRouteCli(argv: string[]): Promise<boolean> {
  if (isTruthyEnvValue(process.env.CLAWDBOT_DISABLE_ROUTE_FIRST)) return false;
  if (hasHelpOrVersion(argv)) return false;

  const path = getCommandPath(argv, 2);
  if (!path[0]) return false;
  const route = findRoutedCommand(path);
  if (!route) return false;
  await prepareRoutedCommand({ argv, commandPath: path, loadPlugins: route.loadPlugins });
  return route.run(argv);
}

// Extract positional commands: "clawdbot gateway status" → ["gateway", "status"]
export function getCommandPath(argv: string[], depth = 2): string[]

// Get the first command: "clawdbot gateway" → "gateway"
export function getPrimaryCommand(argv: string[]): string | null

// Flag presence and value extraction
export function hasFlag(argv: string[], name: string): boolean
export function getFlagValue(argv: string[], name: string): string | null | undefined
export function getPositiveIntFlagValue(argv: string[], name: string): number | null | undefined

export function buildProgram() {
  const program = new Command();
  const ctx = createProgramContext();
  const argv = process.argv;

  configureProgramHelp(program, ctx);
  registerPreActionHooks(program, ctx.programVersion);
  registerProgramCommands(program, ctx, argv);

  return program;
}

export type ProgramContext = {
  programVersion: string;
  channelOptions: string[];        // Available channel names
  messageChannelOptions: string;   // "whatsapp|telegram|discord|..."
  agentChannelOptions: string;     // "last|whatsapp|telegram|..."
};

░████░█░░░░░█████░█░░░█░███░░████░░████░░▀█▀
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░░█░█░░░█░░█░
█░░░░░█░░░░░█████░█░█░█░█░░█░████░░█░░░█░░█░
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░█░░█░░░█░░█░
░████░█████░█░░░█░░█░█░░███░░████░░░███░░░█░
              🦞 FRESH DAILY 🦞

program.configureHelp({
  optionTerm: (option) => theme.option(option.flags),
  subcommandTerm: (cmd) => theme.command(cmd.name()),
});

program.configureOutput({
  writeOut: (str) => {
    const colored = str
      .replace(/^Usage:/gm, theme.heading("Usage:"))
      .replace(/^Options:/gm, theme.heading("Options:"))
      .replace(/^Commands:/gm, theme.heading("Commands:"));
    process.stdout.write(colored);
  },
});

const entries: SubCliEntry[] = [
  {
    name: "gateway",
    description: "Gateway control",
    register: async (program) => {
      const mod = await import("../gateway-cli.js");
      mod.registerGatewayCli(program);
    },
  },
  // ... 25+ more entries
];

if (primary && shouldRegisterPrimaryOnly(argv)) {
  const entry = entries.find(candidate => candidate.name === primary);
  if (entry) {
    registerLazyCommand(program, entry);
    return;
  }
}

function registerLazyCommand(program: Command, entry: SubCliEntry) {
  const placeholder = program.command(entry.name).description(entry.description);
  placeholder.allowUnknownOption(true);
  placeholder.allowExcessArguments(true);
  placeholder.action(async (...actionArgs) => {
    // When invoked: remove placeholder, load real module, re-parse
    removeCommand(program, placeholder);
    await entry.register(program);
    const parseArgv = buildParseArgv({ programName, rawArgs, fallbackArgv });
    await program.parseAsync(parseArgv);
  });
}

┌────────────────────────────────────────────────────────────┐
│  clawdbot gateway status                                   │
│                                                            │
│  1. getPrimaryCommand(argv) → "gateway"                    │
│  2. Find SubCliEntry for "gateway"                         │
│  3. import("../gateway-cli.js")  ← only this module       │
│  4. registerGatewayCli(program)                            │
│  5. program.parseAsync(argv)     → gateway status action   │
│                                                            │
│  NOT loaded: browser, cron, nodes, memory, models,         │
│  sandbox, tui, channels, plugins, security, skills, ...    │
└────────────────────────────────────────────────────────────┘

.action(async (opts) => {
  await runCommandWithRuntime(defaultRuntime, async () => {
    await someCommand(opts, defaultRuntime);
  });
});

export function applyCliProfileEnv(params: {
  profile: string;
  env?: Record<string, string | undefined>;
  homedir?: () => string;
}) {
  env.CLAWDBOT_PROFILE = profile;
  env.CLAWDBOT_STATE_DIR = resolveProfileStateDir(profile, homedir);
  env.CLAWDBOT_CONFIG_PATH = path.join(stateDir, "clawdbot.json");
  if (profile === "dev") env.CLAWDBOT_GATEWAY_PORT = "19001";
}

# Production instance (default)
clawdbot gateway status

# Development instance — separate state dir, port 19001
clawdbot --dev gateway status

# Named profile — ~/.clawdbot-staging/
clawdbot --profile staging gateway status

export function getSlashCommands(options): SlashCommand[] {
  return [
    { name: "help",       description: "Show slash command help" },
    { name: "status",     description: "Show gateway status summary" },
    { name: "agent",      description: "Switch agent (or open picker)" },
    { name: "agents",     description: "Open agent picker" },
    { name: "session",    description: "Switch session (or open picker)" },
    { name: "sessions",   description: "Open session picker" },
    { name: "model",      description: "Set model (or open picker)" },
    { name: "models",     description: "Open model picker" },
    { name: "think",      description: "Set thinking level" },
    { name: "verbose",    description: "Set verbose on/off" },
    { name: "reasoning",  description: "Set reasoning on/off" },
    { name: "usage",      description: "Toggle per-response usage line" },
    { name: "elevated",   description: "Set elevated on/off/ask/full" },
    { name: "activation", description: "Set group activation" },
    { name: "abort",      description: "Abort active run" },
    { name: "new",        description: "Reset the session" },
    { name: "settings",   description: "Open settings" },
    { name: "exit",       description: "Exit the TUI" },
  ];
}

TUI (root)
├── Header (Text)
│   "clawdbot tui - ws://... - agent main - session main"
│
├── ChatLog (Container) ← scrollable message history
│   ├── UserMessageComponent
│   ├── AssistantMessageComponent  ← markdown-rendered
│   ├── ToolExecutionComponent     ← collapsible tool calls
│   └── Text (system messages)
│
├── StatusContainer
│   ├── Loader (spinning indicator during agent runs)
│   └── Text (idle status)
│
├── Footer (Text)
│   "agent main | session main | model | think off | tokens"
│
└── CustomEditor ← multi-line input with autocomplete

export async function runTui(opts: TuiOptions) {
  const config = loadConfig();
  const client = new GatewayChatClient({ url, token, password });
  const tui = new TUI(new ProcessTerminal());

  const header = new Text("", 1, 0);
  const chatLog = new ChatLog();
  const editor = new CustomEditor(tui, editorTheme);

  // Wire up input handling
  editor.onSubmit = createEditorSubmitHandler({
    editor, handleCommand, sendMessage, handleBangLine
  });
  editor.onEscape = () => void abortActive();
  editor.onCtrlC = () => { /* double-tap to exit */ };
  editor.onCtrlD = () => { process.exit(0) };
  editor.onCtrlO = () => { /* toggle tool expansion */ };
  editor.onCtrlL = () => { /* open model selector */ };
  editor.onCtrlG = () => { /* open agent selector */ };
  editor.onCtrlP = () => { /* open session selector */ };
  editor.onCtrlT = () => { /* toggle thinking display */ };

  // Gateway event handling
  client.onEvent = (evt) => {
    if (evt.event === "chat") handleChatEvent(evt.payload);
    if (evt.event === "agent") handleAgentEvent(evt.payload);
  };

  tui.start();
  client.start();
}

export function createEditorSubmitHandler(params) {
  return (text: string) => {
    const value = text.trim();
    if (!value) return;

    // 1. Bang mode: !command runs locally
    if (text.startsWith("!") && text !== "!") {
      params.handleBangLine(text);
      return;
    }

    // 2. Slash commands: /help, /model, /think, etc.
    if (value.startsWith("/")) {
      params.handleCommand(value);
      return;
    }

    // 3. Regular message: send to agent via gateway
    params.sendMessage(value);
  };
}

const runLocalShellLine = async (line: string) => {
  const cmd = line.slice(1);
  const allowed = await ensureLocalExecAllowed();
  if (!allowed) return;

  chatLog.addSystem(`[local] $ ${cmd}`);
  const child = spawn(cmd, { shell: true, cwd: getCwd(), env });
  child.on("close", (code) => {
    chatLog.addSystem(`[local] exit ${code ?? "?"}...`);
  });
};

export class TuiStreamAssembler {
  private runs = new Map<string, RunStreamState>();

  ingestDelta(runId, message, showThinking): string | null {
    // Accumulate thinking + content text separately
    // Compose display text based on showThinking flag
    // Return null if no visible change
  }

  finalize(runId, message, showThinking): string {
    // Produce final text, clean up run state
  }
}

export class GatewayChatClient {
  async sendChat(opts: ChatSendOptions): Promise<{ runId: string }>
  async abortChat(opts: { sessionKey, runId }): Promise<{ ok, aborted }>
  async loadHistory(opts: { sessionKey, limit? }): Promise<...>
  async listSessions(opts?): Promise<GatewaySessionList>
  async listAgents(): Promise<GatewayAgentsList>
  async patchSession(opts): Promise<...>
  async resetSession(key): Promise<...>
  async getStatus(): Promise<...>
  async listModels(): Promise<GatewayModelChoice[]>
}

const palette = {
  text: "#E8E3D5",       // Warm off-white
  dim: "#7B7F87",        // Gray
  accent: "#F6C453",     // Gold
  accentSoft: "#F2A65A", // Orange-gold
  border: "#3C414B",     // Dark gray
  userBg: "#2B2F36",     // Dark blue-gray
  systemText: "#9BA3B2", // Light gray
  toolTitle: "#F6C453",  // Gold
  success: "#7DD3A5",    // Green
  error: "#F97066",      // Red
};

export type WizardPrompter = {
  intro: (title: string) => Promise<void>;
  outro: (message: string) => Promise<void>;
  note: (message: string, title?: string) => Promise<void>;
  select: <T>(params: WizardSelectParams<T>) => Promise<T>;
  multiselect: <T>(params: WizardMultiSelectParams<T>) => Promise<T[]>;
  text: (params: WizardTextParams) => Promise<string>;
  confirm: (params: WizardConfirmParams) => Promise<boolean>;
  progress: (label: string) => WizardProgress;
};

export class WizardSession {
  async awaitAnswer(step: WizardStep): Promise<unknown>   // Push step, await answer
  async next(): Promise<WizardNextResult>                  // Get next step
  async answer(stepId: string, value: unknown): Promise<void>  // Provide answer
  cancel(): void
}

 1. Risk Acknowledgement     ── Security warning + confirm
 2. Flow Selection           ── QuickStart (auto) vs Manual (prompted)
 3. Existing Config          ── Keep / Update / Reset
 4. Mode Selection           ── Local gateway vs Remote
 5. Workspace Configuration  ── Set workspace dir (default: ~/clawd)
 6. Authentication Setup     ── Anthropic, OpenAI, OpenRouter, Gemini, etc.
 7. Model Selection          ── Choose default from available providers
 8. Gateway Configuration    ── Port, bind mode, auth mode, Tailscale
 9. Channel Setup            ── WhatsApp, Telegram, Discord, Slack, Signal
10. Skills Setup             ── Install skill packages
11. Internal Hooks           ── Session memory on /new
12. Finalization             ── Service install, health check, Control UI

export async function configureGatewayForOnboarding(opts) {
  // Port: keep existing or default 18789 (QuickStart), or prompt (Manual)
  // Bind: loopback / LAN / tailnet / auto / custom
  // Auth: token / password
  // Tailscale: off / serve / funnel
  // Constraints:
  //   Tailscale requires bind=loopback
  //   Funnel requires password auth
  //   Token auto-generated if blank
}

export const LOBSTER_PALETTE = {
  accent:       "#FF5A2D",   // Lobster red
  accentBright: "#FF7A3D",   // Light lobster
  accentDim:    "#D14A22",   // Dark lobster
  info:         "#FF8A5B",   // Warm orange
  success:      "#2FBF71",   // Green
  warn:         "#FFB020",   // Yellow-orange
  error:        "#E23D2D",   // Red
  muted:        "#8B7F77",   // Warm gray
};

┌──────────┬──────────┬────────┐
│ Column A │ Column B │ Status │
├──────────┼──────────┼────────┤
│ value    │ value    │ ok     │
└──────────┴──────────┴────────┘

export function createSafeStreamWriter(options?): SafeStreamWriter {
  // Catches EPIPE errors (e.g., when piped to `head`)
  // Marks stream as closed, notifies callback once
  // Subsequent writes silently return false
}

if (!shouldSkipPluginRegistration) {
  const { registerPluginCliCommands } = await import("../plugins/cli.js");
  registerPluginCliCommands(program, loadConfig());
}