# Grok Build Init

> Bootstrap grok-build with the karlorz subagent harness and companion plugins. Use when initializing grok-build on a new host.

- Skill: `karlorz/grok-build-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add karlorz/grok-build-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karlorz/grok-build-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: karlorz (https://skillmd.com/u/karlorz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karlorz/grok-build-init

---


# grok-build-init

Initialize grok-build (v1.0+) on a host with the karlorz subagent harness:
custom user-scope agents, global routing rules, the BYOK model/config layer,
and the companion plugin set. The skill runs `scripts/install.sh` from this
plugin; it is idempotent and backup-first.

## Prerequisites

- `python3` on PATH (installer scripts).
- `git` on PATH (marketplace clone), unless you pass `--skip-plugins`.
- `grok` installed, authenticated, and **runnable**: `grok --version` must succeed.
  On musl/Alpine, a glibc grokgod binary often cannot exec; use a musl grok
  (often `$GROK_HOME/downloads/grok-linux-*`) and do **not** leave PATH pointing
  at a broken grokgod shim. The installer will not rewrite that shim.
- On the fresh host, this plugin itself must be installed first:

  ```bash
  grok plugin marketplace add karlorz/agent-skills
  grok plugin install grok-build-harness --trust
  ```

  Then start a new session (or press `r` in the Plugins tab) and run
  `/grok-build-init`.

### Remote / SSH hosts

Do **not** allocate a TTY and run unknown `grok` words such as `grok whoami`.
Grok 1.0.x treats those as a chat turn and opens the TUI. Health checks:

```bash
grok --version
grok inspect --json
grok plugin list
```

Locate `install.sh` (below) and run it directly:

```bash
bash "$INSTALL" --hub-key "$HUB_KEY" --new-key "$NEW_KEY" --context7-key "$CTX7_KEY" --verify -y
```

## Locating install.sh

The installer ships with this plugin at `scripts/install.sh`. Resolve it from
the installed plugin root:

```bash
INSTALL="$(find ~/.grok/installed-plugins -maxdepth 3 -type f -name install.sh -path '*grok-build-harness*' | head -1)"
```

or from the agent-skills repo checkout: `skills/grok-build-harness/scripts/install.sh`.

## Procedure

1. **Update the plugin and locate installer**: On an existing install, refresh the plugin and find `install.sh`:

   ```bash
   grok plugin update grok-build-harness
   INSTALL="$(find ~/.grok/installed-plugins -maxdepth 3 -type f -name install.sh -path '*grok-build-harness*' | head -1)"
   ```

2. **Collect API keys from the user** (or read `HARNESS_HUB_KEY`,
   `HARNESS_NEW_KEY`, `HARNESS_CONTEXT7_KEY`). Two gateway keys
   (hub.karldigi.dev, new.karldigi.dev) and the context7 MCP key. If the user
   declines, install continues env-only — the generated config keeps
   `env_key` lines so `HUB_API_KEY` exports work.
3. **Run the installer** with the keys and any skip flags the user wants:

   ```bash
   bash "$INSTALL" --hub-key "$HUB_KEY" --new-key "$NEW_KEY" --context7-key "$CTX7_KEY" --verify
   ```

   Optional flags: `--skip-codex`, `--skip-vault-sync`, `--skip-playwright-cli`
   (heavy or host-specific plugins); `--require-keys` (hard-fail when hub/new
   gateway keys are missing — use for unattended runs); `--restrictive`
   (render `permission_mode = "plan"` instead of `"always-approve"` for
   shared hosts); `--with-grokgod` / `--skip-grokgod` (force or skip grokgod
   `[plan_mode] implement_via_subagents = true` merge; auto-detected by default);
   `--strict` (fail verify if config has unexpected top-level keys);
   `--force-render` (rewrite an existing keyed config env-only
   when no keys are provided — the default is to skip the config render
   instead, to avoid silently downgrading a working keyed config); `--dry-run`
   to preview without writing; `--no-config` to skip config.toml. When keys
   are missing the installer always warns that the config will be env-only
   (model aliases won't resolve until `HARNESS_HUB_KEY` / `HARNESS_NEW_KEY`
   are exported).
4. **Verify** (installer's `--verify` step): `grok plugin list --json` shows
   the 14 enabled plugins (13 companions + grok-build-harness itself), `grok inspect --json` reports agents discovered
   (asserts `grok-build-byok` with a path under `$GROK_HOME/agents/`; Grok 1.0.5
   may label that `source.type=project` and 1.0.12 `user` — type is ignored), stamp file is inspected,
   config does not pair `[agent] name = grok-build-byok` with `agent_type = "codex"`,
   schema-checks `config.toml` across template-owned, docs-known, and runtime extras layers
   (validating consent extra while protecting PII; fails on unexpected tables with `--strict`),
   and verifies no unresolved key tokens in config.toml.
5. **Finish**: tell the user to start a new session so `~/.grok/AGENTS.md` and
   the agents load. The skillwiki activation file (`~/.grok/skillwiki.md` and
   the `AGENTS.md` marker block) is owned by the llm-wiki plugin's
   `install:activation` — the harness installer preserves any existing marker;
   no manual step needed.

## What gets installed

| Path (under `~/.grok/`) | Content |
|---|---|
| `agents/grok-build-byok.md`, `agents/scout.md` | Custom parent agent + disposable read-only scout (verbatim) |
| `agentrules.md` | Global subagent routing/workflow rules (verbatim) |
| `AGENTS.md` | Subagent contract in a `<!-- grok-build-harness:begin/end -->` block — spliced in: all other content (user sections, skillwiki marker) is preserved |
| `config.toml` | Rendered from the sanitized template: model aliases (sonnet/haiku → deepseek-v4-flash-max via hub), `[subagents.models]` pins, `[subagents.toggle] grok-build-byok = false`, `[agent] name`, plugin enable list, context7 MCP |
| `.grok-build-harness-stamp.json` | Harness install stamp (`grok-build-harness-stamp/v1`): plugin version, root, install timestamp, and grokgod detection |

Existing files are backed up to
`~/.grok/backups/grok-build-harness-<timestamp>/` before overwrite; identical
files are skipped. Re-runs preserve host-set config keys the template does
not emit (`[plugins].disabled`, extra marketplace sources, extra tables),
and a re-run with no keys over a keyed config skips the render (use
`--force-render` to override).

## Troubleshooting

- **Harness rules not active** → confirm `~/.grok/AGENTS.md` + `agentrules.md`
  exist and start a new session.
- **Plugin skills missing** → `grok plugin list`; add the name to
  `[plugins].enabled` or press `Space` in the Plugins tab; reload with `r`.
- **Hooks/MCP servers inactive** → plugins were installed without trust;
  reinstall with `--trust` (`grok plugin uninstall <name> --confirm &&
  grok plugin install <name> --trust`).
- **Models don't resolve ("sonnet" unknown)** → the `[model.*]` aliases are
  missing or keys were not injected; re-run install.sh with keys, or export
  `HUB_API_KEY` / `NEW_API_KEY` (env_key fallback).
- **`grok --version` fails on Alpine/musl** → the grokgod/glibc binary cannot
  exec. Point `grok` at a musl build; do not rewrite the shim via this installer.
- **SSH session opened a grok TUI** → a TTY plus an unknown subcommand (e.g.
  `whoami`) is a chat turn. Use `install.sh` and `grok --version` / `inspect`.
- **Test without touching the host** →

  ```bash
  GROK_HOME=/tmp/grok-home bash "$INSTALL" --dry-run
  ```

  `GROK_HOME` relocates the whole grok tree; `grok inspect` against the scratch
  home validates the generated config safely.

## References

- Design and rationale: `docs/harness-design.md` in this plugin.
- Config semantics: `~/.grok/docs/user-guide/05-configuration.md`,
  `09-plugins.md`, `16-subagents.md`.