Instalacao¶

Esta pagina e a fonte unica de instrucoes de instalacao. O conteudo abaixo e includido literalmente do README.md da raiz do repositorio — qualquer atualizacao no README aparece aqui no proximo build CI (FR-005).

Pre-requisitos¶

bash ou sh POSIX (Linux, macOS, WSL).
curl no PATH para o one-liner de bootstrap.
tar e sha256sum (ou shasum -a 256 no macOS) para validar a release.
git se voce planeja contribuir. Nao ha dependencia de Node, Python ou Docker para o cstk em si.
jq e opcional — habilita merge de settings.json em escopo de projeto.

Conteudo canonico (do README)¶

Installation¶

Via cstk CLI (recommended)¶

The toolkit is installed via cstk — a POSIX shell CLI that downloads, validates (SHA-256), installs and updates skills without requiring a clone of the repository.

Bootstrap one-liner (installs cstk into ~/.local/bin/):

curl -fsSL https://github.com/JotJunior/cstk/releases/latest/download/install.sh | sh

After that, typical commands:

cstk --version                       # confirms installation
cstk install                         # installs the 'sdd' profile into ~/.claude/skills/
cstk install --profile all           # installs ALL 28 skills (includes language-go)
cstk install advisor bugfix          # cherry-pick by name
cstk update                          # applies new releases preserving local edits
cstk update --force                  # overwrites locally edited skills
cstk list                            # lists installed skills + status
cstk doctor                          # detects drift between manifest and disk
cstk self-update                     # updates the cstk binary itself + cli/lib

install/update touch only the catalog (skills/commands/agents in ~/.claude/); the runtime (cli/lib/*.sh + binary) updates via cstk self-update.

Available profiles:

Profile	Content	Typical use
`sdd`	17 skills: complete Spec-Driven Development pipeline (briefing → review-features) + internal runtime, model-selector and the orchestrators' 4 quality gates	Default global installation
`complementary`	10 independent skills (advisor, bugfix, e2e-integration-flow, etc.)	Complements the SDD pipeline
`all`	All 28 skills (sdd + complementary + language-go)	Full installation
`language-go`	Go-specific skills + hooks	Only in Go projects

Default profile when none is given: sdd.

Project scope (./.claude/skills/ in the CWD instead of ~/.claude/skills/):

# In a Go project: installs skills + hooks + settings.json merge
cd ~/projects/my-go-app
cstk install --scope project --profile language-go

# Cherry-pick in project scope
cstk install --scope project advisor owasp-security

# language-* hooks ARE installed only in --scope project
# (in --scope global, hooks are omitted with a warning in the summary — FR-009c)

Via Claude Code plugin (native, no binary)¶

Since v6.9.0 the catalog is also distributable as a native Claude Code plugin — no cstk binary, no clone, no curl bootstrap:

/plugin marketplace add JotJunior/cstk
/plugin install cstk@cstk
# optional, Go projects only:
/plugin install cstk-language-go@cstk

Enable the plugin and open a new session in any project — skills, the 7 /agente-00c*//feature-00c*//roadmap-wave commands and the enforced guard hooks (pretooluse-bash-guard, posttooluse-tool-call-tick, posttooluse-agent-usage) activate automatically, with no cstk hooks install step (confirmed empirically — see docs/specs/_archived/2026-08-08-claude-plugin-packaging/spec.md §Clarifications, assumption A1). posttooluse-loose-usage.sh (opt-in consumption capture) is deliberately not part of the plugin's hooks.json — it stays an explicit opt-in via cstk hooks install --with-loose-usage, and it also needs CSTK_OTEL_ENDPOINT in the claude process environment or it captures nothing (docs/cstk-usage.md).

Choosing between the two paths:

	Classic (`cstk` CLI)	Plugin (native)
Install step	bootstrap one-liner + `cstk install`	`/plugin marketplace add` + `/plugin install`
Provides the `cstk` binary (`recall`, `usage`, `mcp`, `session`, `serve`, `self-update`)	Yes	No — the plugin format does not install a persistent binary on `PATH` (FR-006); use the classic bootstrap for these
`cstk-state` MCP server (the 7 state tools)	Mirrored to `~/.claude/mcp/state-server` by `cstk install`; registered per project with `cstk mcp install`	Ships inside the plugin and is registered by its own `.mcp.json` — auto-starts, no per-project step
Guard hooks activation	Requires `cstk hooks install` per project	Automatic on session start, zero per-project step
Integrity verification	SHA-256 of the tarball, fail-closed (`serve-integrity`), fixed trusted-host allowlist	Commit pin (`gitCommitSha`) recorded by the harness + its own "Will install" trust dialog
Update propagation	`cstk update` (explicit, per invocation)	Not automatic: `claude plugin marketplace update` then `claude plugin update cstk --scope <scope>`, plus a session restart — the plugin CLI itself prints `Restart to apply changes.`

Both paths are equally official (no third, ungoverned distribution mechanism — see FR-017 in docs/specs/current/guards-defense-in-depth.md) and deliver the same auditable content with comparable protection, not identical mechanisms — pick the plugin for the fastest zero-binary onboarding of skills + guard hooks, the classic CLI when you need recall/usage/mcp/session/serve, or both together: cstk doctor/cstk hooks install detect the plugin and automatically avoid double-registering the guard hooks (plugin wins; cstk doctor reports aligned/diverged/duplicated-hooks with an actionable fix for each).

00c runtime hooks (`cstk hooks`)¶

The three 00c runtime hooks — pretooluse-bash-guard.sh (fail-closed Bash guard), posttooluse-tool-call-tick.sh and posttooluse-agent-usage.sh (per-wave metrics) — only run in a target project once they are copied into .claude/hooks/ and registered in .claude/settings.json.

cstk install --scope project agente-00c-runtime does that, but it also copies the skill, 7 commands and 7 agents into the repo. When you only want the hooks, use:

cd ~/projects/my-target-project
cstk hooks install                    # touches .claude/hooks/ + settings.json only
cstk hooks install --dry-run          # show the plan without writing
cstk hooks install --project-path ../other-project
cstk hooks install --remove-classic   # de-duplicate against the plugin, no prompt
cstk hooks install --local            # register in settings.local.json (third-party repos)
cstk hooks status                     # read-only: where is each hook registered?

Third-party repos (--local, issue #135): when the client's team versions .claude/settings.json on purpose, a personal tool has no business in it. --local writes the registration to .claude/settings.local.json instead — Claude Code sums hooks across scopes, and the local file is normally gitignored — so the hooks fire only for you and the team's file stays byte-for-byte untouched. The scripts still land in .claude/hooks/; keep them out of the client's git status without touching their .gitignore:

printf '.claude/hooks/\n.claude/settings.local.json\n.claude/*.bak\n.claude/*.bak-pre-dedup\n' >> .git/info/exclude

The two .bak patterns cover the backups the command itself writes — settings.json.bak / settings.local.json.bak when it merges the registration, and settings.json.bak-pre-dedup when it removes a duplicate classic block. Without them the backup shows up in the client's git status and rides along in a distracted git add -A (issue #163).

Idempotent like the default flow. If the other file already registers the 00c hooks (both would fire, double-counting every tool call) the command warns and offers the same removal as the plugin dedup (--remove-classic skips the prompt). cstk hooks status and guard-hooks-status.sh check read both files, so tick-mode keeps answering hook and the orchestrator does not tick by hand on top of an active hook.

When the plugin already provides the hooks, cstk hooks install skips the classic provisioning (plugin wins) and, if the project still carries a classic registration in settings.json, both layers would fire. In that case it asks whether to remove the classic block, deleting only the 00c hook entries — third-party hooks and every other key in the file are preserved — and writing a backup to settings.json.bak-pre-dedup. Use --remove-classic to skip the prompt (scripts/CI). Without a TTY and without the flag the block is kept, with a warning: settings.json belongs to the operator and is never rewritten without explicit consent.

Without this step the Bash guard is inert and tool_calls/agent_usage stay at zero for every wave. To check the current state without writing anything:

guard-hooks-status.sh check --projeto-alvo-path .
# <hook>  present|missing  registered|unregistered  current|stale|unknown

Re-run cstk hooks install after every cstk upgrade that touches the hooks: the copies under .claude/hooks/ are snapshots and nothing reconciles them with the catalog. A stale copy is as harmful as a missing one — it runs an older ruleset. That is a real regression, not a hypothetical: after the state.json → state.db cutover, projects kept a tick hook that only knew how to read state.json, so tool_calls was 0 for every wave while the check still reported "3/3 hooks active". The fourth column exists to make that visible, and tick-mode falls back to manual in exactly that pairing (backend-blind copy + state.db) so the metric survives until you re-provision.

Real per-wave cost (`otel-usage.sh`)¶

Claude Code's native OpenTelemetry counters are incremented on every API request and carry a query_source label (main / subagent / auxiliary). A snapshot at wave start and another at wave end gives the exact consumption of that wave — including the orchestrator's own spend, which the spawn hook can never capture (the orchestrator's spawn encloses the wave, so its tool_result arrives after the wave is already closed).

Opt in with two environment variables — no API key, no Admin key, no organization; works on subscription plans:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

state-ondas.sh start/end then populate .waves[N].otel_usage automatically. Without the variables everything is a no-op and the field is null — absent, never a fabricated zero.

Measured on a delegated task: main $0.156, subagent $0.141, auxiliary $0.001 — the subagent was ~47% of the spend, exactly the slice the panel used to show as —.

The exporter binds 127.0.0.1:9464; nothing leaves the machine. Identity labels (user_email, user_id, user_account_*, organization_id) are stripped at snapshot time and never reach disk. Override the endpoint with CSTK_OTEL_ENDPOINT if you changed the exporter port.

Multiple Claude Code processes at once? Give each one its own port. Only ONE process can bind the fixed port 9464 — the first one launched wins. Every other process (another terminal tab, another project) fails the bind silently: its metrics are exposed nowhere, the per-wave snapshots scrape the winner's stale sessions, and the delta guard correctly discards the result — so otel_usage comes out null for every wave of that execution, with the panel showing no cost at all. Real case: a two-day-old claude -c from an unrelated project held the port and an entire 16-wave run measured nothing.

The fix is a launcher function in your ~/.zshrc (or ~/.bashrc) that asks the OS for a free port at every launch (binding port 0 lets the kernel pick) and points the cstk scraper at it via CSTK_OTEL_ENDPOINT — hooks and runtime scripts run inside the Claude process, so they inherit both variables.

Since v6.9.0 you rarely need to do this by hand: cstk install offers this wrapper as an opt-in on first install (writes it to your shell rc between # >>> cstk telemetry >>> markers, only with explicit consent — never in non-interactive environments), and cstk help telemetry prints the canonical ready-to-paste block if you declined or want to set it up later.

# One OTel exporter per claude process: OS picks a free port at each launch.
claude() {
  local _otel_port
  _otel_port=$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1",0)); print(s.getsockname()[1]); s.close()' 2>/dev/null)
  if [ -n "$_otel_port" ]; then
    OTEL_EXPORTER_PROMETHEUS_PORT=$_otel_port \
    CSTK_OTEL_ENDPOINT="http://127.0.0.1:${_otel_port}/metrics" \
    command claude "$@"
  else
    command claude "$@"   # no python3: fall back to the fixed default port
  fi
}

The wrapper is also a hard requirement for loose-usage capture (cstk usage, issue #162), not just a multi-process convenience: posttooluse-loose-usage.sh gates on CSTK_OTEL_ENDPOINT and exits 0 in silence without it. Unlike the per-wave path — which falls back to the fixed default port — loose capture has no fallback, so without the variable (or an equivalent manual export) it stays inert and cstk usage answers nao medido. See docs/cstk-usage.md.

Zero per-session configuration: each claude you type gets an isolated exporter and an isolated measurement. As a bonus, the delta's "exactly-one-session-grew" guard only ever sees that process's sessions, so ambiguity discards (null from concurrent sessions) all but disappear.

The wrapper only covers claude TYPED in your shell. It is a shell function, and exec never resolves one — so until v9.4.0 every session started by cstk session start --claude, cstk 00c or the roadmap's parallel wave ran with no telemetry at all, which is exactly what issue #168 measured. Since v9.4.0 those three launchers set the variables themselves (one drawn port per process), so they no longer depend on your rc, your shell or tmux — and neither does the native-plugin install, which provisions no wrapper. Turn that off with CSTK_TELEMETRY_AUTO=0; an explicit CSTK_OTEL_ENDPOINT or CLAUDE_CODE_ENABLE_TELEMETRY already in the environment also wins. Anything launched outside both paths (IDE, desktop app) still uses the fixed default port.

Quick diagnosis when the panel shows no cost for any wave: check who owns the port and whether its working directory is the project you're actually running:

lsof -nP -iTCP:9464 -sTCP:LISTEN     # who owns the exporter port?
lsof -p <PID> | grep cwd             # ...and from which project?

Or let the runtime decide: otel-usage.sh preflight answers "will THIS session be measured?" deterministically — status=ok (exporter owned by an ancestor of this process), port-conflict with the owner's PID and cwd (exit 3), exporter-down (exit 4), disabled or unverified. The 00c launcher commands run it in their pre-flight diagnostics and relay any warning to the operator before wave 001.

Interactive mode (numbered selector in a TTY) and dry-run:

cstk install --interactive   # lists numbered profiles + skills; selection via toggle
cstk install --dry-run --profile all
cstk update --dry-run

Plan usage gauge (`cstk statusline` + `cstk plan-usage`)¶

Since v7.2.0 the toolkit can also capture the plan usage gauge you see in /usage — no OAuth credential, no API key: Claude Code already sends rate_limits.five_hour/seven_day in the statusline payload on every render, so the capture hook just reads what is already passing by and persists it locally in the plan_usage table of ~/.claude/cstk/knowledge.db.

cstk statusline install    # wires the capture hook into ~/.claude/settings.json
cstk statusline status     # is the capture active (and settings.json still valid)?
cstk plan-usage            # latest capture per scope (five_hour / seven_day)
cstk plan-usage history    # time series; reuses --scope/--limit/--since from cstk usage

Opt-in by construction — nothing is captured until you run statusline install — and 100% local. An existing custom statusline command is preserved and chained as a mandatory stdout pass-through, never silently overwritten. A scope without measurement prints nao medido (null with --json) — never a fabricated zero.

Manual installation (deprecated, still supported)¶

Directly copying the directories still works (cp -r plugins/cstk/skills/ ~/.claude/skills/), but does not track versions or detect drift — see CLAUDE.md §"Installed vs Source Drift". cstk solves this via manifest + hash_dir.

Complete cstk documentation¶

cli/README.md — technical overview, conventions, release process
docs/specs/_archived/cstk-cli/ — spec, plan, contracts, quickstart

Conferindo a instalacao¶

cstk --version    # imprime tag semver da release instalada
cstk list         # lista skills instaladas + status (managed / drifted / unmanaged)
cstk doctor       # detalha drift entre manifest e disco

Se cstk nao aparece no PATH, garanta que ~/.local/bin esta em PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # ou ~/.bashrc
exec "$SHELL" -l

Atualizacao¶

cstk self-update   # atualiza o proprio binario cstk a partir do GitHub
cstk update        # atualiza skills preservando edicoes locais (--force sobrescreve)

A skill cstk update deteca drift (edicao local depois da instalacao) e pausa por seguranca antes de sobrescrever. Use --force para aceitar a sobrescrita ou cstk doctor para inspecionar diferencas.