CLI Reference

Daemon and client

A third, chitta_hintd, is built only when the build enables llama.cpp and is optional at runtime.

Status as of 2026-09-20 Canonical command reference.

chittad runs the daemon. chitta talks to it. Both compiled from C++, communicating over Unix domain socket.

chittad — Daemon

6 commands ▾
chittad daemon [--foreground] [--path PATH] [--interval SECS] Run background daemon. Self-daemonizes by default (double-fork). Opens the chitta-field memory substrate, loads the GGUF embedding model through llama.cpp, creates the Unix socket, starts the thread pool.
chittad shutdown Gracefully stop the running daemon via Unix socket.
chittad status Check if daemon is running and responsive.
chittad stats [--json] [--fast] Show soul statistics — nodes, coherence, ojas, yantra status.
chittad metrics Show the component metrics behind the Soul Utility Score.
chittad distill --transcript-path PATH [--session-id ID] [--realm REALM] Distill one transcript by hand. The daemon also does this on a timer (--distill-interval, minutes) once a session has at least --distill-min-turns turns. Distillation is native C++; the --distill-script flag is accepted and ignored.
# Start daemon in foreground with custom path
$ chittad daemon --foreground --path ~/.claude/mind

# Check status
$ chittad status
chittad running (pid 41823, socket /tmp/chitta-a3f1.sock)

# Show stats in JSON
$ chittad stats --json

chitta — Client (CLI Mode)

8 examples ▾

Direct tool invocation with named arguments. The client connects to the running daemon via Unix socket and returns the result.

chitta <tool-name> [--param value ...]

Global options: --socket-path, --json, --toon, --text-only, --help

chitta soul_context Check soul health — memory count, confidence distribution, realm info, uptime.
chitta recall --query "auth" --limit 5 Semantic search — ranks memories by embedding similarity.
chitta full_resonate --query "caching" --k 5 8-phase resonance — spreading activation, attractor dynamics, Hebbian26 recall.
chitta learn_codebase --path . --project "my-app" Index codebase — extract symbols, relationships, and call graphs via tree-sitter.
chitta read_symbol --name "Mind" Read symbol source code directly by name — avoids full file reads.
chitta find_symbol --name "UserService" --kind class Structural symbol search with optional kind filter (function, class, method).
chitta remember --content "[domain] pattern→insight" Store a memory in SSL format with automatic embedding and realm detection.
chitta mcp Speak MCP over stdio. printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | chitta mcp enumerates the daemon’s whole tool surface; this is what generates the tools page.

chitta — Thin Client Mode

▾

When stdin is not a terminal, chitta forwards raw JSON-RPC to the daemon. This enables programmatic integration from scripts, hooks, and other tools.

$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recall","arguments":{"query":"test"}}}' | chitta
# Response (JSON-RPC)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "..."}]
  }
}

TOON Output Format

▾

Token-Oriented Object Notation — ~40% fewer tokens than JSON, optimized for LLM consumption. Use --toon flag to enable.

--json

{
  "memories": [
    {
      "id": "a3f1...",
      "content": "cmake tip",
      "confidence": 0.85,
      "type": "solution"
    }
  ]
}

--toon

memories:
  id=a3f1...
  content=cmake tip
  confidence=0.85
  type=solution
---

Environment Variables

5 variables ▾
Variable Description Default
CHITTA_DB_PATH Mind storage directory ~/.claude/mind
CLAUDE_PLUGIN_ROOT Plugin root for model paths —
SUBCONSCIOUS_INTERVAL Daemon cycle interval in seconds 60
CHITTAD_BIN Path to chittad binary ~/.claude/bin/chittad
CHITTA_BIN Path to chitta binary ~/.claude/bin/chitta

Model Path Resolution

▾

The embedding model is a GGUF loaded in-process through llama.cpp. Its filename follows the compiled embedding identity, so auto-discovery and the bundled model can never drift apart: a public build looks for bge-large-en-v1.5.gguf. Search order:

--embed-model / $CHITTA_EMBED_MODEL → ~/.claude/models/ → ~/.claude/bin/ → <mind>/../../models/

The ~/.claude/bin/ probe exists because the systemd unit keeps the model beside the binaries. Without it, a daemon started with no --embed-model would silently fall back to an HTTP embedding backend — a different vector space, which means wrong-dimension vectors and corrupt recall rather than a clean failure.

Embedding dimension is a compile-time constant, 1024 on a public build, set with -DCHITTA_EMBED_DIM or $CHITTA_EMBED_DIM at configure time. Changing it requires a fresh build directory and re-embedding the store.

Daemon Internals

▾

What happens when chittad daemon starts:

  • Opens chitta-field at {path}/chitta-field/
  • Loads the GGUF embedding model through llama.cpp (bge-large-en-v1.5, 1024 dimensions, on a public build)
  • Creates Unix socket at /tmp/chitta-{hash}.sock
  • Starts thread pool (8–16 workers)
  • Begins subconscious processing loop

Subconscious schedule:

Every 1s Check for work Every 30s Process embedding queue (batch of 20) Every 30min Hygiene cycle — decay, prune, consolidate Every 60min Theme maintenance

Runtime and lifecycle

chitta --help lists client categories; chitta <tool> --help shows parameters. --text-only emits tool text for hooks, and CHITTA_SOCKET_PATH selects the daemon. Native help includes ledger_op, session_register, session_heartbeat and session_deregister; these entries are shown separately in the tool reference.

The queue defaults to <mind>/queue.jsonl. The store holds <mind>/chitta-field/.instance.lock; only a dead same-host owner is automatically replaced. The service allows TimeoutStopSec=300 for clean shutdown. Do not remove a live or other-host lock.

Matching .lsh, .turbo and .organs sidecars and parallel snapshot decode bring measured warm startup to about 9.5 s. First start after deployment or a format change is about 20 s. Index maintenance can continue after readiness; allow 30 s before recall benchmarking.

--no-enrich is still accepted for code enrichment, whose worker is currently inert. It does not disable the separate hint worker: that script path comes from CHITTA_HINT_ENRICHER or discovery, with a three-new-memory trigger, 600-second cooldown and batch of 50. Native transcript distillation remains separate.

← Back to chitta

References

  1. Donald O. Hebb. The Organization of Behavior: A Neuropsychological Theory. Wiley (1949); Psychology Press reissue (2002). https://www.routledge.com/The-Organization-of-Behavior-A-Neuropsychological-Theory/Hebb/p/book/9780415654531