SMITHY AGENT
v1.16.0 Install

01 / INSTALL

Install

The fastest path: paste one prompt into your pi agent (or prime-agent). The agent fetches the install guide and does the clone, build, register, restart, and verify for you.

Install with one paste

Paste into pi
Install and configure the smithy-agent extension (works under both the pi and prime-agent harnesses) by following the guide here:
https://smithy-agent.netlify.app/install-guide.md
Read the guide

Prefer to do it by hand? The guide covers clone, build, register, and restart. Requires Node ≥ 25.

02 / ONE PASTE

How it works

What the agent does 3 steps
01

Paste

Paste the prompt into your pi agent (or prime-agent).

02

Fetch

pi fetches the install guide.

03

Install

pi clones, builds, registers the extension, restarts, and verifies.

03 / BY HAND

Manual install

Requires Node ≥ 25 and git. Resolve the clone path once, then reuse it for both harnesses.

Clone · build · register · restart 4 steps
01

Clone

Clone into a stable location and note the absolute path.

git clone https://gitlab.com/mikeysax/smithy-agent.git ~/.local/share/smithy-agent
cd ~/.local/share/smithy-agent && pwd

Use the absolute path. It must start with /, not ~. Reuse it as $SMITHY_DIR below.

02

Build

The build produces smithy-lib first, then the rest. Node ≥ 25 is required.

cd "$SMITHY_DIR" && npm install && npm run build

The build is required — smithy-core's main is ./dist/pi/index.js, so pi will not find the extension without it.

03

Register

Add the literal absolute path to the extensions array in ~/.pi/agent/settings.json. Create the file and the field if they are missing; preserve any existing JSON.

{
  "extensions": ["$SMITHY_DIR/packages/smithy-core"]
}

Replace $SMITHY_DIR with the actual path. Do not leave the $ variable in the JSON. A ~ prefix works on current pi/prime, but the absolute form is what the guide verifies against.

04

Restart

Restart the pi agent so it reloads the extensions list, then run a trivial task.

/smithy add a comment to README.md

Installing for prime too? The same clone and build serve both harnesses — register the same path in ~/.prime/agent/settings.json below.

04 / PRIME AGENT

Prime Agent (dual harness)

smithy also runs under prime-agent, the RLM-native fork of the pi harness — same clone, same build, one extra registration.

  1. 01
    Add the same absolute packages/smithy-core path to the extensions array in ~/.prime/agent/settings.json.
  2. 02
    Run prime once interactively so its Python kernel runtime is set up, then restart and run /smithy as usual.
  3. 03
    Verify with npm run test:live-prime — a live RPC smoke test against the prime binary.

On prime, smithy's subagents (prospector, draftsman, inspector, smith, judge) adhere to prime's tool model: the persistent ipython kernel is their only capability tool — all file, shell, and search I/O flows through it, and their prompts carry a harness appendix mapping tool names to kernel equivalents. The full install guide has the details.

05 / KNOWLEDGE BASE

Knowledge base (optional)

For a codebase-aware memory — symbol search, code-context retrieval, a code graph — also register smithy-mcp-bridge. It spawns the tome MCP server and defers its ~40 tools behind three bridge tools (progressive disclosure). Every agent can consult the graph when the bridge is online, and falls back to grep / find / ast_grep when it isn't. Don't add a separate mcpServers.tome entry — the bridge owns it.

  • tome_search find a tool by keyword
  • tome_describe inspect one tool's schema
  • tome_call invoke a tool by name

06 / VERIFY

Verify the install

Three checks, straight from the install guide.

  • Restart pi so the extensions list reloads.
  • Run /smithy add a comment to README.md and watch the pipeline stream.
  • Read .smithy/plan.md for the recorded plan, adversarial reviews, and verification.

The full install guide covers prerequisites and troubleshooting.