stagingmind
v0.4.0
Published
Write your Staging Mind brief from your own git history, then rehearse the meeting on any device.
Readme
stagingmind (command line tool)
Writes your Staging Mind brief from your own git history and prints a link that opens it on the practice page, on this computer or any device you're signed in on, such as your phone. It never asks a question, so a coding agent (for example Claude Code, including from the Claude app on your phone) can run it for you.
stagingmind login # sign in to Staging Mind in your browser
stagingmind prep # inside your repo: write a brief from your recent commits
stagingmind logout # sign out and forget the saved sign-inAnyone: npx stagingmind login, then npx stagingmind prep inside a repo. In this monorepo: pnpm stagingmind login --api http://localhost:3101 --front http://localhost:3100 from the root (it builds the package first; without the options it talks to stagingmind.dev).
Needs Node 20 or later and git on the PATH. The published package is one bundled file (release/stagingmind.js, built by pnpm --filter ./packages/cli bundle with esbuild), so it has no dependencies: @stagingmind/domain and zod are bundled in.
Publishing
npm login once, then from packages/cli: bump version in package.json, and pnpm publish --access public. prepublishOnly builds the workspace packages, runs the tests and bundles.
Options
| Option | Commands | Meaning |
| --- | --- | --- |
| --since <date> | prep | Commits since this day (2026-10-20, local midnight) or moment (ISO). Default: your last finished Staging Mind session, or 7 days ago |
| --all-authors | prep | Everyone's commits, not only yours (git config user.email) |
| --committed-only | prep | Leave out uncommitted work (changed, staged, deleted and new files), which is included by default |
| --repo <path> | prep | The repository to read. Default: the current folder |
| --vault <path> | prep | Also read this Obsidian vault: the folder holding .obsidian, or a folder with exactly one vault at the nearest level up to 3 levels below it (so a repository with a vault in docs/ works). See Obsidian vaults |
| --private <folder> | prep | A folder in the vault (path inside the vault, any case) that is never listed or read, for example --private Journal --private "Areas/Health". Repeatable; needs --vault; a folder that isn't in the vault is refused, so a typo can't leave notes readable |
| --front <url> | all | The Staging Mind app. Default https://app.stagingmind.dev, or STAGINGMIND_FRONT_URL |
| --api <url> | all | The Staging Mind API. Default https://api.stagingmind.dev, or STAGINGMIND_API_URL |
| --keep <30m|24h|7d> | prep | How long Staging Mind keeps this brief. Default: what you chose on the approval page or in your account (30 minutes if you never chose). 30m is deleted the first time it is opened; 24h and 7d can be opened again until they run out |
| --no-open | all | Only print links. Links are also never opened when the output is not a terminal (a coding agent running the command), because opening the prep link here would use it up |
| -h, --help, -v, --version | | Help and version |
Login
Better Auth's device authorization flow, client id stagingmind-cli. The tool asks the API for a code, prints it with the link FRONT_URL/device?user_code=... (opening it when run in a terminal), where you approve it while signed in, on any device. The approval page shows what prep reads and sends, and asks how long to keep briefs; approving agrees to it, and the tool records that in settings.json. It polls POST /api/auth/device/token (every 5 seconds, longer when asked to slow down) and saves the token, your email and its expiry in %APPDATA%\stagingmind\credentials.json on Windows or $XDG_CONFIG_HOME/stagingmind / ~/.config/stagingmind/credentials.json elsewhere, with the folder 0700 and the file 0600. One sign-in is kept per API address. logout calls POST /api/auth/sign-out with the token and deletes it.
Prep
- Checks the folder is in a git repository and you are signed in.
- Reads the default start date from
GET /api/repo-prep/defaults, counts the matching commits and lists the uncommitted files fromgit status(ignored and secret-looking files left out). The agent's first message names the uncommitted files and asks it to treat them as the newest work. With no commits and nothing uncommitted, it says so and suggests--since(or--all-authors). - Checks you agreed to what prep reads and sends on the approval page (
settings.json); if not, it asks you to runstagingmind loginagain. - Runs the agent: sends the conversation to
POST /api/repo-prep/turn, runs the tools Claude asks for on this machine, sends the results back, and repeats until Claude callssubmit_brief(at most 30 turns). Each tool call prints one line, for example· read apps/api/src/main.ts:1-80. - Checks the submission against
briefSubmissionSchema, thenCodePackBuilderreads the code Claude chose to keep (codeToKeep: files, line ranges and commit patches) through the same tools, up to about 50,000 tokens. - Prints the brief and the code the panel will see (each piece with why it was kept, and the total size).
- Writes
.stagingmind/brief.md, adds.stagingmind/to.git/info/exclude, sends the brief and the code pack toPOST /api/repo-prep/handoffs, and printsFRONT_URL/practice?handoff=<id>, for your account only, on any device. With 30 minutes it works once; with 24 hours or 7 days it can be opened again until then, and is listed under "Briefs waiting for you" on the practice page.
Obsidian vaults
stagingmind prep --vault ~/Brain --private Journal reads the repository as above and the vault too, so you can run it through Claude Code on your computer from the Claude app on your phone and practise with your own notes on the phone.
NodeVaultFileslists the vault's files (path inside the vault with forward slashes, last change and size) and reads them as text. It never writes. It doesn't enter.obsidian,.trash,.git,node_modules, the private folders or linked folders, and leaves out links to files outside the vault;.obsidian/daily-notes.jsonand.obsidian/templates.jsoncan still be read for the daily notes and templates settings.VaultIndexfrom@stagingmind/domainreads the notes (private folders excluded) and prints, for example,Reading notes in Brain: 196 notes, 9 changed since Tue 20 Oct 2026, leaving out Journal.- The agent's first message carries the vault's overview (folders, tags and the titles of recent notes, never their contents), and it gets the notes tools (
recent_notes,search_notes,read_note,linked_notes) next to the git tools. Each notes tool call prints one line like the others, for example· read note Decisions/Queue.md. - The notes Claude keeps (
notesToKeep) come first in the pack, within their share (MAXIMUM_NOTES_PACK_CHARACTERS); the code fills the characters and pieces they leave. The terminal lists "Notes the panel will see" above the code,.stagingmind/brief.mdlists them under "Notes kept for the panel", and the hand-off carries notes and code together (note pieces havesource: "note").
Tools
All run git through execFile, never a shell, in the repository root. Inputs are checked (references can't start with - or contain :, and must name a commit; paths must resolve inside the repository, symbolic links included; pathspec magic is refused). Every result is capped at 20,000 characters with a "truncated" note.
| Tool | Runs |
| --- | --- |
| git_log | git log --shortstat with since (default the prep's), your email unless allAuthors or --all-authors, branch, allBranches (local and remote), paths, maxCount (default 100, at most 300) |
| git_show | git show --stat for one commit, with --patch when includePatch, limited to paths |
| git_diff | git diff between from and to, or from and the working tree; statOnly for the stat |
| list_files | git ls-files (plus new files that aren't ignored, unless --committed-only), under path, matching a pattern glob (*.ts matches at any depth) |
| read_file | A tracked file or new uncommitted file as it is on disk, or startLine to endLine, numbered; binary files refused |
| search | git grep -E -n -I (with --untracked unless --committed-only), at most 20 matches per file, limited to paths, ignoreCase |
Unknown tools and bad inputs come back to Claude as an error result rather than stopping the prep.
Never read: .env*, *.pem, *.key, id_rsa*, id_dsa*, id_ecdsa*, id_ed25519*, anything with credentials in its name, *.p12, *.pfx, *.keystore, *.jks, and anything under .git/. git_show, git_diff and search exclude the same files with pathspecs.
Redacted from every result: sk-... (Anthropic, OpenAI), sk_live_/sk_test_/rk_/pk_ (Stripe), ghp_/gho_/ghu_/ghs_/ghr_/github_pat_ (GitHub), glpat- (GitLab), AKIA/ASIA (AWS), xox?- (Slack), AIza (Google), npm_ tokens, JWTs, private key blocks, and, in configuration files and diffs, long random-looking values after = (at least 24 characters, letters and digits, Shannon entropy of 3.5 bits per character or more).
Code
main.ts (entry), commandLine.ts (options and help), AccountCommands (login, logout), PrepCommand (prep), NodeVaultFiles (an Obsidian vault on disk), DeviceLogin, CredentialStore, StagingMindApi, Repository, RepoTools, SecretFilter, GitRunner, PrepAgentLoop, BrowserOpener, Terminal and briefText.ts. Tests: pnpm --filter ./packages/cli test (the tool tests run real git in a temporary repository).
