Is Cowork History safe to install?

SaferSkills independently audited Cowork History (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

README.md · 1 file

README.md5.7 KB · Markdown

Cowork History MCP

An MCP (Model Context Protocol) server for searching and browsing your Claude conversation history stored in ~/.claude/. Works with both Claude Code and Cowork conversations.

Features

Hybrid Search - Combines multiple search methods for best results:
SQLite FTS5 - Fast full-text search with BM25 ranking
macOS Spotlight - Leverages system content indexing via mdfind
Vector Embeddings - Semantic similarity search (optional, requires Ollama)
Smart Path Reconstruction - Recovers actual filesystem paths via probing (not heuristic guessing)
Persistent Index - SQLite database with incremental updates for fast queries
Ollama Setup Tools - Automated installation and configuration for embeddings

Installation

Option 1: Claude Desktop (One-Click Install)

Download cowork-history.mcpb from the latest release and double-click to install.

Option 2: Via uvx (Recommended for CLI)

uvx cowork-history

Option 3: Via pip

pip install cowork-history

Option 4: Manual Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cowork-history": {
      "command": "uvx",
      "args": ["cowork-history"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

Quick Start

Once installed, Claude can search your conversation history:

"What did we discuss about authentication last week?"
"Find the conversation where we debugged the payment webhook"
"Show me my conversations in the my-project folder"

Available Tools

Search & Browse

Tool	Description
`cowork_history_search`	Search conversations using hybrid search (FTS + Spotlight + vector)
`cowork_history_list`	List recent conversations, optionally filtered by project
`cowork_history_get`	Get full content of a specific conversation by session ID
`cowork_history_projects`	List all projects with conversation history
`cowork_history_stats`	Get statistics and search capability status
`cowork_history_reindex`	Rebuild index and optionally generate embeddings

Ollama Setup (for Vector Search)

Tool	Description
`history_system_check`	Check system requirements for Ollama
`history_setup_ollama`	Install Ollama via Homebrew (macOS)
`history_setup_ollama_direct`	Install Ollama via direct download (no Homebrew)
`history_ollama_status`	Check Ollama status and embedding model availability

Search Modes

The cowork_history_search tool supports multiple search modes:

Mode	Description
`auto` (default)	Uses all available methods, best results
`fts`	Full-text search only (fastest)
`spotlight`	macOS Spotlight only
`vector`	Semantic similarity only (requires Ollama)
`hybrid`	Explicit combination with ranking

Search Examples

"authentication bug"           → finds conversations with both words
"how to deploy"                → semantic search finds related discussions
"\"exact phrase\""             → exact phrase matching
project:"my-app" "database"    → filter by project

Enabling Vector Search

Vector search provides semantic similarity matching (finding related concepts even without exact keywords). It requires Ollama with an embedding model.

Quick Setup

Ask Claude to set it up for you:

"Set up Ollama for vector search"

Or manually:

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
brew services start ollama

# Pull the embedding model
ollama pull nomic-embed-text

Then generate embeddings:

"Rebuild the history index with embeddings"

How It Works

Indexing

The server maintains a SQLite database at ~/.claude/.history-index/conversations.db with:

FTS5 virtual table for fast full-text search
Conversation metadata (session ID, project, timestamps, topic)
Full content for comprehensive search
Path cache for reconstructed paths
Embeddings table for vector search (optional)

The index updates automatically when you search (if >5 minutes old) or you can force a rebuild with cowork_history_reindex.

Environment Variables

Variable	Default	Description
`OLLAMA_URL`	`http://localhost:11434`	Ollama server URL
`EMBEDDING_MODEL`	`nomic-embed-text`	Ollama embedding model

Troubleshooting

No conversations found

Make sure ~/.claude/ directory exists
Check that you have conversation history (use Claude Code or Cowork first)
Verify the MCP server is properly configured

Vector search not available

Check Ollama is installed: ollama --version
Check Ollama is running: curl http://localhost:11434/api/tags
Check model is available: ollama list
Pull embedding model: ollama pull nomic-embed-text

Search not finding expected results

Try natural language queries (semantic search is more flexible)
Use mode: "fts" for exact phrase matching
Check cowork_history_stats to see which search backends are active

Development

Running locally

# Clone the repository
git clone https://github.com/egoughnour/cowork-history
cd cowork-history

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run the server directly
python -m src.cowork_history_server

Testing with MCP Inspector

npx @modelcontextprotocol/inspector uvx cowork-history

License

MIT License - see LICENSE file for details.

Cowork History— agent skill

Is Cowork History safe to install?

Cowork History MCP

Features

Installation

Option 1: Claude Desktop (One-Click Install)

Option 2: Via uvx (Recommended for CLI)

Option 3: Via pip

Option 4: Manual Configuration

Quick Start

Available Tools

Search & Browse

Ollama Setup (for Vector Search)

Search Modes

Search Examples

Enabling Vector Search

Quick Setup

How It Works

Indexing

Environment Variables

Troubleshooting

No conversations found

Vector search not available

Search not finding expected results

Development

Running locally

Testing with MCP Inspector

License

Audit the pieces. Scan the whole. Decide.