### Create PostgreSQL Test Database and Extensions

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Create the 'agent_wiki_test' database and install necessary PostgreSQL extensions if they do not exist. This setup is required for the application's testing environment.

```bash
createdb agent_wiki_test
psql agent_wiki_test -c 'CREATE EXTENSION pg_textsearch;'
psql agent_wiki_test -c 'CREATE EXTENSION pgmq CASCADE;'
```

--------------------------------

### Install Agent Wiki

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/README.md

Installs Agent Wiki using a curl command to download and execute an installation script. This is a quick way to get started.

```bash
curl -fsSL https://raw.githubusercontent.com/onyx-dot-app/agent-wiki/main/install.sh | bash
```

--------------------------------

### Tool Setup Wizard (State B)

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

The second step of the tool setup wizard, displaying the status of each tool's MCP token, helper installation, and CLI detection. It provides actions for installation and confirmation.

```text
┌─── Set up your coding tools ─── step 2 of 2 ──┐
│ Claude Code                                    │
│   ✓ MCP API key (minted "claude-launcher")     │
│   ⚠ Launcher not installed on this machine     │
│        $ npm install -g @agentwiki/launcher    │
│        [Copy] [I've installed it →]            │
│                                                │
│ Codex                                          │
│   ✓ MCP API key (reused)                       │
│   ✓ Launcher detected                          │
│   ⚠ codex CLI not found in PATH                │
│        Install: https://github.com/openai/codex│
│        [Skip Codex] [I've installed it →]      │
│                                                │
│                          [Back]  [Done]        │
└────────────────────────────────────────────────┘
```

--------------------------------

### Install AgentWiki Launcher (Development)

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/packages/agentwiki-launcher-go/README.md

Build the launcher and set the endpoint URL for development purposes, then install it.

```bash
make build
./agentwiki-launcher set-endpoint http://127.0.0.1:8088
./agentwiki-launcher install
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Start the frontend development server with a specified backend URL and port. Verify the wiki loads correctly with no console errors.

```bash
cd /Users/nikolas/agent-wiki/frontend
BACKEND_URL=http://127.0.0.1:8088 npx next dev -p 3088
```

--------------------------------

### Setup Logging Once Per Process

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Install the formatter on the root logger exactly once per process using setup_logging() in process entry points. This ensures consistent log formatting and level control via the LOG_LEVEL environment variable.

```python
log = logging.getLogger(__name__)
# ... in entry point like app/main.py:create_app or app/tasks/run_worker.py:main
setup_logging()
```

--------------------------------

### Start Development Server

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Starts the Next.js development server with a specified backend URL. This command is used for local development and testing.

```bash
BACKEND_URL=http://127.0.0.1:8088 npx next dev -p 3088

```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Install frontend dependencies for the agent wiki project.

```bash
cd /Users/nikolas/agent-wiki/frontend
npm install
```

--------------------------------

### Install Backend Development Dependencies

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Ensure the backend development environment is set up correctly by syncing dependencies. This command uses 'uv' to install tools needed for linting and type checking.

```bash
uv sync --extra dev
```

--------------------------------

### Install and Build AgentWiki Launcher

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Commands to install npm dependencies and build the AgentWiki launcher package.

```bash
cd /Users/nikolas/agent-wiki/packages/agentwiki-launcher
npm install
npm run build
ls dist/
```

--------------------------------

### SetupWizard Component Implementation

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

The main SetupWizard component orchestrates the multi-step setup process. It manages the current step, selected tools, and state for helper and CLI probes. Use this component to initiate the agent setup flow.

```tsx
"use client";

import { useEffect, useState } from "react";

import { Button } from "@/components/common/Button";
import { color, radius } from "@/lib/theme";
import { LauncherCatalogEntry, probeCli, probeHelper } from "@/lib/launchers";

import { InstallHelperPane } from "./InstallHelperPane";
import { ToolStatusBadge } from "./ToolStatusBadge";

interface Props {
  catalog: LauncherCatalogEntry[];
  onDone: () => void;
  onCancel: () => void;
}

interface CliStatus {
  present: boolean;
  version: string | null;
  meets_min: boolean;
}

export function SetupWizard({ catalog, onDone, onCancel }: Props) {
  const [step, setStep] = useState<1 | 2>(1);
  const [selected, setSelected] = useState<Set<string>>(new Set());
  const [helperState, setHelperState] = useState<{ 
    acked: boolean;
    port: number | null;
  } | null>(null);
  const [cliState, setCliState] = useState<Record<string, CliStatus> | null>(
    null,
  );
  const [probing, setProbing] = useState(false);

  async function runProbes() {
    setProbing(true);
    try {
      const h = await probeHelper();
      setHelperState({ acked: h.acked, port: h.helperPort });
      if (h.acked && h.helperPort && selected.size > 0) {
        const ids = Array.from(selected).filter(
          (id) => catalog.find((c) => c.id === id)?.kind === "local_cli",
        );
        if (ids.length > 0) {
          const c = await probeCli(h.helperPort, ids);
          setCliState(c);
        }
      } else {
        setCliState({});
      }
    } finally {
      setProbing(false);
    }
  }

  useEffect(() => {
    if (step === 2) void runProbes();
  }, [step]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      {step === 1 && (
        <Step1
          catalog={catalog}
          selected={selected}
          onToggle={(id) => {
            const next = new Set(selected);
            if (next.has(id)) next.delete(id);
            else next.add(id);
            setSelected(next);
          }}
          onCancel={onCancel}
          onNext={() => setStep(2)}
        />
      )}
      {step === 2 && (
        <Step2
          catalog={catalog.filter((c) => selected.has(c.id))}
          helperState={helperState}
          cliState={cliState}
          probing={probing}
          onReprobe={runProbes}
          onBack={() => setStep(1)}
          onDone={onDone}
        />
      )}
    </div>
  );
}

function Step1({
  catalog,
  selected,
  onToggle,
  onCancel,
  onNext,
}: {
  catalog: LauncherCatalogEntry[];
  selected: Set<string>;
  onToggle: (id: string) => void;
  onCancel: () => void;
  onNext: () => void;
}) {
  return (
    <>
      <div style={{ fontSize: 14, color: color.text.primary, fontWeight: 600 }}>
        Pick which tools to set up — step 1 of 2
      </div>
      <div style={{ fontSize: 12, color: color.text.muted }}>
        You can add more later from the Agents page.
      </div>
      <ul
        style={{
          listStyle: "none",
          padding: 0,
          margin: 0,
          display: "flex",
          flexDirection: "column",
          gap: 8,
        }}
      >
        {catalog.map((c) => (
          <li key={c.id}>
            <label
              style={{
                display: "flex",
                alignItems: "center",
                gap: 10,
                padding: 10,
                border: `1px solid ${color.border.default}`,
                borderRadius: radius.sm,
                cursor: "pointer",
              }}
            >
              <input
                type="checkbox"
                checked={selected.has(c.id)}
                onChange={() => onToggle(c.id)}
              />
              <img src={c.icon_url} alt="" width={20} height={20} />
              <div style={{ flex: 1 }}>
                <div
                  style={{
                    fontSize: 14,
                    fontWeight: 600,
                    color: color.text.primary,
                  }}
                >
                  {c.name}
                </div>
                <div style={{ fontSize: 12, color: color.text.muted }}>
                  {c.tagline}
                </div>
              </div>
              <ToolStatusBadge
                status="muted"
                label={c.kind === "in_app" ? "in-app" : "terminal"}
              />
            </label>
          </li>
        ))}
      </ul>
      <div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
        <Button onClick={onCancel}>Cancel</Button>
        <Button
          variant="primary"
          onClick={onNext}
          disabled={selected.size === 0}
        >
          Next
        </Button>
      </div>
    </>
  );
}

function Step2({

```

--------------------------------

### Install Launcher Command

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

Command to install the agentwiki launcher globally using npm. This is part of the tool setup process when the launcher is not detected.

```bash
npm install -g @agentwiki/launcher
```

--------------------------------

### InstallHelperPane Component

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

A React component that guides the user to install the agent launcher, providing the installation command, a copy button, and an option to re-probe after installation.

```tsx
"use client";

import { useState } from "react";

import { Button } from "@/components/common/Button";
import { color, radius } from "@/lib/theme";

const INSTALL_CMD = "npm install -g @agentwiki/launcher";

export function InstallHelperPane({
  onReprobe,
}: {
  onReprobe: () => Promise<void> | void;
}) {
  const [copied, setCopied] = useState(false);
  const [busy, setBusy] = useState(false);

  async function copy() {
    try {
      await navigator.clipboard.writeText(INSTALL_CMD);
      setCopied(true);
      setTimeout(() => setCopied(false), 1500);
    } catch {
      setCopied(true);
      setTimeout(() => setCopied(false), 1500);
    }
  }

  async function reprobe() {
    setBusy(true);
    try {
      sessionStorage.removeItem("agentwiki:helper-probe");
      await onReprobe();
    } finally {
      setBusy(false);
    }
  }

  return (
    <div
      style={{
        padding: 12,
        background: color.state.warning.bg,
        border: `1px solid ${color.state.warning.border}`,
        borderRadius: radius.sm,
      }}
    >
      <div
        style={{ fontSize: 13, color: color.state.warning.fg, marginBottom: 8 }}
      >
        Launcher isn&apos;t installed on this machine. Run:
      </div>
      <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
        <code
          style={{
            flex: 1,
            padding: "6px 8px",
            background: color.bg.sunken,
            borderRadius: radius.xs,
            fontFamily: "ui-monospace, Menlo, monospace",
            fontSize: 12,
            color: color.text.primary,
          }}
        >
          {INSTALL_CMD}
        </code>
        <Button size="sm" onClick={copy}>
          {copied ? "Copied" : "Copy"}
        </Button>
      </div>
      <div
        style={{ marginTop: 10, display: "flex", justifyContent: "flex-end" }}
      >
        <Button size="sm" variant="primary" onClick={reprobe} disabled={busy}>
          {busy ? "Checking..." : "I've installed it"}
        </Button>
      </div>
    </div>
  );
}

```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Install Node.js dependencies for the frontend using 'bun'. This is a prerequisite for running frontend type checking and formatting tools.

```bash
bun install
```

--------------------------------

### Copy Manual Install Command Button

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Provides a button to copy the npm install command for the launcher to the user's clipboard. This serves as a fallback for users experiencing installation issues.

```tsx
<Button
  size="sm"
  variant="ghost"
  onClick={() =>
    navigator.clipboard.writeText("npm install -g @agentwiki/launcher")
  }
>
  Copy manual install command
</Button>
```

--------------------------------

### Initialize and Apply Terraform Configuration

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/deploy/terraform/README.md

Use these commands to copy the example variables file, customize it for your environment, and then initialize and apply your Terraform configuration.

```bash
cp example.tfvars terraform.tfvars  # edit for your env
terraform init
terraform apply
```

--------------------------------

### Start Backend Server

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

This bash command starts the backend Uvicorn server using a factory pattern for application creation, listening on host 127.0.0.1 and port 8088.

```bash
# Terminal A
cd /Users/nikolas/agent-wiki/backend && uv run --extra dev uvicorn --factory app.main:create_app --host 127.0.0.1 --port 8088
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Install pre-commit hooks for the project. This ensures code quality checks are performed automatically before each commit.

```bash
cd /Users/nikolas/agent-wiki && pre-commit install
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Run this command once after cloning the repository to install pre-commit hooks. These hooks ensure code quality by running checks similar to CI before each commit.

```bash
pre-commit install
```

--------------------------------

### TypeScript: Install AgentWiki.app on macOS

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

This TypeScript function handles the installation of the AgentWiki.app bundle to the user's Applications directory. It copies the bundle, ensures the stub binary is executable, and attempts to register the URI scheme with Launch Services.

```typescript
// src/install/darwin.ts
import { execSync } from "node:child_process";
import { cpSync, existsSync, mkdirSync } from "node:fs";
import { homedir } from "node:os";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";

export function installOnDarwin(): void {
  const here = dirname(fileURLToPath(import.meta.url));
  const src = join(here, "..", "..", "install", "AgentWiki.app");
  const dest = join(homedir(), "Applications", "AgentWiki.app");
  mkdirSync(dirname(dest), { recursive: true });
  cpSync(src, dest, { recursive: true });
  // Make sure stub is executable (cpSync may strip it on some FSes).
  execSync(
    `chmod +x "${join(dest, "Contents", "MacOS", "agentwiki-launcher-stub")}"`,
  );
  // Force Launch Services to re-scan the bundle.
  try {
    execSync(
      `/System/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f "${dest}"`,
    );
  } catch (e) {
    console.warn(
      "[agentwiki-launcher] lsregister failed; you may need to open the .app once manually.",
    );
  }
  console.log(`[agentwiki-launcher] installed ${dest}`);
}
```

--------------------------------

### Install Agent Wiki Helm Chart

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/deploy/README.md

Install or upgrade the Agent Wiki Helm chart into a specified namespace. Customize secrets, database connection, image tags, and ingress settings as needed.

```bash
helm upgrade --install agent-wiki ./deploy/helm/agent-workspace \
  --namespace agent-wiki --create-namespace \
  --set secretKey="$(openssl rand -hex 32)" \
  --set databaseUrl="postgresql://USER:PASSWORD@HOST:5432/DBNAME" \
  --set image.backend.tag=v0.0.1 \
  --set image.frontend.tag=v0.0.1 \
  --set ingress.host=<your-host> \
  --set ingress.clusterIssuer=letsencrypt-prod \
  --set ingress.tls.enabled=true
```

--------------------------------

### Linux Installation Script for URI Scheme Registration

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_4_cross_os_helper.md

Installs the AgentWiki launcher's desktop entry file and registers the custom URI scheme with the system. It creates the necessary directory, writes the `.desktop` file, and uses `update-desktop-database` and `xdg-mime` to apply the changes. Includes fallback instructions if registration fails.

```typescript
// src/install/linux.ts
import { execSync } from "node:child_process";
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

export function installOnLinux(): void {
  const dir = join(homedir(), ".local", "share", "applications");
  mkdirSync(dir, { recursive: true });
  const desktopPath = join(dir, "agentwiki-launcher.desktop");
  writeFileSync(
    desktopPath,
    [
      "[Desktop Entry]",
      "Name=AgentWiki Launcher",
      "Exec=/usr/local/bin/agentwiki-launcher run %u",
      "Type=Application",
      "NoDisplay=true",
      "MimeType=x-scheme-handler/agentwiki;",
      "",
    ].join("\n"),
  );
  try {
    execSync(`update-desktop-database "${dir}"`);
    execSync(
      `xdg-mime default agentwiki-launcher.desktop x-scheme-handler/agentwiki`,
    );
  } catch (e) {
    console.warn(
      "[agentwiki-launcher] xdg registration failed — run manually:",
    );
    console.warn(
      `  xdg-mime default agentwiki-launcher.desktop x-scheme-handler/agentwiki`,
    );
  }
}

```

--------------------------------

### Local Testing Commands for AgentWiki Launcher

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

These bash commands are used to build, package, and globally install the agentwiki-launcher package on a local macOS machine for testing purposes. It verifies the installation by checking for the application bundle and the global launcher executable.

```bash
cd /Users/nikolas/agent-wiki/packages/agentwiki-launcher
npm run build
npm pack
npm install -g ./agentwiki-launcher-0.1.0-alpha.1.tgz
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Starts the Next.js development server with a custom backend URL and port. Ensure you are in the correct project directory.

```bash
cd /Users/nikolas/agent-wiki/frontend && BACKEND_URL=http://127.0.0.1:8088 npx next dev -p 3088
```

--------------------------------

### Page Frontmatter Example

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

Example of markdown frontmatter for wiki pages, specifying linked repositories and a working directory hint.

```yaml
---
linked_repos:
  - git@github.com:onyx-dot-app/onyx
  - git@github.com:onyx-dot-app/agent-wiki
linked_working_dir_hint: "~/code/onyx" # display-only suggestion; per-user real value lives in page_working_dirs
---
```

--------------------------------

### SetupWizard React Component

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

The SetupWizard component renders the second step of the setup process, displaying the status of various agent launchers and providing navigation controls. It checks for token readiness, launcher detection, and CLI path configuration.

```typescript
function SetupWizard({
  catalog,
  helperState,
  cliState,
  probing,
  onReprobe,
  onBack,
  onDone,
}: {
  catalog: LauncherCatalogEntry[];
  helperState: { acked: boolean; port: number | null } | null;
  cliState: Record<string, CliStatus> | null;
  probing: boolean;
  onReprobe: () => Promise<void>;
  onBack: () => void;
  onDone: () => void;
}) {
  const allOk =
    !probing &&
    helperState?.acked &&
    catalog
      .filter((c) => c.kind === "local_cli")
      .every((c) => cliState?.[c.id]?.meets_min);

  return (
    <>
      <div style={{ fontSize: 14, color: color.text.primary, fontWeight: 600 }}>
        Setup checklist — step 2 of 2
      </div>
      <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
        {catalog.map((c) => (
          <div
            key={c.id}
            style={{
              padding: 12,
              border: `1px solid ${color.border.default}`,
              borderRadius: radius.sm,
            }}
          >
            <div
              style={{
                display: "flex",
                alignItems: "center",
                gap: 8,
                marginBottom: 6,
              }}
            >
              <img src={c.icon_url} alt="" width={20} height={20} />
              <strong style={{ fontSize: 14 }}>{c.name}</strong>
            </div>
            <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
              <ToolStatusBadge
                status={c.setup_status.token ? "ok" : "warn"}
                label={
                  c.setup_status.token
                    ? "Token ready"
                    : "Token will auto-mint on launch"
                }
              />
              {c.kind === "local_cli" && (
                <>
                  <ToolStatusBadge
                    status={helperState?.acked ? "ok" : "warn"}
                    label={
                      helperState?.acked
                        ? "Launcher detected"
                        : "Launcher not installed"
                    }
                  />
                  {helperState?.acked && cliState && (
                    <ToolStatusBadge
                      status={cliState[c.id]?.meets_min ? "ok" : "warn"}
                      label={
                        cliState[c.id]?.meets_min
                          ? `CLI ${cliState[c.id]?.version} ready`
                          : `${c.id} not in PATH`
                      }
                    />
                  )}
                </>
              )}
            </div>
          </div>
        ))}
        {!helperState?.acked && <InstallHelperPane onReprobe={onReprobe} />}
      </div>
      <div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
        <Button onClick={onBack}>Back</Button>
        <Button variant="primary" onClick={onDone} disabled={!allOk}>
          Done
        </Button>
      </div>
    </>
  );
}

```

--------------------------------

### Frontend Components for Agent Wiki

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

Lists new frontend components for agent setup, session display, and tool selection.

```text
frontend/src/
  components/
    wiki/
      RunAgentModal.tsx           rewrite from stub — wizard host
      ActiveSessionsList.tsx      file-viewer header widget
    agents/
      SetupWizard.tsx             multi-step (tool select → checklist)
      ToolCard.tsx                catalog row with setup status
```

--------------------------------

### Example Fix Command

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/backend/starter_templates/runbook.md

This is a placeholder for a command to fix a specific issue. Replace `<command>` with the actual command.

```bash
<command>
```

--------------------------------

### Sync Development Environment

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Synchronize the development environment using 'uv sync'. This ensures all project dependencies are correctly installed and configured.

```bash
cd /Users/nikolas/agent-wiki/backend
uv sync --extra dev
```

--------------------------------

### TypeScript: Post-install Script for Platform Detection

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

This script checks the operating system platform and calls the appropriate installation logic. For macOS, it imports and executes `installOnDarwin`. It includes basic error handling and messages for other platforms.

```typescript
// src/install/postinstall.ts
import { platform } from "node:process";

async function main() {
  try {
    if (platform === "darwin") {
      const { installOnDarwin } = await import("./darwin.js");
      installOnDarwin();
    } else if (platform === "linux") {
      console.log("[agentwiki-launcher] Linux install — Phase 4.");
    } else if (platform === "win32") {
      console.log("[agentwiki-launcher] Windows install — Phase 4.");
    }
  } catch (e) {
    console.warn("[agentwiki-launcher] postinstall failed:", e);
    console.warn(
      "Run `agentwiki-launcher` manually or see docs to register the URI scheme.",
    );
  }
}

await main();
```

--------------------------------

### Verify Codex CLI Installation

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_4_cross_os_helper.md

Check if the Codex CLI is installed and accessible in the system's PATH. If not, follow the provided installation guide.

```bash
which codex
codex --version
```

--------------------------------

### Handle Probe Acknowledgement with Live Port

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Parses a launch URI, starts the probe server to get a live port, and sends a probe acknowledgement back to the endpoint. It includes the nonce, helper port, and machine ID.

```typescript
async function handleProbeAck(uri: string): Promise<void> {
  const parsed = parseLaunchUri(uri);
  if (parsed.action !== "probe") throw new Error("expected probe action");
  const port = await startProbeServer();
  await fetch(new URL("/api/launch/probe-ack", parsed.endpoint).toString(), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      nonce: parsed.nonce,
      helper_port: port,
      machine_id: getOrCreateMachineId(), // AF#14 — frontend uses this for workdir defaulting
    }),
  });
}
```

--------------------------------

### Build and Run CLI Command

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Builds the agentwiki-launcher package and executes the 'run' command with a sample URI. This tests the end-to-end flow of argument parsing, machine ID creation, and the initial exchange process.

```bash
cd /Users/nikolas/agent-wiki/packages/agentwiki-launcher
npm run build
./bin/agentwiki-launcher run "agentwiki://run?code=fake&tool=claude-code&endpoint=http%3A%2F%2F127.0.0.1%3A8088"
```

--------------------------------

### GET /api/launchers

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Retrieves a catalog of available coding tool launchers. This endpoint is protected and requires user authentication. It returns a list of launchers, each with details such as ID, name, tagline, icon URL, kind, and setup status (including token availability). The endpoint is gated by a configuration flag `CONFIG.launchers_enabled` and will return a 404 if disabled.

```APIDOC
## GET /api/launchers

### Description
Retrieves a catalog of available coding tool launchers. This endpoint is protected and requires user authentication. It returns a list of launchers, each with details such as ID, name, tagline, icon URL, kind, and setup status (including token availability). The endpoint is gated by a configuration flag `CONFIG.launchers_enabled` and will return a 404 if disabled.

### Method
GET

### Endpoint
/api/launchers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **launchers** (array) - A list of LauncherCatalogEntry objects.
  - **id** (string) - The unique identifier for the launcher.
  - **name** (string) - The display name of the launcher.
  - **tagline** (string) - A short description of the launcher.
  - **icon_url** (string) - The URL for the launcher's icon.
  - **kind** (string) - The type or category of the launcher.
  - **setup_status** (object) - An object containing the setup status.
    - **token** (boolean) - Indicates if the user has a token for this launcher.

#### Response Example
```json
{
  "launchers": [
    {
      "id": "claude-code",
      "name": "Claude Code",
      "tagline": "AI assistant for code generation and review.",
      "icon_url": "/icons/claude-code.png",
      "kind": "ai_assistant",
      "setup_status": {
        "token": true
      }
    },
    {
      "id": "codex",
      "name": "Codex",
      "tagline": "AI pair programmer.",
      "icon_url": "/icons/codex.png",
      "kind": "ai_assistant",
      "setup_status": {
        "token": false
      }
    }
  ]
}
```

#### Error Response
- **401 Unauthorized**: If the user is not authenticated.
- **403 Forbidden**: If the user does not have permission.
- **404 Not Found**: If launchers are disabled via configuration.
```

--------------------------------

### Run Full Helper Test Suite

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Execute the test suite for the agent wiki launcher package. Includes running type checking and the main test command.

```bash
cd /Users/nikolas/agent-wiki/packages/agentwiki-launcher
npm run typecheck
npm test
```

--------------------------------

### Build AgentWiki Launcher

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/packages/agentwiki-launcher-go/README.md

Build the agentwiki-launcher for the local architecture or for distribution.

```bash
make build              # local arch
make dist               # darwin-arm64 + darwin-amd64
```

--------------------------------

### Create Launchers Package and Init File

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Creates the directory structure for the launchers package and an empty __init__.py file to mark it as a Python package.

```bash
mkdir -p /Users/nikolas/agent-wiki/backend/app/launchers
touch /Users/nikolas/agent-wiki/backend/app/launchers/__init__.py
```

--------------------------------

### Verify Claude Code CLI Installation

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Check if the `claude` command-line interface is installed and accessible in the system's PATH. This is a prerequisite for Phase 3.

```bash
which claude
claude --version
```

--------------------------------

### Example Filler Section for Decision Log

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/backend/wiki_seed/Setup.md

This example shows how to create a filler section in a wiki document. The wiki can automatically populate this section with decision logs over time.

```markdown
## Decision Log
Below is a list of all critical decisions made about the project and the timestamps for those decisions.

```

--------------------------------

### Task Queue Immediate Mode for Testing

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Shows how to use a context manager to run tasks synchronously for testing purposes, ensuring state is preserved.

```python
from queue import immediate_mode

# Assuming a task function exists, e.g., process_data
# def process_data(data):
#     # ... task logic ...
#     pass

# Example usage within a test:
# with immediate_mode():
#     process_data(some_data)
#     # Assert on side effects here
```

--------------------------------

### Encrypt/Decrypt Helper Module Initialization

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Initializes the `launcher_tokens.py` module, setting up the encryption key derivation function. This module will handle the encryption and decryption of launcher tokens.

```python
def _key() -> bytes:
    # Derive a 32-byte key from the app secret. SECRET_KEY is already
    # required at boot, so this can't be missing.
    import hashlib
    return hashlib.sha256(CONFIG.secret_key.encode("utf-8")).digest()
```

--------------------------------

### Codex Manifest JSON Example

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_4_cross_os_helper.md

An example JSON structure for the Codex CLI manifest. This should be updated to reflect the actual CLI's behavior regarding configuration, prompt delivery, and session handling.

```json
{
  "manifest_version": 1,
  "id": "codex",
  "name": "Codex",
  "tagline": "OpenAI's terminal coding agent.",
  "icon_url": "/icons/codex.svg",
  "kind": "local_cli",
  "cli_check": {
    "binary": "codex",
    "version_flag": "--version",
    "min_version": "<actual>",
    "install_hint_url": "https://github.com/openai/codex#install"
  },
  "mcp_config_format": "<claude_json or codex_toml or none — per actual support>",
  "first_turn_prompt_delivery": {
    "method": "<prompt_file_flag or stdin>",
    "flag": "<actual flag or null>"
  },
  "launch": {
    "binary": "codex",
    "argv": ["<real-flags-here>"],
    "env": {
      "AGENTWIKI_MCP_TOKEN": "${token}",
      "AGENTWIKI_SESSION_ID": "${session_id}"
    },
    "cwd": "${working_dir}"
  },
  "resume": {
    "binary": "codex",
    "argv": ["<real-resume-shape>"],
    "env": { "AGENTWIKI_MCP_TOKEN": "${token}" },
    "cwd": "${working_dir}"
  },
  "session_id_capture": {
    "source": "file_watch",
    "path": "<actual ~/.codex path>",
    "pattern": "<actual glob>",
    "extract": "filename_basename"
  }
}
```

--------------------------------

### Start Probe Server with Random Port

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_3_mac_helper.md

Starts an HTTP probe server on a random ephemeral port and persists the port number to a secure file for reuse. This prevents port collisions on multi-user machines.

```typescript
import { createServer } from "node:http";
import { writeFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";

export async function startProbeServer(): Promise<number> {
  const server = createServer(/* /probe-cli handler */);
  await new Promise<void>((resolve) =>
    server.listen(0, "127.0.0.1", resolve),
  );
  const port = (server.address() as { port: number }).port;
  writeFileSync(
    join(homedir(), ".agentwiki", "launcher.port"),
    String(port),
    { mode: 0o600 },
  );
  return port;
}
```

--------------------------------

### Agent Wiki Launcher CLI Entry Point

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

The main entry point for the Agent Wiki launcher Node.js CLI tool.

```text
packages/agentwiki-launcher/
  package.json
  bin/agentwiki-launcher          single Node CLI entry
```

--------------------------------

### Backend Testing with FastAPI TestClient

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/CLAUDE.md

Demonstrates how to set up and use FastAPI's TestClient for backend testing, including user authentication via a helper function.

```python
from fastapi.testclient import TestClient

# Assuming create_app() is defined elsewhere and returns a FastAPI app
# from app.main import create_app
# app = create_app()
# client = TestClient(app)

# Assuming login_fastapi is defined in tests/_auth.py
# from tests._auth import login_fastapi

# Example usage:
# def test_user_profile(client: TestClient, login_fastapi):
#     user_id = "test-user-123"
#     login_fastapi(client, user_id)
#     response = client.get("/api/users/me")
#     assert response.status_code == 200
#     assert response.json()["id"] == user_id
```

--------------------------------

### Check Agent Wiki Launcher Version

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_4_cross_os_helper.md

Verify the installed version of the @agentwiki/launcher package. Requires version 0.1.0-alpha.1 or higher.

```bash
npm view @agentwiki/launcher version
```

--------------------------------

### LauncherCatalogEntry Model

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Defines the structure for a single launcher in the catalog, including its ID, name, icon, kind, and setup status.

```python
class LauncherCatalogEntry(BaseModel):
    model_config = ConfigDict(frozen=True)

    id: str
    name: str
    tagline: str
    icon_url: str
    kind: Literal["local_cli", "in_app", "web_handoff"]
    setup_status: dict[str, Any]  # {token: bool, helper_seen_on_any_machine: bool}
```

--------------------------------

### Agent Wiki Launcher Spawn and Capture Modules

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/design.md

Handles binary spawning across different OS, including allow-list checks, and file watching for capture.

```text
packages/agentwiki-launcher/
  src/
    spawn.ts                      terminal-open + binary spawn per OS
                                  (allow-list check, then exec)
    capture/
      file_watch.ts               mtime-guarded directory watcher
      stdout_regex.ts             reserved adapter; not used in v1 by
                                  any shipped manifest (P1 #4)
```

--------------------------------

### Navigate to Agent Wiki Directory

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

Navigate to the agent wiki directory.

```bash
cd /Users/nikolas/agent-wiki
```

--------------------------------

### Get Agent Session by ID

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Retrieves an agent session by its session ID. Returns a dictionary representation or None if not found.

```python
def get(sid: str) -> dict[str, Any] | None:
    with session() as s:
        row = s.get(AgentSession, sid)
        return _to_dict(row) if row is not None else None
```

--------------------------------

### Apply Alembic Migration to Scratch Schema

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Command to run a Python script that initializes the database, applying the Alembic migration. This is used to verify the migration runs without errors.

```bash
cd /Users/nikolas/agent-wiki/backend
uv run --extra dev python -c "
from app.db.session import init_db
init_db()
print('migration applied')
"
```

--------------------------------

### Verify Backend Implementation

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Runs a Python command to verify the backend implementation by checking the import and instantiation of response models.

```bash
cd /Users/nikolas/agent-wiki/backend
uv run --extra dev python -c "from app.models.launchers import LaunchResponse, ExchangeResponse; print('ok')"
```

--------------------------------

### Get Raw Token for Token ID

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Retrieves the raw plaintext token given its ID. Returns None if the token is not found.

```python
def get_raw_for_token_id(mcp_token_id: str) -> str | None:
    with session() as s:
        row = s.get(LauncherToken, mcp_token_id)
        if row is None:
            return None
        return AESGCM(_key()).decrypt(row.nonce, row.ciphertext, None).decode("utf-8")
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Executes the entire test suite for the backend project. Use this to ensure no regressions were introduced by recent changes. The '-x' flag stops after the first failure.

```bash
cd /Users/nikolas/agent-wiki/backend
uv run --extra dev pytest -x
```

--------------------------------

### Start Lightweight Maintenance Worker

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

This bash command initiates a Python worker process for lightweight maintenance tasks within the backend directory.

```bash
# Terminal B
cd /Users/nikolas/agent-wiki/backend && uv run --extra dev python -m app.tasks.run_worker lightweight_maintenance
```

--------------------------------

### Commit SetupWizard Component Changes

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_2_frontend_wizard.md

These bash commands are used to stage and commit the changes made to the SetupWizard component in the frontend directory.

```bash
cd /Users/nikolas/agent-wiki/frontend && npm run typecheck
git -C /Users/nikolas/agent-wiki add frontend/src/components/agents/SetupWizard.tsx
git -C /Users/nikolas/agent-wiki commit -m "feat(launchers): SetupWizard component"
```

--------------------------------

### Get Manifest Registry Singleton

Source: https://github.com/onyx-dot-app/agent-wiki/blob/main/local_data/wiki/Wiki Project/Specific Features/coding_tool_launchers/implementation_plans/phase_1_backend.md

Provides a lazy singleton instance of ManifestRegistry. This defers the reading of the manifest directory until the registry is first used.

```python
_MANIFEST_DIR = Path(__file__).parent / "manifests"
_registry_singleton: ManifestRegistry | None = None

def get_registry() -> ManifestRegistry:
    """Lazy singleton — defers manifest dir read until first use so the
    test file can import the validator types without the manifest dir
    needing to exist yet."""
    global _registry_singleton
    if _registry_singleton is None:
        _registry_singleton = ManifestRegistry(_MANIFEST_DIR)
    return _registry_singleton
```