catenary

Catenary

Catenary hands an AI coding agent a small, opinionated set of code-intelligent commands — and a hook that keeps it on them. Reach for grep and you're redirected to catenary grep; reach for ls or find and you get catenary glob. Every command the agent can run is backed by a language server, so it navigates code by meaning instead of brute-forcing text. The generic path isn't blocked for safety — it's off the menu, so the code-intelligent one is the only path left.

Why Catenary

Exposing language-server tools to an agent isn't novel anymore — most coding CLIs do it, and Catenary did it early. But having a tool and using it are different things. Give an agent grep, find, raw file reads, and LSP navigation, and it reaches for whatever's nearest — usually brute-force text scanning that burns context and misses structure.

Catenary takes the choice away. It exposes one curated, code-intelligent surface and enforces it:

• A PreToolUse hook runs an allowlist over every shell command the agent issues.
• Denied commands aren't dead ends — each denial names the code-intelligent command to run instead (grep → catenary grep, ls/find → catenary glob).
• Edits flow through the host's tracked Edit/Write tools, so LSP diagnostics come back automatically when the agent runs catenary diagnostics.

The result is a workflow the agent follows by construction, not by prompt-engineering.

This is enforcement of a workflow, not a security sandbox. The hook is a cooperative contract — a Makefile can still run anything, and Catenary doesn't isolate the filesystem or environment. Its job is narrower and more useful: keep the agent's reads on code-intelligent search and its writes on a tracked path, so navigation is structural and diagnostics are free.

Less context, more signal

A grep-and-read loop pulls whole files into the agent's context window and re-processes them every turn. catenary grep answers with the symbol, its signature, and where it's used — tens of tokens instead of thousands. Diagnostics arrive through catenary diagnostics stdout, so the agent never re-reads a file just to check whether its edit compiled.

The surface

Search — always available, no setup beyond installation:

Command	What it does
catenary grep <pattern>	Symbol, reference, and text search — LSP-enriched within tracked roots
catenary glob <path>	File outlines, directory listings, glob matches

The edit → diagnostics loop — run in the host's shell tool:

# Edit files with the host's native Edit/Write tools. Editing starts
# automatically on the first change to a server-covered file — there is
# no start step.
catenary diagnostics      # print LSP diagnostics for every file you
                          # touched, then clear the set

catenary diagnostics is the end of an edit batch: it opens the modified files on their servers, waits for each to settle, and prints the errors and warnings — like a linter, it's silent on success. For sweeps too broad for per-file edits, reach for native sed -i — the hook resolves its write-set and folds the changed files into the same diagnostics batch.

Workspace roots — manage which directories are indexed:

catenary roots add <path>   # index a directory
catenary roots rm <path>
catenary roots ls

How it fits together

One daemon per host manages a shared pool of language servers. Multiple agents connect over a Unix socket and share those servers — a single rust-analyzer serves every session on the same project. Catenary reaches the agent through four decoupled surfaces; none depends on the others.

agents ──▶  Catenary daemon  ──▶  shared LSP server pool
                                  rust-analyzer · pyright · gopls · …

reached through four decoupled surfaces:

  CLI     grep · glob · diagnostics         — via the host's shell tool
  Hooks   allowlist enforcement             — one PreToolUse hook
  MCP     heartbeat + workspace roots       — no query tools
  TUI     live observability                — protocol & trace traffic