Install Mental CLI

Mental CLI is @balacode/mental on npm. The binary is mental.

The unscoped package mental is a different project. Do not install that one.

Node.js >= 22.13. Zero runtime npm dependencies.

Fast path

PowerShell, cmd.exe, Windows Terminal, Git Bash, macOS, and Linux:

npm i -g @balacode/mental
mental install
mental doctor

npm puts mental on PATH. mental install does not reinstall or rewrite the CLI; it copies the skill and a tiny always-on rule into each host’s documented path (~/.claude/rules, ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/rules, ~/.agents, and OpenCode AGENTS.md when it already exists), and creates a ~/.mental skeleton. Each copy names that host’s --via token (claude-code, cursor, codex, opencode); copies shared by several hosts (~/.agents, .github/skills) say --via <host>. When the Cursor plugin is installed it already ships the rule, so install skips (and removes) ~/.cursor/rules/mental.mdc rather than load it twice. install never creates OpenCode’s ~/.config/opencode/AGENTS.md: while it is absent OpenCode reads ~/.claude/CLAUDE.md, and creating it would hide whatever else lives there. Create it yourself and re-run mental install if you want OpenCode’s own block. mental install --project writes only the repo dests (.github/skills/mental and .cursor/rules/mental.mdc). Under a PowerShell policy that blocks npm-generated .ps1 launchers, use npm.cmd and mental.cmd explicitly.

That skill is what makes agents journal, decide, and record residue for you. You do not keep the log by hand. It does not turn on hooks or MCP, and it does not delete journals.

Upgrade (already installed)

Journals, decisions, notes, identity, and time data stay.

Existing Windows installs from Mental 0.8.1 or older run the repair once:

npm i -g @balacode/mental
mental-repair.cmd
mental install
mental doctor

mental-repair.cmd has a distinct npm bin name, so the legacy mental cannot shadow it. It fingerprints old Mental-owned launchers under ~/.local/bin, quarantines them under ~/.mental/migrations/cli-shims, verifies npm’s current launcher, and restores them if verification fails. Unknown files are preserved. If PowerShell blocks .ps1, use npm.cmd and mental.cmd for the other lines.

macOS, Linux, Git Bash, and already-migrated Windows installs:

npm i -g @balacode/mental
mental install
mental doctor
mental --version

For a published install, mental --version should match npm view @balacode/mental version (no leading v).

What that does:

1. npm i -g updates the npm-owned executable and launchers.
2. Existing Windows users run mental-repair.cmd once to remove Mental 0.7/0.8’s second launcher source.
3. mental install recopies the skill and always-on rule so agents match this CLI. It does not self-update the executable, turn on hooks/MCP/time tracking, or refresh the host plugin cache.
4. The derived search index (${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.sqlite) rebuilds on the next search or write when the index version changes. mental reindex is optional.
5. mental doctor reports PATH, npm lag, copied-skill lag, and host-plugin lag.

From a git checkout (unpublished commits on this tree):

cd /path/to/mental
npm run mental -- install

npm run mental always launches Node. Never run a .mjs file as a command — Windows ignores the shebang and shows “how do you want to open this file?”.

That checkout is the source of truth until you publish. It does not replace PATH with an older registry build.

Agents after this CLI: mental decide --title create requires --body. Search JSON includes tokens and op. Journal hops may appear as journal/YYYY-MM-DD.md#HH:MM. Heartbeat lists Later for --status later residue. Existing decision files on disk are unchanged.

Plugin: after a release, also update the host plugin (Claude / Copilot marketplace update, Cursor reload). mental install does not refresh that cache. mental doctor warns when it is behind.

Paste this into your agent

Copy the block into Cursor, Claude Code, Copilot, Codex, or any other coding agent:

Install Mental CLI with npm. Do not clone the GitHub repo to install. Do not install from a git clone or plugin cache. Never run a .mjs file — Windows will ask what to open it with.

Fresh install (PowerShell, cmd, Windows Terminal, Git Bash, macOS, Linux):
  npm i -g @balacode/mental
  mental install
  mental doctor

Existing Windows install from Mental 0.8.1 or older (one-time migration):
  npm i -g @balacode/mental
  mental-repair.cmd
  mental install
  mental doctor
  (If PowerShell blocks scripts, use npm.cmd and mental.cmd explicitly.)

Mental CLI is a local-first continuity layer. Git records what changed; Mental records where we left off, why a decision was made, and what is still in the air. After install, you write it on my behalf — I do not journal by hand.

The repo is an Agent Plugins 1.0.0 package (https://agent-plugins.org/specification): plugin.json at the repo root, skills-only. Hosts load skills/mental-setup (install the CLI). The full procedure lives in skill/mental and is copied by `mental install` — not plugin-discovered. Native plugin does not start MCP. Do not start a plugin MCP server.

If this client has a native plugin install, use only that host's flow (do not run other hosts' `/plugin`, `copilot plugin`, or Command Palette steps from this session). npm owns the executable; `mental install` only refreshes the copied skill/rule/config. Run the fresh-install block, or the Windows migration block for an existing 0.8.1-or-older install.

The plugin is discovery. npm is the source of truth for the executable; the install command is the source of truth for the copied procedure. After doctor, re-run `mental doctor --json`. If anything is not ok that `--fix` can repair, run `mental doctor --fix --json` once (home skills/rules + git excludes only — never `--project` or optionals). Then tell me remaining checks. Follow the Mental skill copied by install — not the plugin bootstrap.

Missing Mental must not block my coding task (fail open): continue the task, then tell me to run the fresh-install block. Never execute the package's .mjs file directly.

After doctor, ask whether I want optional hooks or time tracking, and whether MCP is needed for this client. Give a one-liner for each, then wait — never run `mental option … on` until I say yes this turn.

- hooks: session-start snippets so a new chat loads Mental status (default off)
- MCP: register `mental serve` for tool-only agents that cannot shell the CLI (skip if this client can run `mental`)
- time tracking: optional automated project record — wall/billable, private + customer-ready descriptions, dated client export (default off)

Install as a plugin (you, this host)

These steps are for a human in that client. Do not paste this whole list into an agent — it will run the wrong host’s commands. The agent paste above stays gated: this client only, then mental install.

Plugin install loads the setup skill from a git clone the host caches. It does not start MCP. Install the CLI with npm, then run mental install so the full procedure and tiny always-on rule land on this machine. Upgrading the CLI does not refresh that cache — after a release, update the plugin in the host. mental doctor warns when a host plugin or a copied skill is behind the CLI.

Cursor — Customize → Plugins → install. From GitHub today: + Add / install from source with https://github.com/afaraha8403/mental, or symlink for local load:

mkdir -p ~/.cursor/plugins/local
ln -sfn /path/to/mental ~/.cursor/plugins/local/mental

Then reload the window. /add-plugin mental is the marketplace slash after Mental CLI is listed on cursor.com/marketplace — it is not a documented GitHub-URL installer. Cursor CLI has no marketplace install (--plugin-dir only). Teams/Enterprise: Dashboard → Plugins → Import from Repo.

Claude Code — in a session (opens the plugin panel):

/plugin marketplace add afaraha8403/mental
/plugin install mental@mental

From a terminal (no TUI; what to use when scripting):

claude plugin marketplace add afaraha8403/mental
claude plugin install mental@mental

After a release: claude plugin marketplace update mental then claude plugin update mental@mental, then restart.

In-session panel (Claude Desktop and Claude Code 2.1.287+). The Claude plugin also ships a Claude Code mod that shows Mental inside the session. In the Claude Desktop app it works in the Code tab for local sessions (not WSL or cloud sessions); check the version with /status.

• Band (terminal) — two rows above the prompt: the resume point, a live pulse while the agent works, open attention and decision counts, and a short receipt each time Mental writes (park, handoff, decision, attention). It steps aside while a survey is showing and drops to one row when the prompt area is short.
• Claude Desktop — a Mental button with the brain logo sits in the prompt footer and shows the status (Idle, Working, how many items need you). Click it, or type /mental, to open the side panel: the resume point, this session’s elapsed time, turns, files and context, the attention items that need you, the files touched this session, what Mental recorded, and recent guardrail decisions. Park, Hand off, Ask Claude and Refresh send a real message to Claude, and the Dashboard card opens the full dashboard in your browser. The panel updates itself every few seconds (a small dial counts down to the next refresh), cards animate in when it opens, and their order follows the session: what needs you first, the way out near the context limit, live numbers while Claude works. The panel reopens if you left it open. A Browse row opens your Journals, Decisions, Notes, Threads, or the last hand-off as a list; click an item to read it, and Back steps out, like the dashboard. A concern shown in the footer has a Hide button that hides it there only; it stays in the panel and in Mental.
• /mental (terminal) — toggles a pane with Now, Residue, Decisions, Session (files touched, turns, context), and Time (Track sit-downs, when Track is on) tabs (n r d s t). Park (p) and Handoff (h) put the request in the prompt so the agent records it through the skill. The panel itself never writes. In Claude Desktop it docks as a side panel beside the chat. In a terminal it docks in fullscreen at 110+ columns and opens as a dialog otherwise.

The panel reads mental heartbeat --json --passive. --passive does not ping a running Track timer. Older Claude builds ignore the mod and the rest of the plugin works. mental doctor reports claude-panel with the Claude Code version it found on PATH (Claude Desktop bundles its own; use /status there). To try it from a checkout: in a terminal, claude --plugin-dir /path/to/mental; in Claude Desktop, add "env": { "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/mental" } to ~/.claude/settings.json and restart the app. Then type /mental.

The panel contract, the Cursor sidebar, and the localhost page: Host UIs, Dashboard. Decision-model keys: Decision models.

VS Code — Command Palette → Chat: Install Plugin From Source, then https://github.com/afaraha8403/mental.

GitHub Copilot CLI:

copilot plugin marketplace add afaraha8403/mental
copilot plugin install mental@mental

After a release: copilot plugin marketplace update then copilot plugin update mental.

Mental CLI is packaged as a portable Agent Plugins 1.0.0 plugin — the vendor-neutral format maintained by Amazon, Cursor, Microsoft, OpenAI, and Vercel. Compatible clients load the same directory.

Cursor extras live in .cursor-plugin/plugin.json (logo). Claude Code extras live in .claude-plugin/plugin.json (displayName: Mental) and .claude-plugin/marketplace.json. Rules and hooks are not portable v1 components — they still come from mental install / mental hooks on.

From a git checkout

For unpublished commits on this tree (developers). Agents must use npm i -g @balacode/mental, not a clone.

cd /path/to/mental
npm run mental -- install --json

npm run mental always launches Node. Never execute a .mjs file as a command.

A git checkout installs that tree and does not clobber it with the registry.

What mental install does

npm owns and upgrades the global mental executable. mental install refreshes the procedure/rule/config and removes leftover Balakit Mental skill/rule copies (the old npx balakit doctor pointer) so they cannot fight the new rule. It never installs or updates the executable. Already installed? See Upgrade.

Optional:

mental install --mcp    # register `mental serve` in ~/.cursor/mcp.json + ~/.claude.json (+ ~/.codex/config.toml if present)
mental hooks on         # session-start hooks (Cursor + Claude Code); default off
mental option track on  # per-UUID sit-down clock; never from install paste unless the user asked
mental doctor           # PATH, bindings, ignore, skills, npm update, host plugin lag, optionals[]
mental doctor --fix     # safe repairs: home install + git excludes (never --project)
mental doctor --fix-ignore   # add .mental/ and .mental-id to your global git excludes

mental hooks on writes mental hooks session-start cursor to ~/.cursor/hooks.json and mental hooks session-start claude-code to ~/.claude/settings.json (mental.cmd … on Windows). It resolves through PATH, so it survives a Node reinstall, and prints the shape each host injects (additional_context for Cursor, hookSpecificOutput.additionalContext for Claude Code), capped at 4,000 characters of valid JSON. Hooks written by 0.12.1 and older pointed at an absolute hooks/session-start.sh; that script still works, and mental install rewrites those entries when hooks are on.

Install and doctor JSON include optionals[] (id, enabled, scope, command, isNew, needsConsent: true). After doctor, re-run mental doctor --json, then mental doctor --fix --json once if --fix can repair remaining errors. Then ask about hooks and time tracking, and whether MCP is needed, with a one-liner each. Do not pass --hooks / --mcp / --track until the user says yes this turn.

Time tracking is off by default. When enabled, agents generate private and customer-ready descriptions from current work, clock wall/billable time, and refresh the record at park, journal, or handoff. Billable defaults to wall. Genuine ambiguity uses one plain-text draft prompt with short single-select options through the host’s native question renderer, or the same numbered-text fallback. --new starts another clock. Customer exports contain dated work descriptions and hours, never private detail. It does not reconstruct hours from git, guess a duration, or print hours on the TTY pulse. Hours live in bundle time.sqlite (never git). The track skill is copied from optional/mental-track/ only when track is enabled — not from plugin skills/. Full contract: What time tracking can and cannot do.

Uninstall

mental uninstall
mental uninstall --delete-data --confirm DELETE

Uninstall removes skill / rule / hooks / MCP / mental-track copies. ~/.mental stays unless you type DELETE (time.sqlite stays with OKF).