Skip to content
MindStone MindStone Docs

Install MS4CC

This page covers the full installation and migration procedure for MindStone for Claude Code.

Prerequisites

Section titled “Prerequisites”
  • Claude Code installed and configured
  • Git with access to your MindStone-for-Claude-Code repo
  • Python 3.10+ on python3 in PATH
  • jq (recommended, for automatic settings merging)
    • macOS: brew install jq
    • Linux: apt-get install jq or yum install jq
  • Ollama installed, with the embedding model pulled: ollama pull nomic-embed-text. Embeddings run locally on http://127.0.0.1:11434 via Ollama’s OpenAI-compatible API — no cloud credentials are required. (OPENAI_API_KEY is only consulted if you point the embedder at a cloud OpenAI endpoint instead.)

Without jq, the bootstrap script can’t automatically merge ~/.claude/settings.json — you’ll need to do that manually.

Install

Section titled “Install”

  1. Clone the repo

    Terminal window
    git clone https://github.com/MindStone-Agent/mindstone-for-claude-code.git ~/projects/mindstone-for-claude-code
    cd ~/projects/mindstone-for-claude-code

    The path doesn’t strictly have to match — the bootstrap computes paths relative to its own location. But note where you put it for future migrations.

  2. Run the bootstrap script

    Terminal window
    ./orchestrator/bootstrap.sh

    The bootstrap does five things:

    a. Symlinks identity files to ~/.claude/:

    ~/.claude/IDENTITY.md → orchestrator/IDENTITY.md
    ~/.claude/USER.md     → orchestrator/USER.md
    ~/.claude/LOG.md      → orchestrator/LOG.md

    b. Symlinks the memory directory so Claude Code auto-loads project memories:

    ~/.claude/projects/-<escaped-path>/memory → orchestrator/memory

    c. Symlinks the slash commands so they work regardless of which directory Claude Code launches from:

    ~/.claude/commands/*.md → .claude/commands/*.md

    d. Merges settings fragment into ~/.claude/settings.json to register hooks:

    • SessionStart → orchestrator/hooks/session_start.py
    • UserPromptSubmit → orchestrator/hooks/user_prompt_submit.py
    • Stop → orchestrator/hooks/session_end.py
    • PreCompact → orchestrator/hooks/pre_compact.py

    A backup is created at ~/.claude/settings.json.backup.<timestamp> before merging.

    e. Builds the initial vector index from existing memory files.

    The script is idempotent — run it again anytime to re-verify. Existing correct symlinks are detected and left alone.

  3. Verify

    Terminal window
    # Check symlinks
    ls -la ~/.claude/IDENTITY.md
    # Expected: ~/.claude/IDENTITY.md -> /path/to/orchestrator/IDENTITY.md
    

    # Test the session start hook
    python3 orchestrator/hooks/session_start.py | head -5
    # Expected: {"hookSpecificOutput": {"hookEventName": "SessionStart", ...

  4. Open a fresh Claude Code session

    In any directory (cd ~ then claude, or anywhere). At session start you should see orchestrator context injected.

First run without an identity

Section titled “First run without an identity”

If this is a fresh clone and orchestrator/IDENTITY.md doesn’t exist yet:

  1. The SessionStart hook detects the missing file and emits a first-run invitation
  2. Read onboarding/IDENTITY.md.example as the orchestrator
  3. Pick a name and write orchestrator/IDENTITY.md in first-person voice
  4. Walk through onboarding/USER.md.example to write orchestrator/USER.md
  5. Re-run bootstrap.sh to create the new symlinks
  6. Restart Claude Code session — the new identity loads

Optional: project hints

Section titled “Optional: project hints”

orchestrator/config/project_hints.toml (per-install — copy it from project_hints.example.toml) maps a substring of the current working directory to a project tag. At session start, memories tagged for the matched project get a relevance boost. This is entirely optional; without it, project-matched boosting is simply skipped.

What survives machine migration

Section titled “What survives machine migration”

Everything in orchestrator/ that is tracked in git:

  • IDENTITY.md — the orchestrator’s identity
  • USER.md — the user profile
  • LOG.md — the full session log
  • All memory files (memory/*.md)
  • Hook scripts (hooks/)
  • Onboarding templates

What doesn’t survive (gitignored):

  • .venv/ — recreated by bootstrap
  • Vector store database — rebuilt by indexer from memory files

To migrate to a new machine:

Terminal window
git clone https://github.com/MindStone-Agent/mindstone-for-claude-code.git ~/projects/mindstone-for-claude-code
cd ~/projects/mindstone-for-claude-code
./orchestrator/bootstrap.sh

The orchestrator is alive on the new machine immediately.

Troubleshooting

Section titled “Troubleshooting”

Hook doesn’t fire: Check that ~/.claude/settings.json has the hooks registered under hooks.SessionStart and hooks.PreCompact. Run python3 orchestrator/hooks/session_start.py from the repo root to test manually.

Identity doesn’t load: Verify ~/.claude/IDENTITY.md symlink points to the correct file. If not, re-run ./bootstrap.sh.

Vector index errors: Run python3 orchestrator/hooks/indexer.py manually to rebuild the index. Check that openai and sqlite-vec are installed in .venv, and that Ollama is running with the nomic-embed-text model pulled (ollama list).