Semantica
Code provenance and attribution for AI-assisted development.
Semantica tracks AI coding activity in your repositories and ties it to your Git workflow. It makes AI code provenance, attribution, and semantic lineage visible across commits, pull requests, and repos.
It answers the question Git cannot: who or what wrote this code, and how did it happen?
It works by installing lightweight Git hooks that record commit lineage, ingest AI agent data, and compute attribution locally.
Core capture works with zero configuration beyond semantica enable.
Website: semantica.sh
Why Semantica
- Make AI-assisted code changes understandable, reviewable, and attributable.
- Connect agent activity to commits and pull requests so teams can trace how work happened.
- Reduce ambiguity during code review, debugging, handoff, and incident analysis.
- Keep provenance and attribution local by default, with optional hosted sync for team visibility.
- Build trust in AI-assisted software development with a clear system of record that supports audit and compliance.
Requirements
- Git - Semantica hooks into the Git commit lifecycle
- macOS, Linux, or Windows - see platform notes for details
- At least one supported AI provider for capture (Claude Code, Codex, Cursor, Gemini CLI, Copilot, or Kiro IDE/CLI)
- At least one supported AI CLI for LLM-backed features such as suggestions and playbooks: Claude Code (
claude), Codex (codex), Cursor CLI (agent), Gemini CLI (gemini), Copilot CLI (copilot), or Kiro CLI (kiro-cli) - not required for core capture and attribution
Install
Shell script (macOS / Linux)
curl -fsSL https://semantica.sh/install.sh | sh
Homebrew (macOS)
brew install semanticash/tap/semantica
The Homebrew cask installs the semantica binary plus shell completions for Bash, Zsh, and Fish.
Scoop (Windows)
scoop bucket add semanticash https://github.com/semanticash/scoop-bucket
scoop install semantica
Or download the .zip from GitHub Releases and add semantica.exe to your PATH.
From source
Requires Go 1.26+.
git clone https://github.com/semanticash/cli.git
cd cli
make build # binary at ./bin/semantica
make install # installs to /usr/local/bin
Shell completions
Homebrew installs completions automatically. For shell script or source installs, load them from the CLI:
source <(semantica completion zsh) # zsh
source <(semantica completion bash) # bash
semantica completion fish | source # fish
Quick start
cd /path/to/your/repo
semantica enable # installs hooks, detects AI providers, creates a baseline lineage record
- Records a lineage snapshot (file manifest plus provenance metadata)
- Ingests agent session data from detected providers
- Computes AI attribution (how much of the commit is AI-attributed)
- Links everything to the commit hash
Optional: use the OS-managed launcher for more reliable background work when
commits are created by agents or IDE-integrated tools.
semantica launcher enable
semantica launcher status
See Background worker for launcher management and upgrade
notes.
Note: If an AI agent session is already active when you enable Semantica, restart
or reload the agent session so it picks up the new hooks. See
provider reload instructions
for details.
All capture and attribution data are stored locally in .semantica/ - a directory alongside .git, added to .gitignore automatically.
Semantica never writes to Git history or creates side branches; lineage metadata lives in its own database and content-addressed blob store.
Each completed AI turn is also packaged locally into a provenance bundle. The
bundle references the prompt and step blobs captured for that turn, and its
manifest preserves provider-reported token usage when available. When a
provider transcript includes enough structured detail, packaging can also fill
in missing step provenance from transcript evidence before the bundle is saved
under .semantica/ or later synced. File-backed provenance for paths ignored
by Git stays local and is omitted from packaged step bundles.
For optional hosted features, authenticate once and then connect each repo:
semantica auth login # global authentication
semantica connect # connect this repo for hosted features
If a repo is already connected through a shared workspace, semantica connect
will offer to request access. Workspace owners and admins can review pending
requests with semantica workspace requests.
The CLI works fully offline without any remote configuration. Connecting a repo only affects optional hosted sync. Local capture, attribution, and playbooks continue to work the same way.
Before prompt content or remote sync payloads leave the machine, Semantica redacts likely secrets and normalizes known provenance path fields to repo-relative form where possible. If outbound redaction cannot complete for an artifact, that upload fails closed instead of sending raw content. This applies only to outbound sync artifacts. Local raw capture in .semantica/ is left unchanged.
What you get
AI attribution
See what percentage of a commit was AI-attributed, broken down by file. The
plain-text report lists contributing agents and their captured models when
available:
semantica blame HEAD
semantica blame HEAD --json # per-file breakdown
If you run semantica blame without a ref in a terminal, Semantica shows an interactive lineage record picker. In non-interactive use, pass a ref explicitly.
When capture is incomplete, blame and explain label unmatched lines
Unattributed and the percentage AI matched. See
the evidence contract for result fields
and worker capture readiness for retries.
Each commit gets a machine-readable lineage trailer, and can also append attribution and diagnostics trailers:
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 the stable internal lineage record ID for the commit and is always included. Semantica-Attribution and Semantica-Diagnostics can be toggled together with:
semantica set trailers enabled
semantica set trailers disabled # keep only the lineage trailer
Explain commits
Get a structured breakdown of what happened in a commit, including AI attribution,
changed files, session context, and optional playbook generation. Explain also
shows session providers, captured models, and token usage when available:
semantica explain HEAD # stats + AI involvement
semantica explain HEAD --generate # also generate LLM playbook summary
Commit and PR suggestions / Daily workflow
Generate commit messages and pull request descriptions from your current changes:
semantica suggest commit # generates a concise commit message from your current diff.
semantica suggest pr # generates a pull request title and description from your branch diff.
semantica status # shows repo status, audit readiness, monitored providers, and sync state.
semantica doctor # diagnoses local binary, hook, launcher, capture, and auth health.
semantica handoff --write # writes a redacted handoff bundle for a fresh agent session.
For automation, semantica status --json includes the latest checkpoint state,
any failed checkpoint blocking the queue, and a named audit-readiness verdict
for manifest, attribution, provenance, and sync evidence. It also identifies the
stored attribution version and manifest version, scope, and integrity.
Agent sessions
View tracked AI sessions and their transcripts:
semantica sessions
semantica sessions <session_id> --transcript
Prepare a fresh-agent handoff from the active Semantica-tracked agent session:
semantica handoff --write
The command writes .semantica/handoff.md and prints instructions for starting a new session without reprinting the bundle into the current chat. The bundle includes redacted prompt context, the last assistant response, touched files, recent commits, and working-tree context when available. If multiple providers are active in an interactive terminal, Semantica asks which provider to hand off from. Use --from <provider> to hand off from a specific recent provider session, for example semantica handoff --write --from claude-code.
Agent skills
Semantica also ships agent skills for natural-language workflows inside
supported AI coding agents. Skills are authored in the public
semanticash/skills repository and
installed by the CLI into detected agent skills directories:
semantica skills install
semantica skills uninstall
semantica skills install fetches the latest Semantica-authored SKILL.md
files from the protected main branch of semanticash/skills, stamps managed
metadata, and writes them to supported provider-scoped skills directories such
as ~/.claude/skills, ~/.codex/skills, ~/.cursor/skills,
~/.gemini/skills, ~/.copilot/skills, and ~/.kiro/skills.
Installed skills let an agent call Semantica safely without the user needing to
remember exact command syntax. The current skills cover:
semantica-handoff - prepare a redacted .semantica/handoff.md bundle so a fresh same-agent or cross-agent session can continue the work.semantica-explain - explain a commit using local provenance, hosted playbooks when connected, or a redacted git-only fallback.
After installation, use natural language in the agent, for example "handoff
this session" or "explain this commit with Semantica." The skills call hidden
CLI backing commands that return structured output for the agent. For offline
or development installs, pass a source directory laid out as
<source>/semantica-*/SKILL.md, such as the skills/ directory inside a local
semanticash/skills checkout:
semantica skills install --source /path/to/semanticash/skills/skills
Playbooks
Generate and revisit commit playbooks directly from commit explanations:
semantica explain HEAD --generate
semantica explain HEAD
Auto-playbook generation still runs in the background after each commit when
enabled with semantica set auto-playbook enabled. See
Background worker for how commit-time background work is
run.
Background worker
Semantica finishes commit-time work in a background worker after the Git hooks
return. By default, the post-commit hook spawns the worker directly. On
supported platforms, you can optionally route that work through a short-lived
OS-managed launcher:
semantica launcher enable
semantica launcher status
semantica launcher refresh
semantica launcher disable
The launcher is optional and supports macOS (launchd), Linux
(systemd user instance), and Windows (Task Scheduler). launcher status
reports three separate views of state: user settings, the definition file on
disk, and the OS daemon manager itself. The default detached worker remains
supported. Use the launcher when commits are often created by agents or
IDE-integrated tools and you want post-commit work to run through the OS service
manager.
Commit-linked work is processed in repository order. Transient failures retry
with bounded exponential backoff; retries due soon run in the current worker,
and launcher installations also drain every 30 minutes. A terminal failure
blocks later commit-linked work so it cannot be processed against the wrong
predecessor. semantica doctor reports the blocking checkpoint and error. After
fixing the cause, run:
semantica worker retry <checkpoint-id>
After upgrading or locally reinstalling Semantica, semantica launcher refresh
re-registers the worker service against the current binary and drains any
queued work. The official installer and make install attempt this
automatically when they are not running as root; root installs print the exact
user-scoped refresh command to run afterward.
Supported AI providers
| Provider | Hook config | Detection |
|---|
| Claude Code | .claude/settings.local.json | Auto |
| OpenAI Codex | .codex/hooks.json; ~/.codex/config.toml feature gate | Auto |
| Cursor (IDE and CLI) | .cursor/hooks.json | Auto |
| Kiro IDE | .kiro/hooks/*.kiro.hook | Auto |
| Kiro CLI | .kiro/agents/semantica.json | Auto |
| Gemini CLI | .gemini/settings.json | Auto |
| GitHub Copilot | .github/hooks/semantica.json | Auto |
Providers are detected automatically during semantica enable. For each
detected provider, Semantica installs lightweight hooks in the provider's
configuration so agent activity can be captured in real time. Session data is
read passively - Semantica never modifies agent session logs or transcripts.
Codex project hooks must be trusted with /hooks in the CLI or Settings >
Hooks in the desktop app. Kiro CLI uses a repo-local named agent config at
.kiro/agents/semantica.json. See the
provider-specific docs for setup details.
Commands
| Command | Description |
|---|
enable / disable | Initialize or disable Semantica in a repo |
status | Show AI activity overview |
doctor | Diagnose local Semantica install and capture health |
blame <ref> | AI attribution for a commit |
explain <commit> | Explain a commit with AI breakdown |
suggest commit | Generate a commit message from uncommitted changes |
suggest pr | Generate a PR title and body from the current branch diff |
tidy | Preview or remove stale local Semantica state |
sessions | List or view agent sessions |
skills install / skills uninstall | Install or remove Semantica agent skills |
launcher | Manage the optional OS-backed worker launcher |
connect / disconnect | Connect or disconnect this repo for hosted features |
workspace requests | List, approve, or reject shared-workspace access requests |
Most commands support --json for structured output. See help.md for the full command reference including list, show, transcripts, agents, set, auth, and tidy.
Data model
.semantica/
settings.json # configuration
lineage.db # SQLite (lineage records, sessions, events, attribution, playbooks)
objects/ # content-addressed blob store (SHA-256, zstd compressed)
tool-snapshots.git/ # isolated Git objects for shell-tool workspace snapshots
tool-windows/ # pending shell-tool capture state
activity.log # hook and lifecycle warnings / activity log
worker.log # background worker logs
By default, Semantica keeps all data local to your machine and repository in .semantica/.
It does not write to Git history or create side branches. Hosted sync only starts after semantica auth login and semantica connect.
When the launcher is enabled, Semantica also writes
$SEMANTICA_HOME/worker-launcher.log for launcher-level events. Per-repo worker
output still goes to .semantica/worker.log.
Documentation
Getting help
License
MIT License - see LICENSE.
