Metadata-Version: 2.4
Name: clink-cli
Version: 0.2.3
Summary: Call installed CLI agents from scripts with JSON, or connect them to an MCP client
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/acebytes/clink-cli
Project-URL: Repository, https://github.com/acebytes/clink-cli
Project-URL: Issues, https://github.com/acebytes/clink-cli/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: clink/resources/CODEX-LICENSE
License-File: clink/resources/CODEX-NOTICE
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# 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](https://github.com/BeehiveInnovations/pal-mcp-server), formerly Zen MCP. **Copyright 2025 Beehive Innovations.** Retains upstream attribution and the [Apache 2.0 license](https://github.com/acebytes/clink-cli/blob/main/LICENSE).

## Install with uv

```sh
uv tool install clink-cli
```

This installs both `clink` and `clink-mcp-server` from [PyPI](https://pypi.org/project/clink-cli/). 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:

```sh
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](https://github.com/acebytes/clink-cli/blob/main/docs/release-evidence.md).

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](https://github.com/acebytes/clink-cli/blob/main/docker/README.md) 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:

```sh
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.3-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:

```json
{
  "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.3 source tree:

```sh
cd /absolute/path/to/clink-cli
./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](https://github.com/acebytes/clink-cli/blob/main/.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:

```sh
.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:

```sh
cd /absolute/path/to/your-project
claude --plugin-dir /absolute/path/to/clink-cli/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](https://github.com/acebytes/clink-cli/blob/main/docs/project-setup.md) for selected clients, configuration precedence, conflicts, and recovery.

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

```json
{
  "mcpServers": {
    "clink": {
      "command": "/absolute/path/to/clink-cli/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](https://github.com/acebytes/clink-cli/blob/main/docs/getting-started.md), [CLI configuration](https://github.com/acebytes/clink-cli/blob/main/docs/cli-configuration.md), and [migration from PAL](https://github.com/acebytes/clink-cli/blob/main/docs/migration.md).

## 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:

```json
{"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:

```json
{
  "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:

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

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

```json
{"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](https://github.com/acebytes/clink-cli/blob/main/docs/native-cli-tasks.md) 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:

```sh
.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:

```sh
.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:

```json
{
  "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
}
```

```sh
.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](https://github.com/acebytes/clink-cli/blob/main/docs/generation-native-setup.md), [schema 2 protocol](https://github.com/acebytes/clink-cli/blob/main/docs/generation-native-protocol.md), and [schema 3 and family discovery](https://github.com/acebytes/clink-cli/blob/main/docs/generation-native-families.md).

## 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](https://github.com/acebytes/clink-cli/blob/main/docs/cli-configuration.md).

**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](https://github.com/acebytes/clink-cli/blob/main/SECURITY.md).

## Development

```sh
.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](https://github.com/acebytes/clink-cli/blob/main/docs/release-evidence.md) and [changelog](https://github.com/acebytes/clink-cli/blob/main/CHANGELOG.md). Report bugs in this fork's [issue tracker](https://github.com/acebytes/clink-cli/issues), excluding secrets and private transcripts.
