Getting Started

Two commands. That's it.

Register the marketplace, add the plugin. Everything else is automatic.

Prerequisites

  • macOS (Apple Silicon or Intel) or Linux (x86_64)
  • Claude Code — Anthropic's official CLI

Install

1

Register Marketplace

Add the cc-soul marketplace to Claude Code.

claude marketplace add https://github.com/genomewalker/cc-soul
2

Add Plugin

Install cc-soul from the marketplace.

claude plugin add cc-soul@genomewalker-cc-soul
3

Register MCP Server (optional)

Gives Claude direct access to 100+ chitta tools via mcp__chitta__*. Without this, hooks still provide memory — MCP adds the full toolkit.

/cc-soul-mcp

That's it.

On your next Claude Code session, smart-install runs automatically — downloads pre-built binaries (or builds from source), fetches the embedding model, configures hooks and permissions. The daemon starts, memory awakens.

What Smart Install Does

  • Downloads pre-built binaries for your platform (falls back to building from source if unavailable)
  • Fetches the ONNX embedding model (~80 MB) for semantic search
  • Installs hooks (session start, prompt resonance, stop checkpoint, pre-compact)
  • Configures bash permissions for chitta commands
  • Runs database migrations if upgrading from a previous version

Smart install only runs when the version changes or binaries are missing. Subsequent sessions start instantly.

Useful Skills

Command What it does
/cc-soul-setup Manual build from source (if you need to rebuild)
/cc-soul-update Update binaries (downloads pre-built or builds from source)
/cc-soul-mcp Configure the MCP server for direct tool access
/health Check soul system health with remediation
/codebase-learn Index a project's symbols and call graphs

Verify

Start a new Claude Code session. You should see status messages during startup:

awakening... recalling context... # Then try asking: "What do you remember about me?"

Companion Features

Beyond memory, cc-soul learns how you work. These features build a richer partnership over time — most activate automatically through hooks, but you can also use them directly.

↺

Habits

Recurring trigger→response patterns that strengthen each time they're observed. After building, always install and restart the daemon. After a test fails, always check the logs first. Habits surface these patterns so they become automatic.

# Record a habit chitta habit_observe --trigger "after building chitta" --response "install binaries and restart daemon" # Find habits matching your current context chitta habit_match --context "just finished building the project" # See all formed habits chitta habit_list
≫

Anticipation

Context→action patterns that predict what you'll need next. When you open a particular file, anticipation predicts which tools and commands typically follow. The prompt hook surfaces these predictions automatically.

# Record what action followed a context chitta anticipation_observe --context "editing duckdb_handler.hpp" --action "rebuild and test" # Predict next actions from current context chitta anticipation_predict --context "user asked about build errors" # See all learned patterns chitta anticipation_list
⌖

Goals

Track long-term objectives with milestones and progress. Goals persist across sessions, so the soul always knows what you're working toward and how far you've come.

# Set a goal with milestones chitta goal_set --title "Ship v4.0" --description "Major release with new features" \ --milestones '[{"name":"API stable","done":false},{"name":"Docs complete","done":false}]' # Update progress and mark milestones chitta goal_progress --id 1 --progress 0.6 --milestone "API stable" # List active goals chitta goal_list --status active
…

Work Modes

The narrative engine tracks your session's work mode — exploring, building, debugging, reviewing — by observing tool usage and file patterns. The prompt hook displays your current mode, and anticipation uses it to filter predictions to what's relevant right now.

# Check current work mode and confidence chitta narrative_status # View session history of mode transitions chitta narrative_history --session_id "abc123" --limit 10
?

Curiosity

Track knowledge gaps as you encounter them. When you hit something you don't understand, note it. Later, when the gap is resolved, record what you learned. This builds a map of your evolving understanding.

# Note a knowledge gap chitta curiosity_note_gap --gap "How does spreading activation affect recall?" \ --context "Noticed recall results vary with triplet density" # List open gaps chitta curiosity_gaps # Resolve when you learn the answer chitta curiosity_resolve --id 3 --learned "Spreading activation boosts neighbors by 0.15 per hop"
%

Calibration

Track prediction accuracy across domains. Was that architecture suggestion correct? Did the debugging approach work? Over time, calibration reveals where the soul's advice is reliable and where it needs improvement.

# Record whether a prediction was correct chitta calibration_record --domain "debugging" --success true # Check accuracy scores chitta calibration_score

What to Do Next

Explore 100+ Tools

Browse the full MCP toolkit — memory, code intelligence, learning, anticipation, and more.

→ tools reference

Understand the Architecture

How the resonance engine, DuckDB store, and semantic anchoring work together.

→ architecture

Learn the Philosophy

Vedantic concepts mapped to measurable code — every Sanskrit term names a real operation.

→ philosophy

Index Your Codebase

Give the soul knowledge of your project structure, symbols, and call graphs.

/codebase-learn /path/to/project

Environment Variables

Variable Description Default
CHITTA_SOUL_DIR Soul data directory — where DuckDB, embeddings, and state are stored ~/.claude/mind/chitta
CHITTA_BIN Path to the chitta CLI binary ~/.claude/bin/chitta
CHITTA_SOCKET Unix socket path for daemon communication /tmp/chittad.sock
CHITTA_LOG_LEVEL Logging verbosity for the daemon info

Troubleshooting

Daemon not starting

Check that ~/.claude/bin/chittad exists and is executable. Run it manually to see errors:

~/.claude/bin/chittad daemon --foreground
search_symbols returns nothing

Embeddings have not been generated. Run both steps after indexing:

chitta learn_codebase /path/to/project chitta embed_symbols
Tool calls fail with connection error

The daemon is not running. Terminate the stale process and retry — the daemon auto-restarts on the next call:

pkill -TERM chittad
MCP tools not showing in Claude

The MCP server process is stale. Restart it:

pkill -f "chitta mcp"
Memory seems empty

This is normal for a fresh install. Memories build organically through usage — preferences, corrections, solutions, and insights accumulate as you work together.

embed_symbols shows 0 new

All symbols are already embedded. Use the reset flag to regenerate with fresh text:

chitta embed_symbols --reset true
← Back to cc-soul