Configuration & paths

Where Blamely stores things, and the environment variables that change those locations.

Default paths #

On Windows, ~ is your user profile (%USERPROFILE%).

Environment variables #

Use these to keep state on a different disk, or to sandbox a test install.

AI-tool hook locations #

blamely install writes a hook configuration only for tools it finds. None of these files are created if the tool isn’t present.

Hooks from other tools are merged, not replaced. blamely uninstall removes only the Blamely-owned entries.

Custom Codex and Claude config directories #

Some teams run Codex or Claude Code from a non-default home — common with corporate provisioning, e.g. ~/.codex-corp/codex-config or ~/.claude-corp/claude-config. Blamely supports these in addition to the defaults: it never stops watching ~/.codex and ~/.claude — a custom directory is simply added to the set. If a machine has both a personal and a corporate install, both are attributed.

A custom directory follows each tool’s own convention:

How Blamely learns the custom path. The Blamely daemon runs as a background service (launchd / systemd / Scheduled Task) and does not inherit your shell’s environment, so it can’t read CODEX_HOME / CLAUDE_CONFIG_DIR on its own. Two things bridge that gap:

1. blamely install runs in your shell, so it captures those variables (when set to a non-default value) and persists them into config.json for the daemon to use.
2. blamely config add lets you register a directory at any time — the right choice for provisioning scripts or when the variable isn’t set in the installing shell:

blamely config add tools.codex_home ~/.codex-corp/codex-config
blamely config add tools.claude_config_dir ~/.claude-corp/claude-config
blamely repair                                   # install the record hook into the custom config too

These are stored under a tools section in config.json:

{
  "tools": {
    "codex_homes": ["/Users/you/.codex-corp/codex-config"],
    "claude_config_dirs": ["/Users/you/.claude-corp/claude-config"]
  }
}

Manage the list from the CLI:

blamely config                                            # 'tools.*' lines show registered dirs
blamely config add tools.codex_home <path>                # add (idempotent; 'homes'/'home' both accepted)
blamely config remove tools.claude_config_dir <path>      # remove a registered dir

After adding a directory, blamely repair wires the record hook into that location’s config.toml / settings.json, and blamely doctor lists every location it checks (default and custom). Session logs and transcripts under all registered directories are then watched together.

Git configuration #

git config --global core.hooksPath
# /Users/you/.blamely/git-hooks

This is set by blamely install so the post-commit hook runs globally for every repository on your machine. A post-merge hook lives alongside it and attributes commits a git pull brings in from a cloud agent (see Devin). If you had a previous global core.hooksPath, the existing hooks are linked into Blamely’s directory so they continue to fire.

Per-repo hooks (legacy) #

Older Blamely versions wrote hooks into each repo’s .git/hooks/ directory. Recent versions use the global core.hooksPath instead. Clean up stale per-repo files with:

blamely repair

This removes .git/hooks/post-commit files that Blamely previously wrote. Anything you wrote yourself is left alone.

Note contents (config.json) #

blamely install seeds ~/.blamely/config.json with every option enabled. It controls what each per-commit git note stores — attribution itself is never affected, only what gets written into the note. Edit the file directly, or use the blamely config command (below).

{
  "note": {
    "file_lines": true,
    "conversation": true,
    "conversation_user": true,
    "conversation_assistant": true,
    "message": true,
    "coding_time": true,
    "tokens": true
  }
}

Every option defaults to on, so a missing or partial file keeps full output — you only list the toggles you want off. A conversation turn is stored only when conversation is on and its role’s toggle is on, so you can keep the model’s replies while dropping what you typed (or the reverse).

Manage it from the CLI #

blamely config                                   # show current settings + file path
blamely config get note.conversation_assistant   # print one value
blamely config set note.file_lines off           # change + save (accepts on/off, yes/no, true/false)
blamely config set conversation_user false        # the "note." prefix is optional
blamely config path                              # print the config file path

Next #

• CLI commands — the command reference.
• Troubleshooting — recovering from a bad state.
• Privacy & data — what stays local and what can leave.