cli

README

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

That's it. Every commit now automatically:

1. Records a lineage snapshot (file manifest plus provenance metadata)
2. Ingests agent session data from detected providers
3. Computes AI attribution (how much of the commit is AI-attributed)
4. 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. 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:

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.

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 provider/session details 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.

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

• Changelog - notable changes by release
• Features - detailed guide to each capability
• Hosted features - optional auth, repo connection, and remote sync behavior
• Architecture - how Semantica works internally
• Providers - AI provider integration details
• Limitations - known constraints and scope boundaries
• Release process - how releases are built and published
• Contributing - how to contribute
• Security policy - reporting vulnerabilities

---

Getting help

• Report an issue
• Contributing guide
• Security policy

---

License

MIT License - see LICENSE.