git:20260812.a9f50e1 to git:20260817.072dbb0

---

name: cgg-install

description: Install the `cgg` call-graph CLI on the user's machine. Trigger when the user says "install cgg", "set up cgg", "I don't have cgg", "how do I get cgg", or when another skill (like the `cgg` skill) reports `cgg` is not on PATH and the user wants it installed. Handles bootstrapping Rust via rustup if missing, the C toolchain check that tree-sitter grammars need, choosing between `cargo install cgg` from crates.io (end-user), a `--git` install for unreleased commits, and a clone-based dev install, PATH setup for `~/.cargo/bin`, and a post-install verification. Walks the user through each step rather than running long-running installs without confirmation.

---

C. Wall time is dominated by core count: ~25 s on a 64-core host,

several minutes on a laptop. Budget up to ~10 minutes and don't let

the user cancel a build that looks stalled on a `tree-sitter-*` crate.

## Prerequisites — check before installing

Run these checks first. **Do not start the install until every

prerequisite is green or the user has confirmed the bootstrap step.**

```bash

# 1. Rust toolchain (cargo + rustc >= 1.85, for the 2024 edition)

command -v cargo && cargo --version

command -v rustc && rustc --version

# 2. git — only needed for the --git or clone installs (3b/3c).

# `cargo install cgg` uses the sparse registry and does not need it.

command -v git && git --version

# 3. C toolchain — tree-sitter grammars compile C code

command -v cc || command -v gcc || command -v clang

```

The Rust check is the one most often missing. The C toolchain check

is the one most often missed *until* the build fails 4 minutes in

with a `linker 'cc' not found` error — check it up front.

## Step 1 — Install Rust if missing

If `cargo` is not on PATH, propose installing via rustup:

```bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

. "$HOME/.cargo/env"

```

**Stop and ask the user before running this** if they didn't already

explicitly opt in. It writes to `~/.cargo` and `~/.rustup`, modifies

shell rc files, and pulls down ~300 MB. Not something to do silently.

After installation:

- The user needs to either restart their shell or `source

$HOME/.cargo/env` so `cargo` is on PATH for the current session.

- Verify: `rustc --version` should report 1.85 or newer. If older,

run `rustup update stable`.

Windows: rustup has its own installer (`rustup-init.exe`) — point

the user to <https://rustup.rs> and pause.

## Step 2 — Install the C toolchain if missing

tree-sitter grammars are shipped as C source and compiled at install

time. If no C compiler is found:

- **Debian/Ubuntu:** `sudo apt install build-essential`

- **Fedora/RHEL:** `sudo dnf groupinstall "Development Tools"`

- **Arch:** `sudo pacman -S base-devel`

- **macOS:** `xcode-select --install` (CLT only; full Xcode not needed)

- **Windows:** install the "C++ build tools" workload of Visual Studio

Build Tools, or use the `gnu` Rust toolchain plus MSYS2's `gcc`.

Again, **stop and ask** before invoking `sudo`. The user may want to

run the package manager command themselves.

## Step 3 — Install cgg

Three install paths. Pick based on what the user wants:

### 3a. End-user install (recommended)

The user just wants the `cgg` binary on PATH. Install the released

crate from crates.io:

```bash

cargo install cgg --locked

```

Notes:

- `--locked` uses the `Cargo.lock` published inside the crate, for a

reproducible build. The published crate does contain one, so

`--locked` will not fail here.

- The binary lands in `~/.cargo/bin/cgg`.

- Re-running this command upgrades to the latest release.

- First-time build compiles 44 grammar crates. Don't cancel.

### 3b. Unreleased commits

Only if the user needs a fix that is on `main` but not yet released:

```bash

cargo install --git https://github.com/NeuralNotwerk/cgg --locked

```

The repo root is a virtual workspace, but `crates/cgg` is its only

package with a binary, so cargo resolves the target without needing

`--bin` or `-p`. Re-running upgrades to the latest commit on `main`.

### 3c. Developer install

The user wants a local clone (to read source, file PRs, run the

benchmark script, etc.).

```bash

git clone https://github.com/NeuralNotwerk/cgg.git

cd cgg

cargo install --path crates/cgg --locked

```

Same destination (`~/.cargo/bin/cgg`), but they keep the source tree

for `./scripts/benchmark.sh`, `./scripts/install-skill.sh`, and so on.

Note the path is `crates/cgg`, not `.` — the workspace root has no

package of its own.

## Step 4 — Verify PATH

If `cargo install` finishes but `cgg` is not found:

```bash

ls ~/.cargo/bin/cgg # should exist after install

echo $PATH | tr ':' '\n' | grep -F "$HOME/.cargo/bin"

```

If `~/.cargo/bin` isn't on PATH, the rustup installer normally adds a

line to the shell rc, but a restart may be needed. Permanent fix:

```bash

# bash

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

# zsh

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc

# fish

fish_add_path "$HOME/.cargo/bin"

```

Then `source` the rc file or open a new shell.

## Step 5 — Verify the install

```bash

cgg --help # should print usage

cgg --version # prints `cgg <version>`

```

For a real smoke test that needs no clone, build a two-function file

and check the edge comes back:

```bash

mkdir -p /tmp/cgg-smoke

printf 'def a():\n return b()\n\ndef b():\n return 1\n' > /tmp/cgg-smoke/t.py

cgg /tmp/cgg-smoke

```

Expected output, exactly:

```text

flowchart LR

C0["t.a"]

C1["t.b"]

C0 --> C1

```

If the user *does* have the source tree, run cgg against itself:

```bash

cgg ./crates --filter 'cgg::analyze_in_pool$' -n 1

```

A few dozen lines of mermaid means everything works.

## Step 6 — Offer to install the skills

If the user did the developer install (clone), there's a companion

script:

```bash

./scripts/install-skill.sh

```

It discovers every skill under `skills/*/SKILL.md` — currently `cgg`

(how to use it), `cgg-install` (this one) and `cgg-frameworks` (teaching

cgg a framework it doesn't recognise) — and installs them into Claude

Code, Kiro, Cline, Roo Code, and/or OpenCode if they're detected. Ask

before running it. `--only NAME` installs just one; `--dry-run` shows

what it would do.

## Common failures and fixes

| Symptom | Cause | Fix |

| --- | --- | --- |

| `error: linker 'cc' not found` | No C toolchain | Step 2 above |

| An error naming `requires rustc 1.85 or newer` | Rust too old (cgg is edition 2024) | `rustup update stable` |

| `error: could not find 'cgg' in registry` | Stale registry index | `cargo install cgg --locked` again; if it persists the user is behind a proxy/mirror that has not synced |

| Build hangs/fails on a `tree-sitter-*` crate | OOM on small machines (each grammar compile is RAM-heavy) | `cargo install ... -j 2` to limit parallelism |

| `cgg: command not found` after install | `~/.cargo/bin` not on PATH | Step 4 above |

| `error: failed to compile … tree-sitter-…` on Windows MSVC | Missing C++ build tools | Install VS Build Tools "C++ build tools" workload |

| `Permission denied` writing to `~/.cargo` | `~/.cargo` owned by root from a previous `sudo cargo` | `sudo chown -R "$USER" ~/.cargo ~/.rustup` |

## Things to NOT do

- **Don't `sudo cargo install`.** It installs into root's home and

leaves the user's `~/.cargo` perms broken. `cargo install` is meant

to run as the user.

- **Don't suggest a system package manager (`apt install cgg`, `brew

- **Don't try to half-install** by downloading individual files from

the repo or `cargo build`-ing a sibling crate like `cgg-lang` on its

own. Only `crates/cgg` produces the binary, and only cargo can pull

its dependency graph — installing it by hand is not a shortcut.

- **Don't run the install non-interactively** (no `< /dev/null`,

no piping `yes`). Build errors need to surface; the user may need

to make platform-specific decisions mid-install.

## Uninstall

```bash

cargo uninstall cgg

# and if they did the developer install:

rm -rf /path/to/cgg

```

`cargo install` does not pollute outside `~/.cargo/bin/cgg` and

`~/.cargo/registry/` cache.