Nock

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) 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

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

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

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:

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:

[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

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

pytest

MIT. Needle is a separate project from Cactus Compute.