v0.13.3 ยท @balacode/mental

Picking up where your AI agents left off

Local-first continuity for you and your coding agents.Git records what changed. Mental records the resume, the decision git cannot explain, and what is still in the air. Your agents write it. You type mental for the pulse.
GitHub
Then mental install and mental doctor.
Mental dashboard Today view with resume line, git, attention lanes, and journal activity from a real local session
The Mental dashboard (localhost, read-only) over the same files the CLI writes.
HOW IT WORKS

Three steps. Then you type mental.

Step 1

Install the CLI

npm i -g @balacode/mental, then mental install. That copies the skill and a tiny always-on rule into your agent hosts. npm owns the executable.
Step 2

Agents write at a task boundary

They journal a short summary, record a decision that constrains the future, and capture residue still in the air. Not every chat turn. Not a hidden hook.
Step 3

You type mental

One pulse, then exit: resume, last outcome, git, hops, needs eyes, in the air. Optional mental dashboard opens a localhost page over the same files.
FEATURES

What it actually stores

Honest to the current CLI. Nothing here is a hosted product.
Journal

Short summaries at the end of a task

One journal section per real task boundary, not per chat turn. Title, body, and a required resume line. Agents write it. You read it later.
Heartbeat

A pulse, not a dump

mental / heartbeat --json is resume, last outcome, git, hops today, needs eyes, in the air, later, unsettled and settled. Then it exits.
Attention

Residue still in the air

direction, concern, thread, or verify. Capped at 7 on the heartbeat. --status later is come back to this, not a second journal.
Decisions

Why a choice constrains the future

Git records what changed. A decision file records why. Same title updates the existing file. Closing it keeps the path as identity.
Search

Local search over your files

Query the derived SQLite index (rebuildable). Markdown stays the source of truth. Deleting the db loses nothing.
Dashboard

A localhost page over the same files

mental dashboard is optional, read-only, loopback only. Today, attention, decisions, library, and a map. Agents still use --json.
Skill

Loads in your agent hosts

mental install copies the procedure into Cursor, Claude Code, Copilot, Codex, and OpenCode paths. The plugin is discovery. npm is the executable.
THE REAL UI

Dashboard and CLI, from this repo

Screenshots below were captured from Mental CLI v0.13.3 running locally. Not mockups.
Mental dashboard Attention view listing verify and later residue from a real local session
Attention: residue that outlives a chat (verify, direction, thread, later).
Mental dashboard Decisions view with one open decision and one decided item from a real local session
Decisions: why things are the way they are.
Mental dashboard Library view showing journal, decisions, attention, and notes from a real local session
Library: journals, decisions, attention, and notes in one catalog.
Terminal screenshot of mental heartbeat showing resume, git, needs eyes, and residue
mental heartbeat
Terminal screenshot of mental --help listing daily, lookup, write, identity, and setup commands
mental --help
Terminal screenshot of mental park encoding an interruption and printing a heartbeat
mental park encodes an interruption, then prints the pulse.
PRIVACY

What leaves your machine

No account. No upload of your journals. Local-first. Default store is ~/.mental/ (never commit). Project ./.mental only after mental local, and it must be gitignored. Never store secrets, tokens, or private keys. Uninstall does not delete OKF files unless you type DELETE.

Optional npm update check

Ordinary commands may spawn npm view @balacode/mental version when a local cache is stale, so they can tell you npm is ahead. Cache file: npm-latest.json under ~/.cache/mental (or $XDG_CACHE_HOME/mental). 24h while this CLI matches cache, 7d while already behind. A failed view backs off 15 minutes. TTY prints the hint at most once per day. Heartbeat never checks. mental doctor still checks live. MENTAL_SKIP_UPDATE_CHECK=1 skips the network. Only the package version string is fetched, not your notes.

Optional decision-model providers

Off until you store a key. Mental can use TypeSafe Jev, OpenAI Decisions, Cloudflare Clef, or a custom TypeSafe-shaped endpoint as a typed judge (search recovery, similar-to-existing hints, proposed links, tags, brief ranking). Keys are read only from ~/.mental/config.json (mode 0600), never from environment variables, and are never printed or sent over MCP. Notes are not uploaded unless you opt into a provider. Personal-slice notes are included unless you set option decide personal off. It fails open. Writes happen only with explicit --apply on high-confidence results.Optional MCP, session hooks, and time tracking are default off.
INSTALL

Three commands

PowerShell, cmd.exe, Windows Terminal, Git Bash, macOS, and Linux. Node.js 22.13 or newer. Zero runtime npm dependencies.
npm i -g @balacode/mental
mental install
mental doctor
Then run mental install and mental doctor. The unscoped npm package named mental is a different project. Install @balacode/mental. The binary is mental.After that, paste the install block from the README(opens in new tab) into your agent, or follow host plugin steps in the docs(opens in new tab). Existing Windows installs from Mental 0.8.1 or older run mental-repair.cmd once after npm updates.
FAQ

Short answers

No. After install, agents write it on your behalf. You type mental when you want the pulse.
No. Mental CLI is project continuity, not conversation memory. Markdown files are the source of truth. There are no embeddings as source of truth, and there is no cloud store.
No. Git still records what changed. --against PLAN.md points at the plan. Mental holds the small amount those systems cannot see: resume, decisions, and residue.
No. Agents journal at task boundaries, real decisions, and residue in the air. Session hooks stay off until you run mental hooks on.
park encodes an interruption mid-hop. handoff is a planned close (journal plus heartbeat). pulse is a compact cross-project overview. The cheap mid-chat reload is still mental / heartbeat --json.
Run npm i -g @balacode/mental, then mental install, then mental doctor. Journals stay. From a git checkout: npm run mental -- install.
Agents continue the coding task and mention the install block. They never execute a .mjs file directly. Fail open.
Default store is ~/.mental (never commit). Project ./.mental only after mental local. Uninstall does not delete OKF files unless you type DELETE.
Only if you turn it on with mental option track on. Default off. Hours never go in git.
README(opens in new tab)Docs(opens in new tab)GitHub(opens in new tab)npm(opens in new tab)MIT license(opens in new tab)
Mental CLI v0.13.3. Local-first. No account. MIT.