Install

The extracted release archive is the install and your own git repository; every binary ships prebuilt, no Go or Rust needed.

What the quick start leaves out: components, ports, profiles, unattended installs, skill values, deployment, releases. Every setting: Settings; the installed server: Config server.

macOS and Linux

1. Download

   Get smine-<version>-darwin-arm64.tar.gz (Apple silicon) or -darwin-amd64 (Intel) from the latest release and extract it to any folder. It unpacks as smine/: the source tree plus every binary prebuilt under bin/ (bin/PAYLOAD carries the version).

   The binaries are unsigned, and macOS marks everything it downloads as quarantined: Gatekeeper kills a quarantined unsigned binary on launch, the installer included. Clear the flag once before the first run; the installer clears it from the rest of the folder itself.

   xattr -dr com.apple.quarantine smine

2. Run the installer

   Needs git and nothing else. It asks for a preset (Minimal, Full, Custom), the components, the skills (all, none, or a numbered list of the repo's skills to toggle) and whether to keep that skill selection. A kept selection skips the skill question next install; -reset-skills or the Profile page's Installer tick asks again.

   It checks only what the selection needs (a headless token for Routines or the Mining pipeline), shows every step and applies after your yes through bin/configserver -install, which also sets up git: safe.bareRepository explicit, the skillcue merge driver and the pre-commit hook.

   cd smine && ./bin/installer

3. Keep the access token

   On macOS the server runs as LaunchAgent com.smine.configserver on :6001, logs in ~/Library/Logs/; on Linux the installer prints the start command. The first install prints the access token once, the browser's HTTP Basic password; only its SHA-256 digest is stored.

   To rotate it, run the command below. The running server follows the file; an open page reloads and asks for the new token.

   ./bin/configserver -new-credential

4. Prepare the nightly (optional)

   Routines and the Mining pipeline need one thing, a token: the installer offers the one from claude setup-token, or add labeled per-account tokens on the Profile page (Account tokens, ~/.config/claude-routine/tokens/<label>) and pick one per routine in the Configure widget's Token setting. Operations manual: Routines.

Change the selection later

The selection lives in ~/.claude/smine/install.json. Change it under Profile → Installation: Preview changes lists the steps, Apply selection stores the selection over the record and runs them.

Apply keeps every setting override and skill row. Unticking a component puts its dependents in suspended until it is ticked again. An unchanged selection re-runs whatever is missing.

Later re-deploys run from the Overview's Sync widget: settings, hooks or skills alone over the stored selection, or all of them (the whole installation apply).

Unattended installs

From source (development)

./install.sh is the development path: it needs go (and cargo when agentwt or heartbeat is selected), runs the Go installer with go run and builds every binary from the checkout. The same flags apply. A checkout without bin/PAYLOAD is a development checkout: the apply engine and every later Sync build its binaries with go build there.

./install.sh

Seed from your session history

A one-shot bootstrap mines this machine's past sessions: the Welcome page's Bootstrap button, the /smine-bootstrap skill in a session, or bin/routine bootstrap (installed copy smine-routine bootstrap). Run it from the main checkout on main, with a clean tree and the smine peek entry in ~/.claude.json.

Needs BOOTSTRAP_TOKEN_FILE; optional BOOTSTRAP_SINCE=YYYY-MM-DD or BOOTSTRAP_N. BOOTSTRAP_DRY_RUN=1 prints the stage commands and runs nothing. Four stages:

Windows

1. Run smine-setup.exe

   Download it from the latest release and run it. The wizard lays the full source tree and prebuilt binaries into the chosen folder (default %USERPROFILE%\smine) and hands the rest to configserver.exe -install.

2. Get past SmartScreen

   The setup exe is unsigned, so SmartScreen may warn on first run. Choose More info → Run anyway, or unblock it in PowerShell:

   Unblock-File smine-setup.exe

3. Keep the access token

   The first install shows the config server's access token once in a message box (Ctrl+C copies it); the browser asks for it as the password.

4. Log off and back on once

   Or restart the config server, so the routine runtime picks up the new PATH entry: %LOCALAPPDATA%\smine\bin with the smine-*.exe binaries, jq.exe, peek-mcp.exe and the claude shim.

A fresh folder becomes a standalone git repository with no remote. An existing install updates in place: commit local changes first, review the update with git status.

From source

Run .\install.bat from the repo root: a thin launcher running install.ps1 under -ExecutionPolicy Bypass, since a PowerShell script cannot lift the default Restricted policy itself. install.ps1 passes every argument unchanged to the Go installer: -components, -skills, -yes, -preview, -addr, -peek-port, -peek-control-port, -heartbeat-port.

.\install.bat

What configserver.exe -install does

The install logic both paths share:

• Self-elevates once (Register-ScheduledTask needs an elevated token); the task itself runs at logon as your plain user.
• Locates Git Bash and resolves a Claude runtime.
• Registers %LOCALAPPDATA%\smine\bin on your User PATH and copies the smine-*.exe binaries there.
• Sets up git: safe.bareRepository explicit, the skillcue merge driver and the pre-commit hook, as on macOS.
• Applies the selection (install.json) and registers the logon tasks: the config server, and heartbeat when selected (\smine\com.smine.heartbeat, log %LOCALAPPDATA%\claude-routine\logs\heartbeat.log).

Claude runtime

Claude Desktop or the claude CLI (native installer or npm).

Shell and logs

Git Bash is the one Git for Windows supplies; no WSL. The server, the routine wrapper and the heartbeat daemon run fully detached (windowsgui subsystem): no console window, no Quick-Edit freezes.

Follow a log live with Get-Content <log> -Wait.

Multiple macOS profiles on one Mac

All user profiles share the machine's loopback port space, so each install needs its own four ports.

Install each profile with explicit ports:

./bin/installer -addr 127.0.0.1:6002 -peek-port 4243 -peek-control-port 42443 -heartbeat-port 6102

The ports are install-record settings, so plain re-runs and a Profile apply keep them. peek.control_port also fills {{PEEK_CONTROL_PORT}} in the settings template, so each profile's Claude Code exports telemetry to its own peek. peek.claude_home and peek.codex_home point the spawned peek at non-default agent homes.

The install record

~/.claude/smine/install.json holds only overrides, under settings; every other value is the catalog default. Schema 2: an older schema is refused, never imported.

Change a setting on the config server's Smine tab or with smine-rules settings set <component>.<key> <value>. Kind, default and help per setting: Settings.

Skill values

The record's skills object holds the skill rows.

Install-scoped values

The skills sync fills each install-scoped capability into the skill's deployed copy; the first source with a value wins.

The deploy asks each provider <program> interfaces once per run. A capability stays unset when the answer lacks its interface version, the program does not resolve, a path does not exist or the value breaks the value rules; the deploy log and the skill page name the cause.

The skill page's Environment section edits the defaults and, in its advanced disclosure, the provider and capability overrides; it refuses a bad value. A row no skill or provider declares stays, listed as an orphan with a Forget button; configserver -install prints orphan row kept: <key>.

Repo-scoped defaults

Command and path capabilities, and acdsl, have no provider program and are repo-scoped. Their SKILL_* row is only the default for repos that set nothing on the skill's page. A multi-line command keeps its line breaks in the record.

SKILL_FIMPLEMENT_CHECK="make audit"
SKILL_FIMPLEMENT_BUILD="go build ./..."
SKILL_PACKAGECOMMIT_PROJECT_STRIP="bin/acdsl"

bin/acdsl is each ACDSL (Context Linting) repo's own copy, never a PATH program. A vendoring repo tracks it; a repo holding the acdsl source (cmd/acdsl, this checkout) gets it built by the worktree hook on worktree creation and after a base move.

Per-repo values

A repo-scoped value fills at invocation, never at deploy: the deployed SKILL.md reads SKILL_<SKILL>_<KEY> from the session's environment. An unset required one aborts the invocation with a sentence naming the variable, an example and the fix.

Per variable the strongest set value wins: repo value, else skill default, else global default. Example: railroad-review's build and test commands are the repo's SKILL_RAILROADREVIEW_BUILD and _TEST values on its skill page.

The skillenv hook

The skillenv hook belongs to the Skill environment component, its own row under Session hooks; without that component it is off. Two modes:

skillenv: <NAME> = "<value>" (<source>)
skillenv: <NAME> not set — optional, its steps are left out

-repos names the registry, -env-file overrides the target file, -claude-home the Claude home. #disable inject:env turns both modes off for a session. Without the hook (a standalone skill, a bundle user, a session with #disable inject:env) the shell's own exports reach the skill the same way.

Deployment

Deployment runs one way: the repo is the source of truth, nothing is read in place.

bin/configserver -apply

Applies the stored selection (~/.claude/smine/install.json) through internal/install, per component: hook binaries, PATH binaries, settings entries, MCP registration, Codex config, LaunchAgents or logon tasks, routines. A release archive (bin/PAYLOAD present) copies the prebuilt binaries; a development checkout builds them with go build.

configserver -sync-skills

The Go skills sync (internal/skills, also run in process by the config server) writes skills to ~/.claude/skills/ and ~/.codex/skills/, agent definitions to ~/.claude/agents/.

The context deploy engine

internal/contextdocs runs from the Context page's sync form and is replayed by routine bootstrap. It builds one overlay per registered repo under ~/.claude/smine/context/<name>/.

Only the form's Write to Repo box writes into the repository's working tree; nothing is ever committed. It writes the two files. "project markdown" adds the expanded AGENTS.md, the actions chapters, the rules guides and the facts files, and removes a leftover CLAUDE.md -> AGENTS.md symlink. "sync acdsl" adds the reach-covered gate slice via acdsl.Dist: rules, registry subset, policy, prebuilt bin/acdsl and verifier binaries.

Releases

Tagged releases (v*.*.*) run through GitHub Actions (.github/workflows/ci.yml). Every push runs test, test-windows, audit, darwin-payload, windows-payload and installer; on a tag, publish waits for test, darwin-payload and installer and attaches every asset in one shot.

One payload, built by make payload-bin GOOS=<os> GOARCH=<arch> VERSION=x.y.z for every platform: configserver, routine, acdsl, rules, installer, every verifier binary, the fourteen hook binaries and the bin/PAYLOAD marker holding the version. The marker is what makes an extracted archive take its binaries from bin/ instead of building them.

Every payload job, and go build ./... on a windows runner, runs on every push and pull request (version 0.0.0 off-tag), so a broken archive, installer script or *_windows.go file fails CI before a tag exists. make installer-check is the Inno Setup compile locally, against a dummy payload via a dockerized iscc.