Installation and setup
Register the marketplace and install the plugin. The installer builds or downloads binaries, configures hooks, and sets up the daemon.
Status as of 2026-09-20 CLI and startup reference.
Prerequisites
- macOS (Apple Silicon or Intel) or Linux (x86_64)
- Claude Code — Anthropic's official CLI
Installation
Register Marketplace
Add the chitta marketplace to Claude Code.
Add Plugin
Install chitta from the marketplace.
Register MCP Server (optional)
Gives Claude direct access to the chitta tools via mcp__chitta__* — a small default list, with the rest reachable through the advanced gateway. Without this, hooks still provide memory; MCP adds the toolkit. See Tools.
Installer startup
On your next Claude Code session, smart-install.sh runs automatically — it builds the binaries, fetches the embedding model, and configures hooks and permissions. The daemon starts and loads the store.
Upgrading from the old cc-soul marketplace: every CC_SOUL_* variable, your stored realms and your existing store all keep working. The three commands to move to the renamed marketplace are in the rename note.
Codex
chitta also works as a Codex plugin. Its lifecycle hooks connect to the same daemon, tools, and memory store.
Run smart-install
If you haven’t already, install via Claude Code first — this builds the binaries and starts the daemon.
Wire Codex hooks
Run the Codex hook configurator. Writes ~/.codex/hooks.json with session-start, prompt, pre-tool, and stop handlers pointing at the same chitta daemon.
Start a Codex session
Claude Code and Codex can retrieve memories from each other’s sessions when both use the same daemon and store.
Installer operations
- Resolves the latest release, which may be newer than the plugin cache, and fetches that source
- Builds from source with llama.cpp embeddings when a C++ compiler is present; falls back to pre-built binaries when it is not, or when the build fails
- Downloads the GGUF embedding model (
bge-large-en-v1.5, 1024 dimensions). An existingnomic-embed-textinstall is detected and preserved, because changing embedding identity would invalidate the store - Installs hooks, links the rules file, and configures bash permissions and hook wiring in
settings.json - Installs the Python packages for the MCP server and the TUI
- Sets up the systemd user service on Linux; a no-op on macOS
- Runs store migrations against a stopped daemon, then restarts it
- Trains the hook intent classifier in the background if it is missing, from a bundled corpus with no API calls. A regex fallback is active until it finishes
Smart install only runs when the version changes or binaries are missing. Subsequent sessions skip that installation step. Warm daemon startup measured about 9.5 s on the documented store.
Processes
| Process | Role |
|---|---|
| chittad | The daemon. Holds the store, answers every recall over a Unix socket, runs distillation on a timer. On Linux it is a systemd user service. |
| chitta | The client. What hooks and the shell call; also speaks MCP over stdio with chitta mcp. |
| chitta-mcp | The Python MCP server. Adds the composite gateways — advanced, learn, research, recall strategy routing — and the optional cross-encoder rerank stage. |
| chitta_hintd | Optional. A small local hint model behind its own socket, built only when the build enables llama.cpp. Everything works without it. |
Hooks do not run from a checkout. Lifecycle hooks execute from the plugin cache, and the tool hooks execute from ~/.claude/hooks. Those are two different roots in the same configuration, so editing a source checkout changes nothing until you install. Working on chitta itself is what scripts/dev-install.sh is for: it symlinks both live paths back at your checkout, so an edit is live on the next hook invocation. Re-run it after any plugin update, which can replace the symlinks with a fresh clone.
Nothing here needs a GPU. Distillation runs natively in the daemon. A GPU-backed model endpoint can be started on demand for heavier distillation through chitta-gpu start, which ships in the separate chitta-bridge repository, not here.
Maintenance skills
| Command | What it does |
|---|---|
| /chitta:cc-soul-setup (suffix retained after rename) | Manual build from source (if you need to rebuild) |
| /chitta:cc-soul-update (suffix retained after rename) | Update binaries (downloads pre-built or builds from source) |
| /chitta:cc-soul-mcp (suffix retained after rename) | Configure the MCP server for direct tool access |
| /chitta:health | Check soul system health with remediation |
| /chitta:codebase-learn | Index a project's symbols and call graphs |
Verification
Start a new Claude Code session. You should see status messages during startup:
Workflow records
Hooks record workflow patterns, goals, work modes, knowledge gaps, and prediction outcomes. The tools below also expose these records 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.
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.
Goals
Track long-term objectives with milestones and progress stored across sessions.
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.
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.
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.
Documentation and indexing
Environment Variables
| Variable | Description | Default |
|---|---|---|
| CHITTA_SOUL_DIR | Soul data directory — where chitta-field, 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/chittadexists and is executable. Run it manually to see errors:~/.claude/bin/chittad daemon --foreground search_symbolsreturns 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. Hooks and distillation add preferences, corrections, solutions, and other records during use.
embed_symbolsshows 0 new-
All symbols are already embedded. Use the reset flag to regenerate with fresh text:
chitta embed_symbols --reset true
Daemon readiness
Run chitta health_check --json against the intended daemon. A measured warm start takes about 9.5 s with sidecars; first start after deployment or a format change takes about 20 s. Allow 30 s before benchmarking recall because index maintenance may continue after readiness.
Claude Code and Codex share one daemon and store. Use CHITTA_SOCKET_PATH for an alternate endpoint; do not start a second daemon on the same mind directory. Startup and instance-lock recovery explains ownership and stale-lock handling.