# Nock

![Nock](examples/nock-github-card.png)

Nock sits between a coding agent (ChatGPT / Codex, Cursor, Claude Desktop, …) and your local tools.

The cloud model does the thinking. A tiny on-device model ([Needle](https://cactuscompute.com/needle)) tries to pick the right tool. Destructive actions wait for a confirm token. If Needle is unsure or the request is off-topic, Nock refuses without sending your tool list to the cloud.

The host only sees four tools: `nock.resolve`, `nock.call`, `nock.search`, `nock.status`.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Optional — so `nock.resolve` can pick tools instead of always refusing:

```bash
pip install -e ".[needle]"
```

That extra pulls JAX. First resolve also downloads the ~14 MB Needle engine.

## Point Codex / ChatGPT desktop at it

They share `~/.codex/config.toml`. Easiest:

```bash
codex mcp add nock -- /ABS/PATH/nock/.venv/bin/nock serve --warmup
```

Use the **absolute** path to the venv `nock` binary. Restart the app, then `/mcp` should list `nock`.

## Your tools live here, not in Codex

`~/.config/nock/config.toml`:

```toml
[discover]
include_host_configs = false

[servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/ABS/PATH/to/a/folder"]
default_risk = "safe"

[servers.fs.tools.write_file]
risk = "destructive"
```

Keep Codex’s MCP list to **Nock only**. Nock starts the filesystem (and anything else you add).

## How the host should use it

1. `nock.resolve` with the user text.
2. `fast` → `nock.call` the returned envelope.
3. `shortlist` → pick one of the listed tools, then `nock.call`.
4. `escalate` → answer without tools. Do not call `nock.search`.
5. If `nock.call` returns `type: nock.confirm`, call again with `confirm=true` and `confirm_token`.

Reads should not confirm. Writes should.

## Commands

```bash
nock serve          # stdio MCP server (what the host launches)
nock status         # dry config check (does not talk to a running serve)
nock doctor         # binaries, Needle, duplicate servers
nock hosts          # copy-paste snippets for Codex, Claude, Cursor, Continue
nock index          # warm Needle’s tool index
```

## Tests

```bash
pytest
```

MIT. Needle is a separate project from [Cactus Compute](https://cactuscompute.com/needle).