Keep a Markdown copy of your company brain on your computer for coding agents, and ask the brain questions from the terminal.
Coding agents such as Claude Code, Codex, and Cursor are best at reading files. The Hyperspell command line tool plays to that strength. It keeps an up-to-date folder of Markdown pages about your company, projects, people, and decisions on your machine, and tells your coding agents where to find it. Agents read the pages with the tools they already have, without a network call, and can still ask the brain a live question when the pages are not enough.The tool has two parts, installed together:
hyperspell, the sync tool. It runs in the background, keeps the Markdown folder current, and configures your coding agents.
hyperbrain, the query tool. It lets you, or an agent, ask the brain a question, search it, or save a note from the terminal.
In the dashboard, open Settings, then Connect Agents, and choose CLI. The dashboard generates an install command that includes a one-time token tied to you. The token works once and expires after an hour, so generate a fresh one when you need it.
The CLI setup in the dashboard
2
Run it in your terminal
Paste the command into a terminal on your Mac or Linux machine. It looks like this, with your token in place of the placeholder:
The installer sets up an isolated Python environment, installs both tools, saves your credentials, registers the sync tool to start automatically when you log in, and runs a first sync. It refuses to run as root.
3
Check the result
hyperspell status
This shows when the brain last synced, where the files are, and a log of the changes the installer made to your agent configuration.
Prefer to install by hand? The query tool is on PyPI: uv tool install hyperspell-brain or pipx install hyperspell-brain, then hyperbrain login. The sync tool is only distributed through the dashboard install command.
If you install on a second machine, or your credentials expire, run:
hyperspell login
The tool prints a short code and opens a page in your browser. Approve the login there, and the terminal picks it up on its own.The approval page shows the code, the app it is for, and where the request came from. It asks you to confirm that you started the login yourself on your own device. If someone sends you an approval link by email or chat, do not approve it. Codes work once and expire after ten minutes.
A short managed block telling each agent where the brain lives and when to use it. The block sits between two marker comments, and the tool never touches anything outside them.
Claude Desktop and Claude Code configuration
A registration for the Hyperspell MCP server, so those agents can also ask the brain live questions.
Once installed, a coding agent can answer “what does the billing service do and who owns it?” by reading ~/Hyperspell/, and can fall back to hyperbrain ask for anything the pages do not cover.
On a computer with several user accounts, everyone with an account can read the ~/Hyperspell/ mirror. If that is a concern, run the install with --no-visible-mirror, or set visible_mirror = false in ~/.hyperspell/config.toml. Agents then read the private copy instead.
The query tool works for people and for agents alike.
# Ask a question and get a cited answerhyperbrain ask "who owns the mobile release process?"# Search for documents without an answerhyperbrain search "Q3 pricing experiment"# Save something worth rememberinghyperbrain remember "The staging database is refreshed from production every Sunday night."# Check your setuphyperbrain doctor
hyperbrain help --agent prints the whole command surface as one short document, which is handy to paste into an agent’s instructions.
The sync tool checks for a new version of itself and of the query tool once a day and upgrades within the supported range. hyperspell update forces a check. hyperbrain update upgrades the query tool by itself.Other commands you may need:
Command
What it does
hyperspell status
Show sync state, file locations, and recent actions.
hyperspell sync --once
Sync now and exit.
hyperspell search "query"
Search the synced pages locally.
hyperspell uninstall
Remove the tool and its autostart entry. Add --purge to also delete the synced files and credentials.
Some organizations do not want a copy of the company brain sitting on employee laptops. The sync tool supports a lean mode for this. In lean mode it still installs the query tool and registers the MCP server with your agents, so they can ask the brain live questions, but it syncs no pages to disk and removes any it previously synced.Admins can require lean mode for the whole organization from Settings. When that policy is on, every install is lean and the option cannot be turned off on individual machines. Individuals can also choose lean mode for their own install with --no-context-docs.
The install command fails immediately. The token works once and expires after an hour. Generate a new one from the dashboard. If you are on a machine where you are root, the installer stops on purpose; run it as a normal user.Claude Code does not seem to know about the brain. Open a new session so it re-reads ~/.claude/CLAUDE.md, and check claude mcp list shows the Hyperspell server. hyperspell status lists what the installer configured.The pages look stale. Run hyperspell sync --once and then hyperspell status. If the sync tool is not running, hyperspell login re-registers it to start automatically.I want everything gone.hyperspell uninstall --purge removes the tools, the synced files, the credentials, and the managed blocks in your agent configuration files.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.
