interlinked-setup

Stars9

Forks1

UpdatedJuly 25, 2026 at 10:27

Install, operate, and troubleshoot the Interlinked CLI harness in a repo — install/uninstall agent hooks, connect runners (Claude Code, Codex, Copilot CLI, Gemini, Cursor), start/stop/restart the local guard daemon, run `interlinked doctor`, switch server / sync-mode / check-policy, log in, and manage the two-tier `.interlinked/` config. Load when setting up Interlinked, when `interlinked doctor` reports problems, when the guard daemon is down or stale, when hooks are not firing, or when configuring or disabling Interlinked.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

QuentinCody

QuentinCody/interlinked-cli

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Network and Computer Systems AdministratorsComputer and Mathematical Occupations·SOC 15-1244

SKILL.md

readonly

More from this repository

same repository

interlinked-coordination

QuentinCody/interlinked-cli

Coordinate with other agents/humans via the optional Interlinked MCP Server, and use local checkpoints & file reservations. Load this when picking up or handing off work (`tasks`, `send`, `inbox`, `handoff`), switching workspace context (`workspace`, `attach`), when a write is blocked because a file is "reserved by" another agent, when creating/restoring a local checkpoint (`checkpoint`, `rewind`, `resume`), installing the git-hook reservation guard (`interlinked guard`), or checking CI failure rates (`ci-status`). IMPORTANT: `checkpoint`/`rewind`/`resume` MUTATE git state (stash, checkout, clean -fd) and must not be run without explicit per-turn user authorization.

2026-07-259

interlinked-harness

QuentinCody/interlinked-cli

Understand and respond to the Interlinked PreToolUse guard — the local daemon that BLOCKS dangerous tool calls before they run. Load this when a Bash command or file edit was refused with "BLOCKED: … Suggestion: …", when you see an `[interlinked:<check>]` warning tagged `[proven]` or `[heuristic]`, when a destructive command / force-push / protected-file / secret / repo-confinement rule fired, when a grep was answered by the index, or when you need to know how to legitimately suppress a false positive or disable a guard rule. Covers what blocks, how to read the reason, suppression grammar, determinism tags, and the fail-closed cold fallback.

2026-07-259

interlinked-observability

QuentinCody/interlinked-cli

Inspect what AI agents did — the local, offline-first activity log and observability commands. Load this when you want to see what happened this session, tail activity live, review what the guard blocked/warned, find recurring mistakes, inspect a specific session/event, view the dependency graph, backfill external (Codex) sessions, verify the tamper-evident guard-decision log, or push buffered events to the server. Covers `status`, `activity`, `logs` (with `--type`/`--follow`), `explain`, `watch`, `telemetry`, `trace`, `search`, `recurrence`, `viz`, `audit`, `collect`, `compact`, `sync`, and the activity.jsonl / collection.jsonl / timeline.jsonl event-log model.

2026-07-259

interlinked-quality-gates

QuentinCody/interlinked-cli

Respond to Interlinked's metric ratchets — the edit-time gates that block on line-count, cyclomatic complexity, coverage, and CRAP, plus the baseline-integrity gate. Load this when an edit was BLOCKED for growing a file past the line cap (500), for a cyclomatic-complexity jump or over-cap function, for adding an uncovered line or dropping coverage, for a high CRAP score, or for "loosening a baseline"; when adopting Interlinked on a legacy repo (`interlinked adopt`); or when managing caps/coverage/mutation baselines (`interlinked caps`, `coverage`, `mutation`, `debt`, `metrics`). The rule: water-lines only tighten — meet the bar (decompose / add a test / cover the line), never lower the baseline.

2026-07-259

interlinked

QuentinCody/interlinked-cli

Overview and router for the Interlinked CLI — a local guard, quality-enforcement, and observability layer for AI coding agents. Load this when working in a repo that has a `.interlinked/` directory, when you see any `[interlinked:*]` output or a `BLOCKED: … Suggestion: …` reason and are not sure which area it belongs to, or when you need to know what the `interlinked` command can do. This skill explains the mental model, the `.interlinked/` layout, the `[proven]`/`[heuristic]` tags, and routes you to the focused `interlinked-*` skill for setup, guard blocks, verify/checks, quality ratchets, supply-chain, spec-audit, observability, or coordination.

2026-07-259

interlinked-spec-audit

QuentinCody/interlinked-cli

Keep prose specs and design docs honest against the code using Interlinked's spec-audit system. Load this when extracting a doc's invariants or facts (`interlinked spec invariants`, `spec agenda`), when you see `[interlinked:spec-drift]`, `[interlinked:spec-marker]`, `[interlinked:spec-xref]`, or `[interlinked:disputed-ground]` warnings after editing markdown, when ingesting/triaging an external review report (`interlinked findings ingest / status / verify / ack`), or when running executable doc examples (`interlinked doctest`). The system detects and tracks — it never auto-fixes; you write the fix. Covers the fact ledger, findings reconciliation, invariants/agenda, and current-state caveats.

2026-07-259

name

interlinked-setup

description

interlinked-setup — install, operate & troubleshoot the harness

Interlinked is a local, offline-first guard layer for AI coding agents. Everything lives under <repo>/.interlinked/, and a local daemon ("the harness", a Unix-socket server) evaluates every agent tool call. This skill covers turning it on, keeping the daemon healthy, configuring it, and turning it off. The remote server is optional — hooks, guard, and activity capture work with zero network.

Load this when

Installing Interlinked or connecting a runner (Claude Code / Codex / Copilot CLI / Gemini / Cursor).
interlinked doctor reports failures, or hooks are not firing / not capturing events.
The guard daemon is down, stale, or tool calls are being blocked with a "daemon unreachable" reason.
Changing the server URL, sync mode, or check-policy/operational tier.
Disabling or fully removing Interlinked.

Mental model

Per-cwd, offline-first. All state is <cwd>/.interlinked/. Two-tier config: config.json (committed, shared) + config.local.json (gitignored, personal).
A daemon does the work. harness start runs a background Unix-socket server. When it is up you get the full check set; when it is down the hook falls back to a small inline subset and fails closed on the dangerous stuff (destructive commands, package installs, line-cap, merge conflicts).
The server is optional. Auth / sync only matter for server-backed coordination (see interlinked-coordination). Skip it entirely for local-only use.

Turning it on

Command	What it does	When to use
`interlinked enable`	Full setup: writes `.interlinked/` config, installs per-client hooks, updates `.gitignore`, installs statusline (Claude/Copilot), installs the `/enforce` skill, auto-starts the daemon. Idempotent; re-running clears any stand-down.	The normal way to turn Interlinked on.
`interlinked setup`	Runs `enable`, then `login` if no token (skips login on localhost / when a token is present).	One-shot bootstrap with server auth.
`interlinked init`	Interactive/auto onboarding wizard (`--yes` for non-interactive).	Guided first-run.
`interlinked install-hooks`	Adapter path: writes only hook entries + `installer-manifest.json` (no full config scaffold).	Precise, manifest-tracked hook install.

Key enable flags: --server <url> · --agent <name> · --clients <list> (claude,copilot,gemini,codex,cursor) · --sync-mode <realtime|local|manual> · --data-dir <path> · --structure <mode> · --dry-run. install-hooks uses different vocabulary: --runner <claude-code,copilot-cli,cursor,gemini-cli,codex> · --scope <user|project|local> · --mode <balanced|strict|lenient>.

interlinked enable --agent my-bot                 # detects clients, starts daemon
interlinked enable --clients claude --dry-run      # preview without writing
interlinked install-hooks --runner claude-code --scope project

Client detection = presence of the config directory (.claude/, .codex/, …), not the binary. After enabling, Codex needs a session restart and Copilot needs /skills reload to pick up hooks.

Operating the daemon

Command	Purpose
`interlinked harness start [--verbose] [--json]`	Start the daemon (background). Reaps orphans first and auto-rebuilds stale `dist/`, so a cold start can take a few seconds.
`interlinked harness stop`	SIGTERM the daemon.
`interlinked harness restart`	Stop + fresh start; the only way to pick up config/mode changes. Note: clears per-session trajectory state.
`interlinked harness status [--json]`	Running/PID, socket, RSS, mode, orphan count, build staleness.
`interlinked daemons [--cleanup]`	List all per-session daemons; `--cleanup` purges dead-PID records.
`interlinked harness reap [--force] [--all]`	List (default) or kill orphan daemons.

interlinked harness status --json      # is it up? which mode?
interlinked harness restart            # after editing config / changing mode

Diagnosing problems

interlinked doctor is the first stop. It runs local + system + server checks and exits non-zero if any check fails. --fix repairs common drift (regenerates a drifted hook script, strips malformed permission rules, migrates legacy config).

interlinked doctor            # diagnose
interlinked doctor --fix      # auto-repair what it safely can
interlinked context --json    # show the effective merged config
interlinked env               # list supported env vars + current values

What "healthy" looks like in doctor: config dir + both config files present, hook script present, per-client "Hooks installed", and Harness server: Running (PID …) (vs "Not running — inline fallback"). A missing token on a non-localhost server is a fail; on localhost it is only a warn (dev mode allows unauthenticated).

Dev loop after editing the CLI source: interlinked reload rebuilds the CLI in its own checkout, refreshes this repo's hooks, and restarts the daemon only if something changed.

Config & environment

.interlinked/config.json (committed): server_url, default_project, mode (operational tier), skip_paths, pii_patterns, nested harness feature flags.
.interlinked/config.local.json (gitignored): access_token, agent_name, workspace_id, sync_mode, active_server + servers map, guard_mode, data_dir.
Env overrides (win over both files): INTERLINKED_SERVER_URL, INTERLINKED_ACCESS_TOKEN (alias INTERLINKED_TOKEN), INTERLINKED_AGENT_NAME, INTERLINKED_WORKSPACE_ID, INTERLINKED_SYNC_MODE, INTERLINKED_HOME (relocates the whole config dir), INTERLINKED_DATA_DIR, INTERLINKED_CLIENTS (non-interactive bootstrap only).

Two different mode commands — do not conflate them:

interlinked mode <balanced|strict|lenient> → per-check policy preset → check-policy.json.
interlinked harness mode <budget|quality|ci> → operational timeout tier → config.json mode + regenerates the hook. Requires harness restart to take effect.

Auth & server (optional)

interlinked login --server https://your-server.dev   # OAuth PKCE (opens browser)
interlinked login --token "$INTERLINKED_TOKEN"        # CI / headless
interlinked attach --agent my-bot --auto              # link identity + workspace
interlinked logout [--all]

localhost/127.0.0.1 = dev mode → auth skipped (setup/init skip login for local servers).
Token resolution: CLI token in config.local.json → auto-refresh → Claude Code credential fallback (~/.claude/.credentials.json).
Sync modes: realtime (default; per-event post + session-end batch), manual (per-event only), local (no server posts at all).

Turning it off

Command	Effect
`interlinked disable [--reason <t>] [--until <dur>] [--team]`	Non-destructive stand-down: records a marker + stops the daemon. Hooks and config stay. Re-arm with `interlinked enable`.
`interlinked disable --uninstall [--keep-config]`	Destructive teardown: removes hooks + the installed skills and deletes the `.interlinked/` config dir — pass `--keep-config` to keep the config.
`interlinked reset --force`	Nuclear: delete the entire `.interlinked/` dir and strip hook entries. Irreversible; `--force` required.
`interlinked uninstall-hooks`	Remove only what `install-hooks` recorded in its manifest.

A live daemon ignores the stand-down marker. If disable reports the daemon is still running, run interlinked harness stop — the project stays guarded until the daemon dies.

Gotchas

disable is non-destructive by default now — bare disable just stands down; use --uninstall (or reset --force) for real teardown.
clean defaults to dry-run; reset requires --force.
Two install paths, non-interchangeable uninstall. uninstall-hooks only cleans an install-hooks-style install; use disable --uninstall / reset to clean an enable install.
Claude Code merge-up dedup: enable refuses to install Claude hooks when an ancestor .claude/settings.json already has them (would double-fire) — run enable from that ancestor.
reload needs a source checkout — it rebuilds the CLI checkout the running binary resolves to (typically a ~/.local/bin symlink), not the current repo.
--json support is per-command; unknown flags error. doctor takes only --fix/--json.

Related skills

interlinked-harness — what the guard blocks and how to respond when a tool call is refused.
interlinked-observability — inspect the activity the hooks capture (status, activity, logs).
interlinked-coordination — the optional server-backed side (tasks, messages, workspaces).