Configuration

Semantica is configured through .semantica/settings.json inside your repository. Most settings can be managed with semantica set without editing the file directly.

settings.json

{
  "enabled": true,
  "version": 1,
  "providers": ["claude-code", "cursor"],
  "connected": false,
  "trailers": true,
  "automations": {
    "playbook": {
      "enabled": false
    },
    "mcp": {
      "enabled": false
    }
  }
}

Field	Type	Description
`enabled`	boolean	Master switch. `false` makes all hooks inert without uninstalling them.
`version`	integer	Schema version. Currently `1`.
`providers`	array	Providers with hooks installed. Set automatically by `semantica enable`.
`connected`	boolean	Whether this repo syncs attribution to the dashboard. Set by `semantica connect`.
`trailers`	boolean	Whether `Semantica-Attribution` and `Semantica-Diagnostics` trailers are appended. `Semantica-Checkpoint` is always included regardless of this setting.
`automations.playbook.enabled`	boolean	Automatically generate an LLM playbook summary after each commit.
`automations.mcp.enabled`	boolean	MCP server integration for AI agents.

Commit trailers

By default, Semantica appends three trailers to every commit message:

Semantica-Checkpoint: chk_abc123
Semantica-Attribution: 42% claude_code (18/43 lines)
Semantica-Diagnostics: 3 files, lines: 15 exact, 2 modified, 1 formatted

Semantica-Checkpoint is always included and cannot be disabled, it links the commit to its checkpoint.

Semantica-Attribution and Semantica-Diagnostics are optional and can be toggled:

semantica set trailers enabled    # Include all three trailers (default)
semantica set trailers disabled   # Checkpoint-only commits

Auto-playbook

When enabled, every commit automatically spawns a background LLM call that generates a structured playbook summary and indexes it for search.

semantica set auto-playbook enabled
semantica set auto-playbook disabled

Requires at least one LLM CLI installed and authenticated: claude, cursor, gemini, or copilot. The playbook is generated asynchronously, run semantica explain HEAD after a few seconds to see the result.

Environment variables

Variable	Description
`SEMANTICA_API_KEY`	API key for authentication. Overrides stored credentials. Useful in CI environments.
`SEMANTICA_ENDPOINT`	Override the backend endpoint URL.
`SEMANTICA_HOME`	Override the global Semantica home directory (used for global settings and credentials lookup).

Authentication and credentials

Credentials from semantica auth login are stored in:

macOS: macOS Keychain
Linux: Linux Secret Service / libsecret-compatible keyring
Headless / CI fallback: ~/.config/semantica/credentials.json with 0600 permissions (respects $XDG_CONFIG_HOME)

Existing file credentials are automatically migrated to the OS secure store when it becomes available.

For CI pipelines where browser-based auth is not practical, set SEMANTICA_API_KEY instead:

export SEMANTICA_API_KEY=your_key_here
semantica connect

File structure

.semantica/
  settings.json       # Per-repo configuration (this file)
  lineage.db          # SQLite database: checkpoints, sessions, events, attribution, playbooks
  objects/            # Content-addressed blob store (SHA-256 keys, zstd compressed)
  activity.log        # Hook lifecycle warnings and activity log
  worker.log          # Background worker and auto-playbook logs
  enabled             # Presence of this file controls whether hooks are active

.semantica/ is automatically added to .gitignore by semantica enable. It is never committed to the repository.

Resetting configuration

To start over with a fresh configuration while keeping your Git history:

semantica disable
rm -rf .semantica/
semantica enable

This removes all local checkpoints, sessions, and attribution data. It does not affect commits already made or their trailers.

Search documentation