Kin

Git stores text history. Kin understands code.

Kin is the semantic system of record for software work. It replaces the file-first, diff-first repository model with a graph of semantic entities and relationships, then serves precise context to AI agents and developers. Kin is not a coding assistant or a Git wrapper -- it is a sovereign VCS and the semantic operating layer that any assistant can use. kin init works with or without .git.

Latest checked result: on a validated 10-repo Codex CLI sweep, kin-native won 69/70 task comparisons while using 50.0% less wall-clock time and 44.6% fewer tokens than raw Git exploration. The benchmark methodology, per-repo matrix, and caveats are published in docs/benchmarks/validated-popular-repos-2026-03-20.md.

Alpha -- Kin is in active development. The core thesis is proven (1,400+ tests, validated benchmarks, working brownfield migration), but APIs and CLI surface will evolve. Standalone source builds now work from this repo directly; Cargo will fetch the current kin-db / kin-model dependency set from the kin-db repo. Prebuilt release artifacts are still the easiest way to try the CLI.

---

Proof

Kin is making a measurable claim, not a branding claim.

• Validated benchmark sweep -- 69/70 wins across 10 popular repos and 70 checked task comparisons
• Speed -- 50.0% less wall-clock time overall (1659.7s for Git vs 829.8s for Kin-native)
• Efficiency -- 44.6% fewer tokens overall (5,539,366 for Git vs 3,068,820 for Kin-native)
• Breadth -- 10 validated repos spanning JavaScript, TypeScript, and Python; this is repo breadth, not a claim of full language coverage
• Validation -- randomized planted artifacts, identical prompts, automatic scoring, and published raw run artifacts

Read the checked benchmark summary: docs/benchmarks/validated-popular-repos-2026-03-20.md.

---

Demo

Real CLI output on a sample project. kin init + kin git import adopts an existing repo, kin commit materializes the semantic graph, and kin trace resolves any symbol through the graph in one hop.

---

Git vs Kin

This is the comparison that matters in practice: the same real repo, the same question, and two different substrates. Git can find text. Kin can resolve the symbol semantically and show downstream impact directly.

Additional real-repo demos:

• KinDB comparison
• KinLab comparison

---

Why Kin?

• The file-first model is the bottleneck -- AI agents should not have to repeatedly reconstruct software structure from files, line diffs, grep passes, and transient context windows. Kin makes semantic truth primary and treats files as projections.
• Precise context delivery -- Graph-traversal context under token budgets, not file dumping. AI assistants get exactly the entities they need, with signatures for dependencies.
• Identity tracking across refactors -- Semantic fingerprints survive renames, moves, and formatting changes. Kin knows processOrder and handle_order are the same function.
• Semantic review -- Review changed entities and their impact graph, not line diffs. See what a change actually affects.
• Provenance and trust -- Every change carries evidence of who or what made it and why, with full execution traces.
• Git interop -- Import from Git, export to Git, but Git is not required. Kin adoption is reversible: delete .kin/ and your source files remain untouched.
• Measurable results -- The latest checked sweep came in at 69/70 wins, 50.0% less wall-clock time, and 44.6% fewer tokens against validated Git-based exploration.

---

Recommended Adoption Path

# Prerequisites: Rust stable (2021 edition)
git clone https://github.com/firelock-ai/kin.git
cd kin
cargo install --locked --path crates/kin-cli

# Adopt an existing repo
kin init /path/to/your/project
cd /path/to/your/project
kin git import .
kin commit -m "materialize semantic state"

# Success criteria
kin status        # entity counts are > 0
kin trace <entity> # resolves a symbol semantically

That is the recommended first path for real adoption: initialize the repo, import Git history, materialize the semantic graph, and confirm that kin status shows non-zero entities and kin trace resolves through semantic state instead of source-text fallback.

If you only want the MCP server for Claude Code, Codex, or Gemini CLI, the npm wrapper is the lowest-friction path:

claude mcp add kin -- npx -y kin-mcp
codex mcp add kin -- npx -y kin-mcp
gemini mcp add kin -- npx -y kin-mcp

The wrapper downloads the matching Kin release binary on first run, verifies the published checksum, caches it locally, and auto-initializes a .kin/ repo if one doesn't exist. For full CLI workflows, keep the standalone kin install.

kin git import reads your Git history. The follow-up kin commit materializes the semantic graph (entity extraction, fingerprinting, relation mapping). After that, kin status shows entity counts and kin trace resolves symbols through the graph rather than falling back to source text.

Kin adoption is reversible: delete .kin/ and your source files remain untouched. You can still kin push and kin pull against regular Git remotes — Kin-native mode does not require your collaborators to use Kin.

For day-to-day brownfield use, treat Kin as the local VCS and GitHub as the transport. kin push and kin pull keep a hidden .git-export/ mirror in sync with the remote, so you do not have to use the checked-out .git repo as your primary interface once Kin is initialized.

---

Key Workflows

You do not need to memorize a huge command catalog to get value from Kin. Most day-one usage falls into four workflows:

Workflow	Start Here	What You Get
Understand one symbol fast	kin trace, kin context, kin refs, kin impact	Resolve a focal entity, build a narrow context pack, inspect callers/importers, and see downstream blast radius
Review and verify changes	kin diff, kin review, kin verify, kin audit	Entity-level change review, semantic risk signals, coverage checks, and provenance
Work in native mode	kin mode, kin with, kin open, kin reconcile, kin exec	Materialized workspaces, Kin-guided assistant sessions, and graph-backed reconciliation
Adopt without a flag day	kin init, kin git import, kin git export, kin remote, kin push, kin pull, kin mcp	Brownfield migration, Git coexistence, remotes, and assistant-neutral integration

For the full CLI surface, run kin --help and kin <command> --help.

---

Language Support

Tier 1 -- full entity extraction, relation extraction, fingerprinting, and contract adapters:

• TypeScript / JavaScript
• Python
• Go
• Java
• Rust

Parsing is powered by Tree-sitter with per-language adapters.

---

MCP Integration

Kin exposes its semantic graph through the Model Context Protocol, making it assistant-neutral. Any MCP-compatible tool -- Claude Code, Codex, Gemini CLI, Cursor, or others -- can query semantic search, impact analysis, dead code detection, review state, and more.

Start the MCP server with kin mcp or configure it as an MCP server in your assistant's settings. For assistant-native setup without a prior Kin install, use npx -y kin-mcp.

---

Benchmarks

We benchmark Kin against raw Git exploration using a validated task suite, not hand-picked demos.

Latest checked sweep:

• 10 popular open source repos (Express, Axios, Hono, Zod, Flask, Typer, Requests, Redux, Click, Day.js)
• 70 validated task comparisons (7 tasks x 10 repos)
• Assistant: Codex CLI 0.114.0
• Result: 69/70 wins, 50.0% less wall-clock time, 44.6% fewer tokens
• Scope: JavaScript, TypeScript, and Python only; Rust was excluded from the published matrix

Important caveats:

• This checked sweep is a strong proof of the current wedge, not a claim that every language or repository shape is equally covered.
• The run used one assistant configuration and one repetition per repo.
• The checked run was not on a lab-clean machine; see the linked methodology doc for the exact caveats and environment notes.

How We Keep It Fair

• Same assistant binary, same machine, same repo snapshot, same task set for both arms.
• Every run uses --fresh-conversion -- Kin rebuilds its graph from scratch.
• Planted artifacts carry random tags and secret values -- the assistant cannot answer from training data.
• Validation is automatic against planted ground truth. No manual scoring.
• Conversion cost is reported separately from per-task timings.

Full benchmark methodology and per-repo results: docs/benchmarks/validated-popular-repos-2026-03-20.md. Reproducing the sweep locally will write raw run artifacts under .kin/bench/.

# Reproduce
cargo build --release -p kin-cli
python3 scripts/run_popular_validated_benchmarks.py --assistant codex

---

Architecture Overview

Kin organizes code understanding into four planes:

┌─────────────────────────────────────────────────────────────┐
│                     SEMANTIC PLANE                          │
│  Entities, Relations, Contracts, SemanticChanges, Specs     │
│  ↕ source of truth                                          │
├─────────────────────────────────────────────────────────────┤
│                     PROJECTION PLANE                        │
│  Source files, Git commits, PR views, Living docs           │
│  ↕ rendered from semantic state                             │
├─────────────────────────────────────────────────────────────┤
│                     EXECUTION PLANE                         │
│  Local workspaces, Validation runs, Evidence capture        │
│  ↕ proves correctness                                       │
├─────────────────────────────────────────────────────────────┤
│                     CONTROL PLANE                           │
│  Reviews, Governance, Assistant adapters, Benchmarks        │
│  ↕ manages quality and trust                                │
└─────────────────────────────────────────────────────────────┘

Semantic entities are the source of truth. Files are projections of semantic state -- rendered outputs, not primary artifacts. The embedded KinDB graph engine stores topology, metadata, signatures, and fingerprints. A content-addressable blob store holds raw code text.

---

Crate Architecture

Kin is built as 18 Rust crates in this workspace plus the shared kin-model crate shipped from the kin-db repo. Key crates:

Crate	Description
kin-cli	CLI with full command set
kin-daemon	Background service: file watch, incremental indexing, reconciliation
kin-core	Shared runtime, config, error types
kin-model	Canonical types: Entity, Relation, Contract, SemanticChange, Spec (consumed from the kin-db repo)
kin-db	Embedded graph engine (released in tandem as its own repo)
kin-parser	Tree-sitter parsing and language adapters
kin-context	Token-budgeted context pack builder with semantic slicing
kin-mcp	MCP server -- assistant-neutral integration surface

---

Status

Kin is in public alpha.

What's solid:

• Core data model (Entity, Relation, SemanticChange, Fingerprint)
• Embedded graph database (KinDB) with snapshot persistence and read indexes
• Content-addressable blob store
• Tree-sitter parsing pipeline for all Tier 1 languages
• CLI command structure and routing
• Git import/export adapter
• MCP server protocol
• Validated benchmark suite (69/70 wins against Git-based exploration)

What's still hardening:

• Reconciliation loop edge cases (broken ASTs, partial parses)
• Semantic merge conflict resolution
• Multi-workspace coordination
• Performance optimization on large repos (100k+ entities)
• Living docs projection

We ship what works and are transparent about what doesn't yet. If you hit a rough edge, open an issue.

---

Ecosystem

Only kin and kin-db are shipping in this public alpha. The rest of the stack is active infrastructure around it, with some surfaces still hardening rather than speculative.

Component	Status	Description
kin	Shipping now	Semantic VCS (this repo)
kin-db	Shipping now	Apache-licensed graph engine substrate
kin-stack	Active	Bootstrap, orchestration, config, validation, benchmarks, and migration support
kin-code	Active, hardening	Editor shell
kin-pilot	Active, hardening	Agent shell
KinLab	Active, hardening	Hosted collaboration layer

---

Contributing

See CONTRIBUTING.md for build instructions, PR process, and code style guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

Kin is licensed under the Apache License 2.0. See LICENSE for the full text.

KinDB, the embedded graph engine under Kin, is also Apache-2.0.

---

Created by Troy Fortin at Firelock, LLC.

---

"So neither the one who plants nor the one who waters is anything, but only God, who makes things grow." -- 1 Corinthians 3:7