Skip to main content

​
Installation

Get CosmaSense installed and start searching your files in three simple steps.

​
Step 1: Download and Install

CosmaSense is currently available in alpha testing through GitHub.
git clone https://github.com/cosmasense/cosma.git
cd cosma
macOS app coming soon! Currently available as CLI and TUI.
CosmaSense requires Python 3.8+ and uses a monorepo structure with shared dependencies.
# Install Python dependencies
pip install -r requirements.txt

# For local AI models (optional)
pip install ollama
You can use either local models (Ollama) or cloud providers (OpenAI) for AI features.

​
Step 2: Start the Backend

The backend runs as a daemon process on port 60534.
# Start the backend server
cosma serve
The backend will:
  • Initialize the SQLite database with vector search capabilities
  • Start watching for file changes
  • Listen for search requests on http://localhost:60534
The server runs in the background and auto-restarts on crashes.
Tell CosmaSense which directory to index:
# Watch a directory (e.g., Downloads)
curl -X POST http://localhost:60534/api/watch/directory \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/yourname/Downloads"}'
CosmaSense will automatically:
  1. Discover all files in the directory
  2. Parse them using MarkItDown
  3. Generate AI summaries and keywords
  4. Create embeddings for semantic search

​
Step 3: Start Searching

Use the Terminal UI to search your files:
cosma search
The TUI provides:
  • Real-time search as you type (0.5s throttled)
  • Live indexing status updates via SSE
  • File preview and selection (fzf-style)
Try searching:
  • “tax documents from 2023”
  • “python code with API calls”
  • “meeting notes about project roadmap”
Press Enter on a file to print its path (useful for piping to other commands).

​
Quick Usage Examples

# Interactive terminal search
cosma search

# Type your query in natural language
# Select a file with Enter to get its path

​
Next Steps

Now that CosmaSense is running, explore these topics:

How Search Works

Learn about hybrid semantic and keyword search.

Backend Architecture

Understand the async pipeline and processing stages.

API Reference

Explore all available API endpoints.

Watch Directories

Add directories to watch and start indexing files.
Need help? Check out our GitHub issues or read the development guide.