afaraha8403/mental

I type mental
Never reconstruct where you left off.
Local-first continuity for you and your coding agents.
CLI · MCP · Agent Skills — Cursor, Claude Code, Copilot, Codex, OpenCode.
Quick start ·
Docs ·
Research ·
Skill ·
FAQ
Git records what changed. Mental CLI records the rest: the resume, the decision git cannot explain, and what’s still in the air. Your agents write it for you. You type mental when you want the pulse.
text
$ mental
🧠 Ship the pointer, not the dump — open loops: none
Against PLAN.md
Now Resolver landed (today)
Git main (dirty)
feat: UUID bindings survive a repo move
Hops 2
Needs eyes
[verify] Resolver tests not reviewed
In the air
[direction] Tom said ship the pointer
Later
[thread] Come back to MCP
Unsettled
[open] Heartbeat only, no standing TUI
Settled
UUID bindings survive a repo move
One shot. Then exit. Not a menu. Not a todo app. Optional mental dashboard opens a localhost page over the same files.
## Quick start
PowerShell, cmd.exe, Windows Terminal, Git Bash, macOS, and Linux:
text
npm i -g @balacode/mental
mental install
mental doctor
Then cd your-repo and type mental. npm owns the executable on every
platform; mental install copies the agent skill/rule and creates the local data
skeleton. Strict PowerShell policy: use npm.cmd / mental.cmd.
Upgrading from Mental 0.8.1 or older on Windows? Run mental-repair.cmd once
after npm i -g; it quarantines only fingerprinted Mental-owned launchers that
can shadow npm. Journals stay. Upgrade.
After install, agents journal, decide, and record residue while you work. You do not keep a second journal.
The unscoped npm package mental is a different project. Install @balacode/mental. The binary is mental.
### Paste this into your agent
Works in Cursor, Claude Code, Copilot, Codex, and anything that can install a plugin or run a shell:
text
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.