# claude-config

My personal Claude Code configuration — agents, skills, commands, rules, and settings.

Built on top of [everything-claude-code](https://github.com/affaan-m/everything-claude-code).

## What's inside

```
claude/
├── CLAUDE.md                  # Global identity, working style, code principles
├── settings.template.json     # Hooks/env template (CC_ROOT is filled in by install.sh)
├── agents/                    # Subagents (architect, planner, code-reviewer, security...)
├── commands/                  # Slash commands (/plan, /tdd, /code-review, /checkpoint...)
├── rules/                     # Always-follow guidelines (security, testing, git, style...)
└── skills/                    # Workflow definitions and domain knowledge
```

> `claude/settings.json` is generated locally from `settings.template.json` on every
> `./install.sh` run and is gitignored — your absolute paths never end up in the repo.

## Install

Clone the repo anywhere you like, then run the installer:

```bash
git clone https://github.com/aleonsa/claude-config.git
cd claude-config
chmod +x install.sh
./install.sh
```

What `install.sh` does:

1. Generates `claude/settings.json` from `claude/settings.template.json`, substituting
   the `__CC_ROOT__` placeholder with the absolute path of wherever you cloned the repo.
2. Symlinks `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, and the `agents/`,
   `commands/`, `rules/`, `skills/` directories into the repo, so `git pull` updates
   everything in-place.

## Update

```bash
cd <your-clone-path>
git pull
./install.sh   # regenerates settings.json in case the template changed
```

The directory and `CLAUDE.md` symlinks pick up changes automatically; re-running
`install.sh` only matters when the hooks template changes.

### Why a template instead of a committed settings.json?

The hook commands need an absolute path to the repo (`CC_ROOT`) so Claude Code can
locate the hook scripts. Committing one user's absolute path would force every other
contributor to hand-edit it. The template + generated-and-gitignored `settings.json`
pattern keeps each clone working with zero per-user edits — and keeps personal paths
out of the repo history.

> `CC_ROOT` is used instead of `CLAUDE_PLUGIN_ROOT` because the latter is a name
> Claude Code reserves for plugin-style `hooks/hooks.json` files; using it inside
> user-level `settings.json` raises a "hook is not associated with a plugin" error.

## Customizing per project

Add a `CLAUDE.md` at the root of any project for project-specific instructions.
Claude Code merges it with the global one automatically.

```bash
touch my-project/CLAUDE.md
```

## Structure philosophy

- **`CLAUDE.md`** — who you are, how you work, what requires approval
- **`settings.json`** — technical config (model, hooks, env)
- **`rules/`** — non-negotiable guidelines Claude always follows
- **`agents/`** — specialized subagents for delegated tasks
- **`commands/`** — slash commands for common workflows
- **`skills/`** — deep domain knowledge loaded on demand

## AI tooling ecosystem (Graphify + Engram + Caveman)

Three complementary tools extend the setup across Claude Code, Kimi Code, OpenCode, and Cursor.
See [docs/AI-TOOLS-PLAYBOOK.md](docs/AI-TOOLS-PLAYBOOK.md) for the full installation
and usage guide.

| Tool | What it does | Runtime |
|---|---|---|
| [Graphify](https://github.com/Graphify-Labs/graphify) | Turns codebases into queryable knowledge graphs (tree-sitter AST, local) | Python (uv) |
| [Engram](https://github.com/Gentleman-Programming/engram) | Persistent memory across sessions (SQLite + FTS5 + MCP) | Go binary |
| [Caveman](https://github.com/JuliusBrussee/caveman) | Compresses output tokens ~65% by dropping filler | Prompt-only |

### Quick install (all three, all platforms)

```bash
# 1. Graphify — one CLI, registers skill per platform
uv tool install graphifyy
graphify install                      # Claude Code
graphify install --platform kimi      # Kimi Code
graphify install --platform opencode  # OpenCode
graphify cursor install               # Cursor (writes .cursor/rules/graphify.mdc)

# 2. Engram — Go binary + MCP
brew install gentleman-programming/tap/engram
engram setup claude-code
engram setup opencode
engram setup cursor                  # Cursor (writes ~/.cursor/mcp.json)
# Kimi: creates ~/.kimi-code/mcp.json (see playbook for details)

# 3. Caveman — auto-detects installed agents
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
# Kimi is not auto-detected — copy skills manually (see playbook)
# Cursor: create .cursor/rules/caveman.mdc manually (see playbook)
```