npm package: @murphai/murph
Description: Murph is a personal health assistant you run locally. Install this package to get the murph CLI.
Latest version: 0.2.6

# Murph - Personal Health Assistant

Murph is your personal health assistant.

Install this package to get the main `murph` command and the full local Murph experience: onboarding, vault setup, local assistant chat, inbox capture, parser tooling, and the always-on assistant loop.

The repo implementation happens to live in `packages/cli`, but that is a maintainer detail. For users, `@murphai/murph` is the installable Murph package.

[Repository](https://github.com/cobuildwithus/murph) · [Architecture](https://github.com/cobuildwithus/murph/blob/main/ARCHITECTURE.md) · [Hosted control plane](https://github.com/cobuildwithus/murph/blob/main/apps/web/README.md) · [Hosted execution](https://github.com/cobuildwithus/murph/blob/main/apps/cloudflare/README.md)

If you want a local, inspectable assistant that keeps durable truth in normal files you can read, this is the package you install.

Runtime: Node `>= 24.14.1`.

Supported host setup path: macOS and Linux.

## Install

```bash
npm install -g @murphai/murph@latest
# or
pnpm add -g @murphai/murph@latest
```

## Quick start

```bash
murph onboard
```

`murph onboard` installs or reuses the local parser dependencies, initializes a vault, saves that vault as the default Murph vault for later commands, and walks through assistant, channel, and optional wearable setup.

Once setup is complete, the main commands are:

```bash
murph chat
murph run
murph status
vault-cli inbox doctor
```

`vault-cli` is still available as a secondary alias for the operator surface, but `murph` is the primary command this package installs.

## OpenClaw

If you already run OpenClaw, install the first-party Murph bundle after `murph onboard`:

```bash
openclaw plugins install @murphai/openclaw-plugin
openclaw gateway restart
```

That bundle teaches OpenClaw to call `vault-cli` directly against the same configured vault. It does not create a second Murph assistant runtime inside OpenClaw.

When you need to read from the vault, use this chooser:

- `vault-cli show <id>` for one exact canonical read id, including stable family ids such as `meal_*` or `doc_*`
- `vault-cli list` for structured filtering by family, kind, status, stream, tag, or date range
- `vault-cli search query --text "..."` for fuzzy recall or remembered phrases
- `vault-cli timeline` for chronology across journals, events, assessments, and sample summaries
- `vault-cli memory show` plus targeted `vault-cli knowledge ...` reads for saved user context
- `vault-cli wearables day` or `wearables ... list` for semantic wearable summaries
- family `manifest` commands for immutable import provenance

When you need route distance or duration between two points for a run, walk, ride, or hike, use:

```bash
MAPBOX_ACCESS_TOKEN=... vault-cli route estimate "123 Example St, Melbourne VIC" "St Kilda Beach" --profile walking
```

Add `--elevation` when you want an approximate elevation summary. Geometry stays omitted unless you opt in with `--geometry`.

For durable local synthesis that should keep adding up inside the vault, use the derived knowledge wiki commands:

```bash
vault-cli knowledge upsert --title "Sleep notes" --body "# Sleep notes\n\nMagnesium looked helpful for sleep continuity.\n" --source-path research/2026/04/sleep-note.md
vault-cli knowledge search "sleep magnesium"
vault-cli knowledge list
vault-cli knowledge lint
```

## What you get

- a file-native health vault with canonical writes owned by `@murphai/core`
- local assistant chat, runtime automation, status, outbox, canonical memory, and canonical automation commands
- a non-canonical derived knowledge wiki you can upsert and inspect under `derived/knowledge/**`
- inbox capture, review, backfill, and parser-driven attachment extraction
- optional local device sync through the bundled workspace-private `packages/device-syncd` runtime
- optional local assistant daemon support through the bundled workspace-private `packages/assistantd` daemon

`@murphai/murph` is the installable local Murph product entrypoint. The wider monorepo also contains hosted control and execution apps plus many workspace-private owner packages, but the public npm surface is intentionally small: `@murphai/murph`, `@murphai/openclaw-plugin`, `@murphai/contracts`, `@murphai/hosted-execution`, and `@murphai/gateway-core`.

## From source

If you are developing from a checkout instead of installing the published package:

```bash
pnpm install --frozen-lockfile
pnpm onboard --vault ./vault
```

For package-local CLI iteration, use the source-first test lane:

```bash
pnpm --dir packages/cli test
```

For the explicit built-runtime and package-shape acceptance lane, use:

```bash
pnpm --dir packages/cli verify
# or the repo-composed CLI acceptance entrypoint
pnpm verify:cli
```

If `pnpm` is not available yet, use:

```bash
./scripts/setup-host.sh --vault ./vault
```

## Config defaults

The CLI supports incur's built-in config loading for command option defaults. By default it searches `~/.config/murph/config.json`.

Those incur config defaults are local CLI convenience only. Hosted execution does not snapshot or honor `~/.config/murph/config.json`; portable runtime behavior must live in canonical vault state or typed operator config under `~/.murph/config.json`.

- `murph --config <path> ...` selects an explicit config file
- `murph --no-config ...` disables config loading for a single run
- the published package now ships Incur's native `config.schema.json` so editors can validate and autocomplete those config files

Config files only supply command `options`, following incur's nested `commands` shape. For example:

```json
{
  "commands": {
    "init": {
      "options": {
        "vault": "./vault"
      }
    }
  }
}
```

The shipped schema is the direct Incur output for config defaults only. Command help text, hints, examples, and agent-facing discovery stay on Incur's normal `--help` and `--llms` surfaces instead of a Murph-specific schema extension.

To refresh the shipped schema artifact from the built CLI entrypoint during package work:

```bash
pnpm --dir packages/cli gen:config-schema
```

## Maintainer notes

The package exports the CLI runtime plus assistant helper subpaths from `dist/**`, exposes both `murph` and `vault-cli` bins from the same built entrypoint, and keeps `src/index.ts` as the package entrypoint with `src/bin.ts` as the launcher.

Machine-facing callers should rely on incur's native envelope via `--verbose --format json` instead of a Murph-specific wrapper contract.

Current repo-local package responsibilities include:

- the published command graph and install surface
- CLI-owned command routing, onboarding entry, and built binary launchers
- inbox and device command surfaces that delegate to headless owner packages
- release ownership for the public `@murphai/murph` package and bins

Programmatic assistant, setup, and shared usecase APIs now stay in workspace-private owner packages such as `@murphai/assistant-cli`, `@murphai/setup-cli`, `@murphai/assistant-engine`, and `@murphai/operator-config`. The public npm install story is still `@murphai/murph`; the release flow bundles those private owners into the CLI tarball instead of publishing them as separate npm products.

## Release flow

Release and publish actions remain user-operated. The monorepo release source of truth is `scripts/release-manifest.json`, and the normal entrypoints are:

```bash
pnpm release:check
pnpm release:patch
```

Pre-release and exact-version flows use the same root script:

```bash
bash scripts/release.sh preminor --preid alpha
bash scripts/release.sh 0.1.0-rc.1 --dry-run
```

The release flow bumps the five public packages in the manifest to one shared version, updates `packages/cli/CHANGELOG.md`, writes `packages/cli/release-notes/v<version>.md`, and then creates a repository tag so `.github/workflows/release.yml` can pack and publish the public tarballs in dependency order. Workspace-private runtime packages remain in the monorepo and are bundled into the public tarballs when a public package still depends on them at runtime.

npm trusted publishing is configured per package on npm, not once per repository. Because this monorepo still publishes a small set of `@murphai/*` packages, maintainers should bootstrap those package-level trust bindings before relying on tag-driven release publication:

```bash
pnpm release:trust:github -- --dry-run
pnpm release:trust:github -- --yes
```

Those commands target the current publishable package set in `scripts/release-manifest.json` and bind each package to `cobuildwithus/murph` via `.github/workflows/release.yml`.

If a package is already bound to the wrong workflow or repository in npm, revoke that package's existing trust entry with `npm trust list` and `npm trust revoke`, then rerun `pnpm release:trust:github -- --yes`.