Contents

Your tools, ready for your agent.

gu turns the little command-line tools you build for yourself into tools your AI agent can find and use.

Ask your coding agent to publish a tool, or run gu publish yourself. The agent writes a short gu.yaml describing how to call the tool and test it. gu installs a local copy, runs its smoke test, and connects itself to Claude Code and Codex. From then on your agent can use the tool from any project.

Everything runs on your machine, on macOS and Linux. Nothing is uploaded to a registry.

Install

Ask your coding agent

Install github.com/njiedev/gu on this machine: build it with Bun, put dist/gu on my PATH, and run gu register.

Or run this

$ git clone https://github.com/njiedev/gu && cd gu && bun install && bun run build

This builds a single program at dist/gu; ./dist/gu --version should print 0.1.0. Move it somewhere on your PATH and keep it there, since your agent remembers where it lives.

You'll also need

Bun to build gu.
Claude Code and/or Codex. gu connects to whichever is installed.
uv for Python tools, Node.js and npm for Node tools.
git for gu install github.com/….

Quickstart

Ask your agent. Tell it “install gu and publish ~/code/my-tool”. It runs gu publish, writes the card, and installs the tool. You don't need to review any YAML.
gu connects itself. After the first install, gu adds itself to Claude Code (and Codex, if you have it). In your own terminal it asks first.
Just ask for it. Open a fresh agent session and say what you want in plain English. Your agent picks the right tool and runs it.
Commit gu.yaml. Then another machine can run gu install github.com/<owner>/<repo>.

Example

A color-matching script, after gu publish. This is the card:

gu.yamlwritten by your agent

name: color-match
description: Match one image's colors to another
use_when: The user wants an image to look like a reference image
platforms: [macos, linux]
install: { python: "3.12", pip: "." }
tools:
  - name: match
    run: color-matcher
    args:
      source: { type: path, flag: "-s" }
      reference: { type: path, flag: "-r" }
test:
  run: color-matcher -s fixtures/a.png -r fixtures/b.png
  expect: { exit_code: 0 }

And this is what using it looks like, from any project:

Claude Codeany project

Make beach.png match the colors of sunset.png

color-match · matchsource: beach.png
reference: sunset.png
✓ wrote beach_matched.png

Done. beach_matched.png now has sunset.png's warm palette.

Commands

gu publish	Use the existing `gu.yaml`, or get one written, then install, test and connect. Exit code 2 means the card isn't written yet.
gu publish --redraft	Ignore the existing `gu.yaml` and write a fresh one.
gu publish --agent	Have your agent write the card even when an API key is set.
gu install <folder>	Install and test a folder that already has a `gu.yaml`.
gu install github.com/<owner>/<repo>	Clone a repo (optionally `@branch`, tag or commit), show what will run, and install every card in it.
gu status	List installed tools and any problems.
gu register	Connect gu to Claude Code and Codex, or fix a stale path. Usually automatic.
gu serve	The local MCP server your agent talks to. You won't usually run this yourself.

Installed tools live in ~/.gu/tools/. Set GU_HOME to keep them somewhere else.

gu.yaml

One small file per tool, like the one in the example. Your agent writes it, and you can edit it by hand.

use_when	The sentence your agent reads to decide whether this is the right tool.
tools	Each command the agent can call, with its arguments.
install	The Python or Node setup gu prepares for the tool.
platforms	Which systems the tool works on. gu checks before installing.
test	A smoke test on tiny sample inputs, never your real files.

Who writes the card

By default, your coding agent does. With no API key set, gu publish prints the card-writing rules and exits with code 2. The agent writes the card and runs gu publish --yes.

If you'd rather gu wrote cards itself, give it an API model. Claude is the default:

export ANTHROPIC_API_KEY='your key' export GU_LLM=anthropic

Any OpenAI-compatible service works too: set GU_LLM=openai-compatible with GU_LLM_BASE_URL, GU_LLM_API_KEY and GU_LLM_MODEL. This sends a few selected files from the repo to that provider and spends API credits. Installing and serving tools never need a key.

Safety

Tools run as plain argument lists, without a shell, with no keyboard input and with time limits, so a tool that waits for input can't hang your agent. gu never runs brew or apt itself; it tells you what's missing.

gu is not a sandbox. Installed tools run with your permissions, and gu install github.com/… runs that repo's install and test commands on your machine. Only install repos you trust.

FAQ

Does my code get uploaded anywhere?

No. Your tools are installed and run on your machine. Only if you set up an API model does it send a few selected files to the provider you chose.

Which agents work?

Claude Code and Codex are connected automatically. Any other MCP client can launch gu serve.

Which systems?

macOS and Linux.

Why “gu”?

In Reverend Insanity, Gu are small creatures a Gu Master raises and calls on to do one thing well. Same idea: lots of small tools, each with one job, ready when called.