# Installing smithy-agent

This guide is **machine-readable**. Follow it step by step to install the
smithy-agent extension. smithy is dual-harness: one clone serves **both**
the pi coding agent and prime-agent (see the Prime Agent section).

There is intentionally no smithy setup bin — this guide IS the installer. The
`smithy setup` command you may see referenced in older docs does not exist as a
real CLI: the `setup-utils.ts` library landed, but no `bin` was ever wired into
`smithy-lib`. Resolve the clone path by hand as described below.

## Prerequisites

- **Node.js ≥ 25** (to build the packages)
- **git**
- the **pi coding agent** (<https://pi.dev>) and/or **prime-agent**
  (<https://www.primeintellect.ai/prime-agent>) installed

## Steps

### 1. Choose a clone location and resolve its ABSOLUTE path

Both harnesses expand a leading `~` in the `extensions` array (verified
against pi 0.84.x and prime 0.8.0 path resolution), but resolve and paste an
**absolute** path anyway — it keeps this machine-readable flow unambiguous
and survives `HOME` differences. Clone-or-pull into a stable location, then
capture the absolute path:

```bash
SMITHY_DIR="$(mkdir -p ~/.local/share && cd ~/.local/share && git clone https://gitlab.com/mikeysax/smithy-agent.git smithy-agent 2>/dev/null || true; cd ~/.local/share/smithy-agent && git pull --ff-only 2>/dev/null || true; pwd)"
```

This clones into `~/.local/share/smithy-agent` (or fast-forwards it if it
already exists), then `pwd` prints the resolved absolute path into
`$SMITHY_DIR`.

Verify it resolved to an absolute path:

```bash
echo "$SMITHY_DIR"   # must start with /, no leading ~
```

### 2. Build

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

The build produces `smithy-lib` first, then the rest. `smithy-core`'s `main` is
`./dist/pi/index.js`, so **the build is required** — pi will not find the
extension without it.

### 3. Register the extension in pi

Edit `~/.pi/agent/settings.json` and add the **LITERAL ABSOLUTE**
`"$SMITHY_DIR/packages/smithy-core"` to the `extensions` array. Create the file
and the `extensions` field if they are missing; preserve any existing JSON.

```jsonc
// ~/.pi/agent/settings.json
{
  "extensions": ["$SMITHY_DIR/packages/smithy-core"]
}
```

> Replace `$SMITHY_DIR` with the actual absolute path you resolved in step 1
> (e.g. `/home/you/.local/share/smithy-agent`). Do **not** leave the `$`
> variable in the JSON. A `~` prefix also works on current pi/prime, but the
> absolute form is what this guide verifies against.

### 4. (Optional) Knowledge base

For the tome knowledge base (symbol search, code-context retrieval, a code
graph), also add `"$SMITHY_DIR/packages/smithy-mcp-bridge"` to the `extensions`
array. Do **NOT** add a separate `mcpServers.tome` entry — the bridge owns it,
and a duplicate would conflict.

```jsonc
// ~/.pi/agent/settings.json (excerpt)
{
  "extensions": [
    "$SMITHY_DIR/packages/smithy-core",
    "$SMITHY_DIR/packages/smithy-mcp-bridge"
  ]
}
```

### 5. Restart pi

Restart the pi agent so it reloads the `extensions` list. (Installing for
prime-agent too? Continue to the Prime Agent section — same clone, same
build, one extra registration.)

### 6. Verify

Run a trivial task:

```
/smithy add a comment to README.md
```

Then inspect the recorded plan, adversarial reviews, and verification:

```bash
cat .smithy/plan.md
```

## Prime Agent (dual-harness install)

smithy-core also runs under **prime-agent** (the RLM-native fork of the pi
harness). The extension API is compatible — prime's loader aliases
`@earendil-works/pi-coding-agent` to its bundled module — so the SAME clone
and build from steps 1-2 serve both harnesses. No second checkout.

### Steps

1. Register the same absolute path in prime's settings (use the literal
   absolute path, same rule as pi):

   ```jsonc
   // ~/.prime/agent/settings.json
   {
     "extensions": ["/home/you/.local/share/smithy-agent/packages/smithy-core"]
   }
   ```

2. Run prime once interactively before asking smithy to spawn subagents —
   prime sets up its Python kernel runtime on first invocation
   (`PRIME_AGENT_KERNEL_PYTHON` overrides the Python env).

3. Restart prime, then verify:

   ```bash
   cd "$SMITHY_DIR" && npm run test:live-prime   # live RPC smoke test
   ```

   Then in prime: `/smithy add a comment to README.md` — the spawned
   agents run their file/shell/search work through the kernel.

### How smithy behaves on prime (by design)

- **Subagents get the kernel as their ONLY capability tool.** prospector,
  draftsman, inspector, smith, and judge receive exactly `ipython` (plus
  `todo_write`/`todo_read` where their allowlists name them — progress
  plumbing, not capability). Every file, shell, search, and verification
  operation flows through the persistent kernel; each agent's system
  prompt carries a harness appendix mapping tool names to kernel
  equivalents (Python file I/O, `!rg`, `!npx tsc --noEmit`, …).
- **Agent definitions are shared.** The frontmatter allowlists in
  `agent-defaults.ts` (and your `.smithy/agents/*.md` overrides) stay the
  single source of truth; the pi→prime translation happens at spawn time
  and is idempotent. `SMITHY_HARNESS=pi|prime` overrides detection.
- **The parent session keeps its full surface**: prime's `ipython` plus
  every smithy-registered tool (`task`, `todo_*`, `/smithy`, `/plan`, …).
  smithy's permission preset allows the kernel (matching vanilla prime,
  which never prompts for its own primary tool).
- **Quests, background tasks, and worktree isolation work unchanged** —
  the orchestration layer is harness-agnostic.
- **smithy-mcp-bridge works on prime too** (tome knowledge base); its
  logs land in `~/.prime/agent/logs/` (override with
  `MCP_BRIDGE_LOG_DIR`). `smithy-update-checker` and `compact-skills`
  are pi-only for now.

### Troubleshooting

- `smithy: tool "ipython" denied by permission policy` — you are on a
  build older than smithy-core v1.9.0 (which added the kernel to the
  permission preset). Re-run `npm run build` in the clone.
- Subagents report no usable tools — same fix: rebuild, so the spawn-time
  translation in `dist/pi/harness.js` is present.
- Startup warnings about `/usage` / `/context` / `/goal` "conflicting
  with built-in interactive command", or "update-checker failed: Theme
  not initialized" — you are on a pre-v1.9.0 build. Both are fixed:
  colliding commands register under `smithy-` aliases under prime
  (`/smithy-usage`, `/smithy-context`, `/smithy-goal` — the bare names
  belong to prime's own built-ins there), and the status-bar painter
  paints UNCOLORED on theme-less hosts (prime's daemon worker forwards
  `setStatus` to the interactive client's footer, so the update + MCP
  indicators still render there). Rebuild.

Design record: `docs/prime-harness-design.md` in the repo.

## Verify the install

There is no smithy setup bin on your PATH, so resolve by hand and confirm the
harness can load the extension:

1. Resolve the absolute path and confirm it is absolute:
   ```bash
   SMITHY_DIR="$(cd /path/to/your/smithy-agent && pwd)"
   echo "$SMITHY_DIR"   # must start with /
   ```
2. The `extensions` value in `~/.pi/agent/settings.json` must be the literal
   absolute `"$SMITHY_DIR/packages/smithy-core"` (a `~` prefix also resolves
   on current pi/prime — verify whichever form you pasted).
3. Self-check (use `grep -F` + `test -d`, **NOT** `node require` — `settings.json`
   is JSONC with `//` comments and `require` throws):
   ```bash
   test -d "$SMITHY_DIR/packages/smithy-core" \
     && grep -F "$SMITHY_DIR/packages/smithy-core" ~/.pi/agent/settings.json
   ```
4. For prime-agent, the same check against its settings:
   ```bash
   grep -F "$SMITHY_DIR/packages/smithy-core" ~/.prime/agent/settings.json
   ```
   Then run `/smithy add a comment to README.md` in the harness you verified
   and check `.smithy/plan.md` exists.