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 capture checkpoints, 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.
• Track one implementation story even when agents carry the work across multiple repositories.
• 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, playbooks, and intent-gap analysis (claude, codex, agent, gemini, copilot, or 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 baseline checkpoint

That's it. Every commit now automatically:

1. Creates a checkpoint (file manifest snapshot)
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

You can also opt into an OS-managed background worker:

semantica launcher enable   # experimental
semantica launcher status   # inspect settings / definition file / daemon-manager state

This is optional. Repos that do not enable the launcher keep using the default post-commit worker path. The launcher exists for workflows where agents or IDE-integrated tools may create commits on your behalf and you want the follow-up background work to run more reliably through launchd on macOS, systemd user units on Linux, or Task Scheduler on Windows.

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, checkpoints, attribution, rewind, 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 checkpoint picker. In non-interactive use, pass a ref explicitly.

Each commit gets a machine-readable checkpoint 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 always included. Semantica-Attribution and Semantica-Diagnostics can be toggled together with:

semantica set trailers enabled
semantica set trailers disabled    # checkpoint-only commits

Intent-gap analysis

For connected repositories, Semantica can compare captured user prompts with the committed pull request diff using an installed AI CLI. The result is an advisory review signal for requested work that may be incomplete, deferred work, or changed code without supporting captured intent.

Intent-gap analysis is off by default:

semantica set intent-gap enabled

When enabled, the non-blocking pre-push hook starts analysis in the background when the current branch is pushed and Semantica knows about an open pull request for that branch. You can also run it directly:

semantica intent-gap analyze
semantica intent-gap analyze --base origin/main
semantica doctor

Findings are generated locally, validated against captured prompt citations and changed diff regions, then recorded for hosted review. They are not proof that an implementation is correct or complete. See the feature guide and known limitations.

Cross-repo implementations

Agent work often becomes one story that spans more than one repository: an API change in one repo, a client update in another, and a UI or docs follow-up in a third. Semantica tracks that work as an implementation so the related repos, sessions, commits, and summary stay grouped together.

semantica implementations or semantica impl        # show current cross-repo implementations
semantica impl <implementation_id>                 # show the implementation card/details
semantica suggest impl                             # batch suggestions and merge candidates
semantica suggest impl <implementation_id>         # suggest a title and summary for one implementation
semantica suggest impl <implementation_id> --apply # apply or override the title and summary
semantica impl close <implementation_id>           # close an implementation so later work forms a new one
semantica set auto-implementation-summary disabled # disable background title/summary generation

For implementation states, boundaries, manual controls, and --json usage for downstream tools, see the implementations guide.

Checkpoints and rewind

Every commit creates a checkpoint, and you can create checkpoints manually too. Rewind restores the working tree to a previous checkpointed state, including non-commit states and untracked, non-ignored files, without rewriting Git history:

semantica list                   # show checkpoints
semantica rewind <checkpoint>    # restore files (creates safety checkpoint first)
semantica rewind <id> --exact    # also delete files not in the checkpoint

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 suggest implementations # suggests titles and merge candidates for implementation stories.
semantica status # shows repo status, workspace tier, 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.

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.
• semantica-intent-gap - run intent-gap analysis on the current PR; surfaces requested-but-missing work, unrequested code, or deferred trajectories using your installed AI CLI.

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 checkpoint 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. semantica launcher enable can move that background work under the OS launcher backend on supported platforms.

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 disable

The launcher is experimental and currently 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. Use it when commits are often created through agent-driven workflows and you want the post-commit work to run more reliably than the default detached worker path.

---

Supported AI providers

Provider	Hook config	Detection
Claude Code	.claude/settings.json	Auto
OpenAI Codex	~/.codex/hooks.json, ~/.codex/config.toml	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. 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
implementations [id]	List or inspect cross-repo implementation stories
suggest commit	Generate a commit message from uncommitted changes
suggest pr	Generate a PR title and body from the current branch diff
intent-gap analyze	Analyze captured PR intent and record advisory findings
suggest implementations	Suggest titles, summaries, and merge candidates for implementations
tidy	Preview or remove stale local Semantica state
checkpoint	Manually create a checkpoint
rewind <id>	Restore working tree to a checkpoint
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 (checkpoints, sessions, events, attribution, playbooks)
  objects/            # content-addressed blob store (SHA-256, zstd compressed)
  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.

Cross-repo implementations are indexed in Semantica's global state under $SEMANTICA_HOME/implementations.db.

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
• Implementations - cross-repo implementation states, commands, boundaries, and JSON output
• 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.