Installation & Setup

Prerequisites

• Python 3.10+ — Samantha LLM is a Python script with no external dependencies beyond the standard library.
• Git — For cloning the repository.
• An agentic LLM tool — Claude Code, GitHub Copilot CLI, Abacus.ai, or any tool that accepts a text prompt.

Installation

1. Clone the Repository

git clone git@github.com:criswell/samantha-llm.git
cd samantha-llm

2. Run the Installer

./samantha-llm install

This will:

• Create a config directory (~/.config/samantha-llm/ on Linux/macOS)
• Install the samantha-llm command to your PATH
• Set up the default subconscious analysis prompt

If ~/.local/bin is not in your PATH, the installer will tell you what to add to your shell profile.

3. Configure an Agent

samantha-llm setup

You’ll be prompted to choose your agentic LLM tool:

Select your preferred Agentic LLM tool:

1) Claude Code
2) Abacus.ai
3) GitHub Copilot
4) Other (manual setup)

Select your tool and the agent will be configured automatically. The first agent you set up becomes the default.

4. Verify Installation

samantha-llm status

This shows your installation path, config location, configured agents, and default agent.

Starting a Session

Navigate to any project directory and run:

cd /path/to/your/project
samantha-llm start

Samantha LLM will:

1. Create a temporary .ai-cerebrum symlink in your project directory
2. Launch your configured agent with the bootstrap prompt
3. Samantha initializes: loads persona, reads memories, surfaces active projects
4. You work normally with your AI assistant
5. When you exit, the symlink is cleaned up and a background worker begins analyzing the session

Tip: Add .ai-cerebrum to your project’s .gitignore to avoid accidentally committing the symlink.

Multiple Agents

You can configure more than one agent. Run samantha-llm setup again and choose a different tool — it will be added alongside your existing agents without overwriting them.

Switching the Default

samantha-llm setup --default claude

Starting with a Specific Agent

samantha-llm start abacus

Listing Agents

samantha-llm agents

This is useful if you have multiple LLM accounts with different credit balances — switch to another agent and keep working without losing any context.

Manual Workspace Linking

By default, samantha-llm start creates a temporary symlink that’s removed when the session ends. If you’re working on a long project and want the link to persist across sessions:

# Create a persistent link
samantha-llm link

# Later, remove it
samantha-llm unlink

When a manual link exists, samantha-llm start will detect it and skip auto-linking. The link will remain after the session ends.

This is also required for agents that aren’t set up through samantha-llm setup — link the workspace manually, then launch your agent yourself with the .ai-cerebrum/BOOTSTRAP_PROMPT.md prompt.

Platform Notes

Linux and macOS

• Installs to ~/.local/bin/ via symlink
• Config stored at ~/.config/samantha-llm/
• Requires ~/.local/bin in your PATH

Windows

• Installs to %LOCALAPPDATA%\Programs\samantha-llm\ via batch wrapper
• Config stored at %APPDATA%\samantha-llm\
• The installer copies the script and creates a .bat wrapper

Uninstalling

samantha-llm uninstall

You’ll be asked whether to keep or remove the config directory. Your memories (stored in the cloned repository’s .ai/ directory) are not affected by uninstalling — they remain in the repo.

Recommended: Install Memory Search

Samantha LLM works without it, but installing QMD enables semantic search across all your memories — both from the command line and during sessions:

samantha-llm qmd install

This installs the Bun runtime and the qmd search engine. AI models (~2GB) are downloaded on first use.

See Memory Search for details on indexing and searching.

Next Steps

• Memory System — Understand how Samantha organizes and retains knowledge
• Persona System — Customize or replace the default persona
• Memory Search — Set up semantic search across memories