interlinked-cli

The harness for your harness. A local guard layer for AI coding agents — hooks into Claude Code, Codex, Cursor, Copilot CLI, and Gemini CLI; evaluates every tool call against deterministic rules; blocks the dangerous ones in milliseconds; keeps a local activity log you can grep.

Why this matters for responsible AI at scale

Once an AI agent can write code, run shell commands, and install dependencies on its own, the question for any organization stops being "can it help?" and becomes "how do we prove every autonomous action was checked against policy before it ran — and reconstruct what happened afterward?"

Interlinked is a control plane for exactly that. It sits at the boundary between the agent and the system, and on every tool call it:

• Enforces policy deterministically — a block-or-allow decision in milliseconds, with no model in the decision path, so every verdict is explainable and reproducible rather than a probabilistic guess.
• Fails closed on what causes incidents — destructive commands, secrets written into source, and unvetted dependencies are stopped before they touch disk, and remain blocked even when the daemon is unreachable.
• Produces an audit trail by construction — every decision is written to a replayable log, attributable to a specific agent and session, ready to inspect or report on.

That is the triad every responsible-AI program is built on — evaluation, observability, and enforceable guardrails — implemented at the one layer where it can't be skipped: the point where an agent's intent becomes a real-world action. Policy is shared through version control and enforced identically across 5 agent runners and a fleet of agents working in parallel — with no cloud dependency and no telemetry.

This isn't only an architecture diagram. The receipts below are 865 per-event-audited blocks captured over 38 days of daily use on a single developer's machine — and the pattern is the point: a deterministic, audit-first enforcement boundary that works the same way for one agent or a thousand.

Receipts from 38 days of dogfooding on the author's machine. The activity log captured 1081 distinct guard_block events (over-registration duplicates collapsed, grep-accelerator answers excluded); 865 of them survived a per-event audit against Claude Code session transcripts to confirm the agent's actual tool_input. The audited breakdown:

• 574× edits that introduced a new TypeScript error — blocked before the write landed (tsc-diff-overlay)
• 90× new source file with no companion test (TDD gate)
• 65× shell-redirect bypass attempts (cat > file.ts to dodge the content-quality gate)
• 42× writes outside the repo root
• 32× empty catch {} blocks
• 25× kill / pkill / killall at running processes — four aimed at the harness or session itself
• 17× edits to files another agent held the reservation on
• 13× destructive git (reset --hard, branch -D, stash drop)
• 4× secrets detected in proposed write content
• 3× package installs not on the team allowlist (fail-closed supply-chain gate)

Full breakdown on the landing page or in What you get below.

Local-first by design. The harness, activity log, and checks run on your machine; server-backed collaboration commands are optional and require an Interlinked MCP Server URL. No cloud, no telemetry, no LLM in the hot path.

Install From Source

The CLI is currently intended to run from the GitHub repo rather than a formal npm package. Requires Node.js 22+. Supported on macOS and Linux (including WSL on Windows — native Windows is not supported).

git clone https://github.com/QuentinCody/interlinked-cli.git
cd interlinked-cli
npm ci
npm run build          # produces dist/index.js + dist/hook-entry.js
npm link               # exposes `interlinked` and `interlinked-hook` on PATH

After that, interlinked update pulls the latest repo changes, rebuilds, and refreshes the linked binaries.

interlinked install-hooks from a cloned checkout records an absolute path to dist/hook-entry.js in your agent's settings, so hooks will keep firing as long as the clone stays put. If you move or delete the clone, rerun interlinked install-hooks from the new location (or interlinked uninstall-hooks first). The tarball-install smoke test in .github/workflows/ci.yml exercises the same end-to-end path.

What you get

• Guard harness. A local Unix-socket server evaluates every agent action against 116 deterministic safety rules (destructive commands, secrets in writes, sensitive-file reads, lockfile drift, etc.) and returns block/allow decisions in about 1–5 ms for cheap rules; content-checking rules (tsc/biome diff-overlay) take whatever the compiler takes.
• Content-quality gate. tsc and biome run over the proposed file content before a write lands. The gate blocks only on net-new findings, never on pre-existing issues. Works for Edit/Write tools and — via interlinked write — for Bash-mediated writes like sed -i or cat > file.
• Auto file reservation. Every file write takes a lease-based reservation with a 5-minute TTL and a 30-second idle auto-release. When an Interlinked MCP Server is configured, a write that targets a file already reserved by another developer's agent is blocked with a pointer to coordinate via MCP messages; otherwise the reservation is local-only.
• Post-edit checks. 27 quality checks across 8+ languages (tsc, biome, cargo, mypy, …) and 25 structural checks (export surface, import resolution, cycles, blast radius) run after each edit.
• Offline activity log. Every hook event appends to .interlinked/activity.jsonl synchronously (~0.1 ms). interlinked status, activity, explain, and doctor read from this log.
• Trigram grep. Grep calls route through a cached trigram index, narrowing candidate files before rg runs.

Quick start

# In the repo you want to instrument:
interlinked install-hooks --runner claude-code   # or omit --runner to auto-detect
interlinked harness start                        # start the local guard server
interlinked status                               # show what's configured

That's it for local use. Run your agent of choice and tool-use events flow through the harness. Server commands such as login, sync, tasks, and inbox are available when you point the CLI at an Interlinked MCP Server.

Optional: /enforce — turn AGENTS.md prose into deterministic rules

install-hooks wires the harness; interlinked enable does that plus installs the /enforce skill across every detected agent runner (Claude Code, Codex, Gemini, Copilot, Cursor). Use it when you want the imperatives in your AGENTS.md / CLAUDE.md / .clinerules/ to become rules the harness actually enforces, instead of prose the model may or may not follow.

# In the repo you want to instrument:
interlinked enable                                    # installs hooks + /enforce
# Restart or reload your agent so it picks up the new skill, then in-agent:
/enforce                                              # walk the project, distill imperatives
/enforce AGENTS.md                                    # or target a single file
/enforce list                                         # see what got distilled, grouped by source

Some runners surface skills via description match instead of /-prefix ($enforce, @enforce, etc.). The slash form is canonical; description match is a fallback for surfaces that don't expose slash-skills. Output lands at .interlinked/distilled-rules.json; the harness reloads automatically within ~2s. Full reference: skills/enforce/SKILL.md in this repo.

Day-to-day commands

Command	What it does
interlinked status	Summary of configured agents, active harness, recent events
interlinked activity --since 1h	Recent hook events (filterable by agent, tool, since)
interlinked explain --since 1h	Per-event explanation including guard decisions
interlinked doctor	Diagnostics: hook registration, harness liveness, config sanity
interlinked write <path> --stdin	Write a file through the content-quality gate
interlinked multi-edit <path>	Apply N edits to one file atomically (all or none)
interlinked verify	Run the full quality + structural gate over the current tree
interlinked verify --all-checks	Deep-audit mode: add advisory smell/taste checks
interlinked mode	Show or switch enforcement mode
interlinked coverage	Per-file coverage ratchet (needs a coverage-summary.json)
interlinked mutation	Per-file mutation-score ratchet (needs a Stryker report)
interlinked structure	Generic artifact structure management (manifests, adoption)
interlinked harness start/stop/status/test	Manage the harness daemon
interlinked daemons	List all active harness daemons and their health
interlinked uninstall-hooks	Remove hooks this CLI installed (manifest-driven)

Run interlinked --help for the full command list, or interlinked <command> --help for per-command flags.

How it fits together

agent (Claude/Copilot/Gemini/Cursor/Codex) ──► interlinked-hook
                                        │
                                        ├─► harness Unix socket
                                        │     └─► guard eval (block/allow) in ~1–5 ms
                                        │     └─► post-edit quality + structural checks
                                        │
                                        └─► .interlinked/activity.jsonl (append, ~0.1 ms)
                                              └─► interlinked {status,activity,explain,doctor}

The installed hook invokes the packaged interlinked-hook binary. If you uninstall the CLI, previously installed hook entries fail open until you run interlinked uninstall-hooks or reinstall the package.

Enforcement modes

Guard evaluation has two layers:

1. Guard rules — destructive shell commands, secrets in writes, recursive deletes, force-pushes to protected branches. These block by default and are not downgraded by mode selection. Individual rules can still be disabled via disabled_rules in .interlinked/guard-rules.local.json if you have a specific reason.
2. Taste rules — style, complexity, coverage, test quality. Mode selection governs these.

Switch modes with interlinked mode <name>:

• balanced (default): destructive commands are blocked; quality findings warn.
• lenient: findings surface as warnings, writes proceed.
• strict: findings block the write until the agent fixes them.

Team-shared policy lives in .interlinked/guard-rules.json. Personal overrides go in .interlinked/guard-rules.local.json (gitignored).

Privacy

• Harness decisions and activity capture are local by default. Data leaves your machine only when you run server-backed commands such as login or sync, or when you explicitly opt into another remote workflow.
• No telemetry, no analytics, no "phone home" — not even an anonymous version-check ping. The CLI makes no outbound network calls on its own.
• Hook events, guard decisions, and quality findings stay in .interlinked/ under the repo root.

Contributing and reporting issues

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Bug reports and feature requests: https://github.com/QuentinCody/interlinked-cli/issues

License

MIT. See LICENSE.