claude-setup

One command to make Claude Code work at its best -- hooks, agents, persistent memory, and a local LLM, all automatic.

Quick start

Prerequisites: macOS (Apple Silicon), Homebrew, PostgreSQL with pgvector, ~/go/bin in PATH, just installed.

# 1. Create the database
psql -U postgres -c "CREATE DATABASE claudecode;"
psql -U postgres -c "CREATE USER claudecode WITH ENCRYPTED PASSWORD 'your-password';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE claudecode TO claudecode;"
psql -U postgres -d claudecode -c "GRANT ALL ON SCHEMA public TO claudecode;"
psql -U postgres -d claudecode -c "CREATE EXTENSION vector;"

# 2. Bootstrap (downloads binaries from Forgejo releases -- no Go toolchain needed)
just bootstrap

# 3. Edit config with your actual DB credentials
vi ~/.claude-setup/config.json

That's it. Open Claude Code in any project and everything is automatic.

What it does

• 7 hooks -- format, lint, validate, compress, auto-start services, live dashboard
• 8 agents -- worker, researcher, test-runner, security, deps, UI, database, lint
• 13 MCP tools -- memory CRUD, search, LLM proxy, compression, health
• PostgreSQL memory with pgvector -- persists across sessions and projects
• Global MCP server on localhost:19775 (HTTP, launchd auto-start)
• Auto-update daily at 04:00 via launchd
• RTK compresses Bash output 60-90% (lossless token savings)
• Wren compresses hook feedback (lossy semantic compression)
• Local LLM via Ollama (devstral 24B) for cheap tasks

Commands

claude-setup

Command	Description
init	Full setup: install tools, deploy hooks/agents/config, migrate DB
lang <lang>	Copy Justfile template (go, rust, typescript, python, kotlin)
start	Start claude-memory server (launchd, auto-start on login)
stop	Stop claude-memory server, remove launchd jobs
update	Download latest release binaries from Forgejo, restart services
doctor	Health check: binaries, config, services, hooks, agents, launchd
version	Print version

claude-memory

Command	Description
serve	Start MCP server on HTTP (localhost:19775)
migrate	Create/update PostgreSQL tables and indexes
store	Store a memory from CLI (used by hooks)
version	Print version

Hooks

All hooks are automatic -- no manual invocation needed.

Hook	Event	What it does
post-edit.sh	PostToolUse[Edit/Write]	Runs just format, diffs before/after, stores corrections in memory
pre-edit-lint.sh	PreToolUse[Edit/Write]	Runs just lint, feeds issues back as context (non-blocking)
rtk-rewrite.sh	PreToolUse[Bash]	RTK token compression on Bash output
stop-validate.sh	Stop	Runs just check -- blocks until green, loops until all pass
session-start.sh	SessionStart	Auto-starts claude-memory and Ollama if down
pre-compact.sh	PreCompact	Saves current context summary to memory before compaction
post-compact.sh	PostCompact	Reminds Claude to check memory for previous decisions
statusline.sh	StatusLine	Live dashboard (see below)

StatusLine

ANSI-colored live dashboard refreshing every ~300ms. Slow operations (health, memory count, RTK stats) are cached.

Segment	Color	Description
Model	cyan	Current model name
Context	green/yellow/red	Context window usage % (thresholds: 50%, 80%)
Cost	white	Session cost in USD
5h rate limit	green/yellow/red	5-hour rate limit % with reset countdown
7d rate limit	green/yellow/red	7-day rate limit % with reset countdown
Services	green/red	mem:ok oll:ok wrn:ok -- auto-restarts downed services
Memory count	magenta	Total memories in database
RTK	cyan	Cumulative token savings %
Wren	cyan	Cumulative compression savings %
Lines changed	green/red	+added/-removed lines this session

Agents

Claude delegates tasks to these automatically.

Agent	Model	Purpose
worker	inherits	Background coding tasks in fresh context
researcher	haiku	Read-only codebase exploration (Grep, Glob, Read)
test-runner	haiku	Run tests, report only failures
security-checker	inherits	Security review after auth/input/data changes
dep-researcher	inherits	Research best deps + latest versions before adding
ui-designer	inherits	UI/UX specialist, Dracula theme, accessibility
database-specialist	inherits	PostgreSQL/Redis/MariaDB schema, queries, migrations
lint-fixer	inherits	Fix lint/format/build errors across files, learn patterns

MCP Tools

13 tools served via HTTP on localhost:19775.

Tool	Description
store_memory	Store with auto-embedding + dedup
store_correction	Store coding correction (wrong -> correct pattern)
store_rule	Store strict user rule (global scope)
search_memory	Hybrid RRF search (70% semantic + 30% keyword)
recall_corrections	Get corrections, optionally by language
recall_rules	Get all strict rules
track_optimization	Record completed optimization for a file
is_optimized	Check if file already optimized
ask_local_llm	Proxy to Ollama (devstral 24B)
compress_old	Compress old low-access memories (level 0->1->2)
health	Check DB + Ollama connectivity
stats	Memory count by profile and category

One tool is listed above as 12 -- the 13th is ask_local_llm with optional model override, which counts as a single tool serving any Ollama model.

Memory system

Storage

PostgreSQL with pgvector (HNSW index, m=16, ef_construction=64).

Column	Purpose
content	The memory text
embedding	768d vector (nomic-embed-text via Ollama)
profile	Scope: auto-detected from git root folder name, or global
category	correction, preference, optimization, rule, pattern, decision
tags	Array for filtering (language, lint rule, etc.)
fts	Auto-generated tsvector for keyword search
confidence / importance	Ranking factors
access_count	Incremented on every search hit or dedup match
compression_level	0 = full, 1 = gist, 2 = tags-only

Search

Hybrid search with Reciprocal Rank Fusion:

• 70% semantic (pgvector cosine similarity via halfvec)
• 30% keyword (tsvector full-text search)
• Ranked by rrf_score * confidence * (1 + ln(access_count + 1) * 0.1)

Dedup

Cosine similarity > 0.85 increments the existing memory's access_count instead of creating a duplicate.

Profiles

• Project profile: auto-detected from git rev-parse --show-toplevel basename
• Global profile: global -- shared across all projects (rules, cross-project patterns)
• Search always includes both the project profile and global

Compression pipeline

Old, low-access memories are compressed to save space and reduce noise:

Level	Age	Access	Content
0 (full)	< 7 days	any	Original text
1 (gist)	7+ days	< 5	First + last sentence, file paths, error keywords
2 (tags)	30+ days	< 10	First 100 chars + tags

Triggered via the compress_old MCP tool.

Token compression

Two compression systems work together to reduce context window usage:

System	Type	Where	Savings
RTK	Lossless	PreToolUse[Bash]	60-90% on Bash output
Wren	Lossy (semantic)	Stop, PostEdit, PreEdit hooks	Variable, tracked in statusline

Both report cumulative savings in the StatusLine.

Configuration

~/.claude-setup/config.json:

{
  "database_url": "postgresql://claudecode:PASSWORD@your-db-host:5432/claudecode",
  "ollama_url": "http://localhost:11434",
  "embedding_model": "nomic-embed-text",
  "embedding_dims": 768,
  "llm_model": "devstral",
  "dedup_threshold": 0.85
}

Justfile convention

Every project needs a Justfile with these standard recipes. Claude creates and adapts it automatically.

format:     # format code
lint:       # run linter
test:       # run tests
build:      # build project
check:      # format + lint + test + build (Stop hook runs this)
security:   # security scanning
setup:      # install language tools

Set up a new project: claude-setup lang go (or rust, typescript, python, kotlin).

Architecture

~/.claude/
  CLAUDE.md               Global rules (Justfile, worker delegation, self-learning)
  settings.json            Hooks, statusline, permissions, env
  agents/                  8 agent definitions (.md)
  hooks/                   7 hook scripts (.sh) + RTK rewrite
  .mcp.json                -> not used (MCP config is in ~/.claude.json)

~/.claude.json             MCP server config: http://localhost:19775

~/.claude-setup/
  config.json              DB credentials, Ollama config, model settings
  manifest.json            Tracks deployed files (enables clean removal on update)
  claude-memory.log        Server log
  auto-update.log          Daily update log
  claude-memory.pid        PID file (legacy, launchd manages lifecycle)

PostgreSQL:
  memories                 Content, embeddings, profiles, categories, compression
  embedding_cache          SHA256-keyed embedding cache

LaunchAgents:
  de.wuastbude.claude-memory       MCP server (KeepAlive, RunAtLoad)
  de.wuastbude.claude-setup-update Auto-update daily at 04:00

Manifest-based updates

claude-setup init tracks every deployed file in ~/.claude-setup/manifest.json. On subsequent runs, files that were removed from the templates (deleted agents, renamed hooks) are automatically cleaned up from ~/.claude/.

New project workflow

cd my-project
claude-setup lang go      # copies Go Justfile template
just setup                # installs goimports, golangci-lint, gosec
# Open Claude Code -- everything works automatically

Updating

just bootstrap            # re-downloads latest, re-inits, verifies everything

Or manually:

claude-setup update       # downloads latest binaries, restarts services
claude-setup init         # re-deploys hooks/agents if templates changed

Auto-update runs daily at 04:00 via launchd (downloads binaries only, does not re-deploy hooks).

External tools installed by init

Tool	Source	Purpose
RTK	brew install rtk	Lossless token compression on Bash output
Ollama	brew install ollama	Local LLM + embedding host
nomic-embed-text	ollama pull	768d embedding model for memory search
devstral	ollama pull	24B coding model for local LLM proxy
jq	brew install jq	JSON processing in hooks
Wren	manual install	Semantic compression (optional, hooks detect availability)