Skip to content
mash

Quick start

You’ll need some existing agent history and a running local Qdrant search service.

1. Install Mash

Section titled “1. Install Mash”

Public release packages have not been published yet. For now, build with Rust:

Terminal window
cargo +stable install --locked --git https://github.com/kojah/mash mash
Release installers and package managers (available after publication)

Homebrew

Terminal window
brew install kojah/tap/mash

Shell — macOS / Linux

Terminal window
curl -fsSL https://raw.githubusercontent.com/kojah/mash/main/install.sh | sh

PowerShell — Windows x64

Terminal window
irm https://raw.githubusercontent.com/kojah/mash/main/install.ps1 | iex

Both scripts verify release checksums. They install to your user’s .local/bin directory; add it to PATH if needed.

Windows package managers — choose one

Terminal window
winget install --id kojah.mash --exact
Terminal window
scoop bucket add kojah https://github.com/kojah/mash
scoop install kojah/mash
Terminal window
choco install mash

apt — Debian / Ubuntu

Terminal window
curl -fsSL https://mashapp.dev/apt/mash-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/mash-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/mash-archive-keyring.gpg] https://mashapp.dev/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/mash.list
sudo apt update && sudo apt install mash

Package channels depend on the release being published to their registry. See installation options for npm, mise, and installer settings.

2. Start the local search service

Section titled “2. Start the local search service”

With Docker installed, run Qdrant with persistent storage:

Terminal window
docker run -d --name mash-local-qdrant --memory 2g \
  -p 127.0.0.1:6333:6333 -p 127.0.0.1:6334:6334 \
  -v mash-local-qdrant-data:/qdrant/storage qdrant/qdrant:v1.19.1

Mash uses these local addresses by default. Keep Qdrant running while indexing or searching; after stopping the container, use docker start mash-local-qdrant. Custom endpoints and setup details →

3. Connect your histories

Section titled “3. Connect your histories”
Terminal window
mash init

Mash finds supported histories in their usual locations and indexes the last 90 days. It also connects Mash to the Claude Code and Codex CLIs it finds. Restart those agents, then try asking:

“Use Mash to find where we discussed the database migration.”

Search works with words and phrases out of the box. For search by meaning, run mash models install before mash init to add the optional local models. Already initialized? See model setup. The history plugin’s hooks also require Python 3.9 or later.

Try it

Section titled “Try it”
Terminal window
mash search "database migration"
mash list-chats --provider codex --limit 10
mash view MESSAGE_ID --context 3

Use a message ID returned by search in the last command. CLI results are JSON; your connected agent can use the same operations through MCP.

Prefer browsing? Start the local, read-only dashboard:

Terminal window
mash dash

Open the address it prints to browse chats, search history, and read transcripts.

Keep it up to date

Section titled “Keep it up to date”
Terminal window
mash index                 # Pick up recent changes
mash index --all-history   # Include history older than 90 days
mash status                # Check setup and index readiness

The history plugin also starts a throttled background refresh when an agent session begins. For continuous updates, run mash index --watch in a separate terminal. Synchronization details →

Privacy

Section titled “Privacy”

With the default local setup, indexing and search stay on your machine. Sharing history and using remote embedding APIs are optional.

Mash masks recognizable credentials in results by default, but detection is best effort. Local history and exports can contain sensitive text; treat backups like the original chats. Mash never modifies the agent’s source history. Privacy and redaction →

Configuration

Section titled “Configuration”

mash init writes a TOML configuration. Use the configuration guide to choose history locations, search defaults, or remote embeddings. To search across machines, set up an optional shared index.

Upgrading an existing installation? Read the upgrade guide before replacing an existing installation.

Learn more

Section titled “Learn more”
I want to… Guide
Narrow a search by project, provider, or date Search and filters
Connect or troubleshoot an agent Agent integrations
Browse or save a transcript Dashboard
Find missing or stale history Troubleshooting
Search across my machines Shared index
Back up, restore, or upgrade Upgrades and backups
See all commands CLI reference
Configure an MCP client MCP reference
Understand indexing and models Indexing

Documentation website · All guides · License