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
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 Prefer to do it by hand? The guide covers clone, build, register, and restart. Requires Node ≥ 25.
02 / ONE PASTE
How it works
Paste
Paste the prompt into your pi agent (or prime-agent).
Fetch
pi fetches the install guide.
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
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.
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.
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.
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.
- 01 Add the same absolute
packages/smithy-corepath to theextensionsarray in~/.prime/agent/settings.json. - 02 Run prime once interactively so its Python kernel runtime is set up, then restart and run
/smithyas usual. - 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_searchfind a tool by keyword -
tome_describeinspect one tool's schema -
tome_callinvoke a tool by name
06 / VERIFY
Verify the install
Three checks, straight from the install guide.
- Restart pi so the
extensionslist reloads. -
Run
/smithy add a comment to README.mdand watch the pipeline stream. -
Read
.smithy/plan.mdfor the recorded plan, adversarial reviews, and verification.
The full install guide covers prerequisites and troubleshooting.