SMITHY AGENT
v1.16.0 Install

01 / FAQ

FAQ

Naming, harness support, removed surfaces, and what it takes to run.

Q

Is this AWS Smithy?

No — unrelated. AWS Smithy is an Interface Definition Language for API design. smithy-agent is named for the blacksmith's workshop (the forge, the anvil, the workers) and is a multi-agent orchestration harness for the pi coding agent (and its prime-agent fork).

Q

Does it work with prime-agent?

Yes. smithy runs under both harnesses from one clone: register the same smithy-core path in ~/.prime/agent/settings.json. On prime, the discipline subagents (prospector, draftsman, inspector, smith, judge) adhere to prime's tool model — the persistent ipython kernel is their only capability tool, and their prompts carry a kernel-mapping appendix. The parent session keeps the control-plane and orchestration surface; capability tool wrappers are not registered under prime (the kernel covers them). See the Prime Agent section of the install guide.

Q

Is this hammer-cli / Hammer.js?

No. Different projects entirely. The name collision is coincidental.

Q

Where's the desktop app / CLI / web frontend?

Removed. smithy-agent today is a dual-harness extension (pi and prime-agent) plus six npm packages. Earlier surfaces (a Tauri desktop app, web frontend, and standalone CLI) were cut. See the website for what ships now.

Q

Can I run two pi sessions on two PRs at the same time?

Yes — by default both can run in the SAME checkout. Each session gets its own 8-hex run tag and its own ledger at .smithy/runs/<tag>/plan.md (plus quest.md and run.json), while .smithy/plan.md is a mirror of the latest run only; /doctor shows your tag, the authoritative ledger path, sibling runs and the git-lock state. Worktree add/remove, merge and copy-back are serialized by a cross-process git lock — if another session holds it the task reports 'another process is merging — retry' and nothing is merged. Set SMITHY_RUN_LOCK=strict to opt back into refusing a second armed run (it names the holder pid and lock path); off disables both locks (unsafe). Same-file edits still conflict. For a separate checkout per PR, create a slot with node scripts/smithy-slot.mjs new <name> (optionally --pr N), cd into .smithy/slots/<name>, and start pi there. npm run smoke:multi-slot verifies the model headlessly — two runs in one dir both arming, strict refusal, and git-lock timeout.

Q

Can I work on several branches at the same time, in one project directory?

Yes — that is what branch workspaces are for. `smithy <branch>` creates a linked worktree for that branch under .smithy/workspaces/ and starts pi inside it, so a second terminal is a second branch with no interference. Name an issue instead and the launcher resolves it: `smithy 412` (or a quoted #412, or an issue URL) checks the workspace registry first, then asks gh/glab, and derives one branch name. Each branch keeps one persistent session — `smithy <branch>` resumes it with -c, and /branch attaches to it in-process via switchSession, so nothing is copied; a branch with no session yet is started with pi -a -c, and --new-session starts a second, independent one. A per-workspace session lock refuses a second live pi/smithy in the same checkout unless you pass --new-session or set SMITHY_NEW_SESSION=1. Typing "work on #412" in chat attaches and continues in one step. The agent can do the same through the branch tool; SMITHY_BRANCH_SWITCH=off turns that model-driven path off.

Q

Do I need npm run build?

Yes. smithy-core's main is ./dist/pi/index.js, so the build is required after cloning (and after editing smithy-core) for pi to pick it up.

Q

What Node version?

Node ≥25 to build the packages. The marketing site itself builds on Node 20.

Q

Does it phone home?

No telemetry. Independent open-source software, MIT licensed. A test:no-telemetry guard runs in CI.