Clink CLI and MCP server

Use clink generate to send a JSON request to an installed CLI agent from a script and read the result on stdout. To use Clink from Claude Code or another MCP client, connect clink-mcp-server for access to 18 tools. One Python package, clink-cli, installs both commands.

Consultations return advice and proposed code. Explicit native tasks can edit files, run tests, and use the selected agent’s configured tools and permissions.

Derived from PAL MCP Server, formerly Zen MCP. Copyright 2025 Beehive Innovations. Retains upstream attribution and the Apache 2.0 license.

Install with uv

uv tool install clink-cli

This installs both clink and clink-mcp-server from PyPI. If you installed the v0.2.0 GitHub wheel with uv, run uv tool uninstall clink-mcp-server first to free the command names.

Connect to Claude Code

From the project directory where you use Claude Code, run:

claude mcp add --scope local --transport stdio clink -- "$(uv tool dir --bin)/clink-mcp-server" --project "$PWD"
claude mcp get clink

Look for Connected. Local scope keeps the registration private to you in this project, and --project "$PWD" tells Clink which workspace to use. Open Claude Code in the same directory and run /mcp to see clink. To check the connection without calling a model, ask Claude to use Clink’s version tool.

Supported operations

Admission is specific to an operation, executable, launch recipe, and parser. Support in one column does not enable another.

CLI	Consultation	Native MCP tasks	Programmatic generation
Codex 0.166.0	Admitted for text, explicit local images, and structured search.	Disabled: supported output omits a genuine prelaunch permission refusal.	Admitted; schema 2 or 3 with an explicit model.
Claude Code 2.1.304	Unavailable under the advisory policy.	Admitted.	Admitted; schema 2 or 3 with an explicit full model ID.
xAI Grok Build 1.0.70 (grok)	Unverified.	Admitted.	Admitted; schema 3 with native_default selection.
Antigravity 1.4.12 (agy)	Unverified.	Admitted.	Implemented but unverified; execution is refused.
Gemini	Unverified.	Not implemented.	Not implemented.

The recorded admissions cover exact macOS arm64 binaries. Other builds, operating systems, versions, or changed recipes require verification and fail closed. An installed executable or successful login alone is insufficient. Grok reported grok-4.7-build in the recorded successful generation text/action checks. Antigravity's native-task actual model remains unknown; its native-task admission does not admit generation. See release evidence and limits.

Python 3.10+ is required; Python 3.12 is the tested runtime. Process supervision targets POSIX systems. Local discovery and offline tests can run without CLI credentials. Native Windows delegation is unavailable; the container supports local tools without installing CLI agents.

Install and connect

Install from a wheel or source checkout

For a standalone wheel installation, replace the wheel path and choose a persistent environment outside the source tree:

python3 -m venv /absolute/path/to/clink-runtime
/absolute/path/to/clink-runtime/bin/python -m pip install /absolute/path/to/clink_cli-0.2.2-py3-none-any.whl
/absolute/path/to/clink-runtime/bin/python -m clink.setup --project /absolute/path/to/your-project

The installed package contains its manifests, prompts, and admission resources. It does not need the original checkout at runtime. To register its console entrypoint directly in an MCP client, use:

{
  "mcpServers": {
    "clink": {
      "command": "/absolute/path/to/clink-runtime/bin/clink-mcp-server",
      "args": ["--project", "/absolute/path/to/your-project"]
    }
  }
}

Alternatively, from the reviewed 0.2.2 source tree:

cd /absolute/path/to/clink-mcp-server
./run-server.sh --setup

This explicitly creates .venv, installs runtime requirements, and exits. Ordinary startup installs nothing. The launcher does not create .env, copy credentials, change native CLI configuration, or register MCP clients. Optional server settings are documented in .env.example. To build a wheel from this tree, install the development requirements and run .venv/bin/python -m build; the wheel is written under dist/.

Configure an existing project from that source installation:

.venv/bin/python -m clink.setup --project /absolute/path/to/your-project

Setup creates project-local .clink/cli_clients/ manifests, .clink/prompts/, and .mcp.json. It makes no model calls and preserves custom files by reporting conflicts. The generated MCP registration binds a server explicitly to that project. Reconnect your MCP client, then call version and listmodels with empty arguments. These calls need no native CLI login.

Claude Code users can load the checkout-local setup plugin:

cd /absolute/path/to/your-project
claude --plugin-dir /absolute/path/to/clink-mcp-server/integrations/claude

Then run /clink:setup. This command is available only when that local plugin is loaded; MCP registration alone does not install it. See the project setup guide for selected clients, configuration precedence, conflicts, and recovery.

For another MCP client, adapt this stdio registration to its configuration format:

{
  "mcpServers": {
    "clink": {
      "command": "/absolute/path/to/clink-mcp-server/run-server.sh",
      "args": ["--project", "/absolute/path/to/your-project"]
    }
  }
}

Authenticate the chosen CLI through its own login mechanism before an admitted model call. Ensure the MCP client's PATH can find it, or configure its executable path in a manifest. The server does not require hosted-provider API keys. See getting started, CLI configuration, and migration from PAL.

Consult or delegate

Omitting action selects consultation with codex and the default role. The following is a clink MCP tool argument, not a shell command:

{"prompt":"Review this proposed change and return suggested improvements.","cli_name":"codex"}

For native work, select an admitted CLI and a project inside its configured roots:

{
  "action": "start",
  "cli_name": "claude",
  "project_dir": "/absolute/path/to/your-project",
  "prompt": "Fix the failing test, run the relevant checks, and report changed files and unfinished work.",
  "request_key": "fix-test-1",
  "timeout_seconds": 180
}

Save the returned task_handle. Poll, follow up when followup_available is true, or cancel:

{"action":"status","task_handle":"<returned task_handle>"}

{"action":"followup","task_handle":"<returned task_handle>","prompt":"Check one edge case and report the result.","request_key":"fix-test-followup-1"}

{"action":"cancel","task_handle":"<returned task_handle>"}

A follow-up resumes the private native session with a new attempt; native handles are separate from consultation continuation_id values. Identical submissions with the same request key are deduplicated while retained. Changed input with that key returns request_key_conflict. Handles, session mapping, and deduplication are volatile and are lost on restart. See native task usage for states, bounds, and ownership rules.

Programmatic generation

The examples below use the source installation's .venv/bin. For a standalone wheel, use /absolute/path/to/clink-runtime/bin instead. Install the checkout's console commands locally if needed:

.venv/bin/python -m pip install -e .
.venv/bin/clink generation-capabilities --json

Capabilities discovery is read-only: it does not launch a CLI, authenticate, or grant execution authority. It reports schemas 2 and 3 with operation-specific admission. Optional --cli NAME --executable /absolute/path/to/executable checks one local executable's identity without running it. Launch admission is checked again before execution.

Approve an existing project folder independently of MCP project setup:

.venv/bin/clink allow /absolute/path/to/your-project --cli grok

The command shows the resolved path and asks a default-No question; --yes explicitly preapproves it for scripts. It saves an allowed_roots entry in operator configuration and preserves existing settings. This does not grant native CLI trust or permissions. Generation does not discover project manifests from request paths.

Schema 3 example request.json, using an existing canonical project path:

{
  "schema_version": 3,
  "request_id": "66f96fc9-969d-4c0e-ab92-e355fa0e7588",
  "execution_mode": "native",
  "project_dir": "/absolute/path/to/your-project",
  "cli": "grok",
  "model_selection": {"kind": "native_default"},
  "instructions": "Rewrite the supplied text for clarity. Return only the revision.",
  "input": "Explain the tradeoffs of a cache for this application.",
  "timeout_seconds": 120
}

.venv/bin/clink generate --request-json - < request.json

Generation reads one JSON request followed by EOF and writes one terminal JSON result. Schema 3 uses model_selection: Codex and Claude require {"kind":"explicit","id":"<native model ID>"}; Grok and Antigravity accept only {"kind":"native_default"}. Antigravity still refuses execution because its generation admission is unverified. Schema 2 preserves Codex/Claude's explicit model field. The older no-tools schema 1 profile remains refused.

Each accepted request makes at most one top-level CLI invocation, with no wrapper retry, resume, or fallback. Only status: "completed" with exit 0 is ordinary success; validate the result's request identity and hashes before using its text. Completion validates final-response transport, not fulfillment. Requested/effective model selection is distinct from CLI-reported actual identity, which remains null when unreported. See generation setup, schema 2 protocol, and schema 3 and family discovery.

Tools and configuration

All 18 tools are enabled unless listed in DISABLED_TOOLS; version and listmodels remain available.

Tools	Purpose
chat, clink	Advisory consultations; clink also provides explicit native tasks.
thinkdeep, codereview, precommit, debug, secaudit, analyze, refactor, testgen	Caller-driven investigation with final expert-call conditions.
consensus	Independent consultations for caller synthesis, sequential by default with explicit parallel mode.
apilookup	Verified native search with structured sources.
planner, docgen, tracer, challenge	Local workflow guidance.
listmodels, version	Local configuration discovery and provenance.

Manifest precedence is bundled defaults → legacy ~/.pal/cli_clients/ → user ~/.clink/cli_clients/ → explicitly bound project .clink/cli_clients/ → CLI_CLIENTS_CONFIG_PATH. Each later manifest replaces the entire named client. Consultation and native task model defaults are separate; generation has its own request and admission contracts. See CLI configuration.

Risk & Mitigation: Native execution can change files or external systems before failure or cancellation. Approved roots constrain project selection and supplied context, not all native authority. Cancellation does not roll back effects or guarantee detached/remote work stopped. Inspect actual changes and independently run checks before accepting work. Clink preserves native permission controls and provides no approval bypass or relay. See security policy.

Development

.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pytest tests/ -v -m "not integration and not real_cli and not private_evidence"
.venv/bin/python -m ruff check .
.venv/bin/python -m black --check .
.venv/bin/python -m isort --check-only .
.venv/bin/python -m build

Ordinary verification uses synthetic executables and makes no live model calls. Historical live verification requires the private evidence and approval process; the public verification scripts do not submit model requests. See release evidence and changelog. Report bugs in this fork's issue tracker, excluding secrets and private transcripts.