Skillget

kin

mcp
SUMMARY

Local-first semantic version control for AI-native teams. Git stores text history. Kin understands code.

README.md

Kin

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,900+ tests, validated benchmarks, working brownfield migration), but APIs and CLI surface will evolve. Install via curl -fsSL https://get.kinlab.dev/install | sh or build from source with Cargo.

CI
codecov
License: Apache-2.0
Rust
Status: Alpha

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

Kin demo: init, import, commit, status, overview, and trace on a sample project

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

Git vs Kin on the Kin repo: grep versus semantic trace and impact

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:

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: run kin eject 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.

Install

# One-line install (macOS/Linux)
curl -fsSL https://get.kinlab.dev/install | sh

# Or via cargo
cargo install --locked --path crates/kin-cli

# Then run interactive setup
kin setup

Getting Started

# 1. Install
curl -fsSL https://get.kinlab.dev/install | sh

# 2. Initialize on any project
cd my-project
kin init .

# 3. Extract entities and commit
kin git import .
kin commit -m "initial semantic commit"

# 4. Explore
kin status                    # See entity counts and graph state
kin search "authentication"   # Semantic search across the graph
kin overview                  # High-level codebase summary
kin impact                    # Analyze downstream impact

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.

# Auto-configure for Claude Code / Cursor
kin setup   # Select AI Assistants in the wizard

# Or manually
claude mcp add kin -- npx -y kin-mcp
codex mcp add kin -- npx -y kin-mcp
gemini mcp add kin -- npx -y kin-mcp

MCP setup: one command, zero config

The npx 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, use the standalone kin install via curl | sh or cargo install.

Start the MCP server with kin mcp or configure it as an MCP server in your assistant's settings.

Adopting Kin on an existing Git repo

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: run kin eject 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.

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 Graph engine substrate
kin-vfs Alpha Virtual filesystem — serves files from blob store
kin-vscode Alpha Lightweight VS Code extension (replaces kin-code fork)
kin-code Deprecated Editor shell (VS Code fork) — replaced by kin-vfs + kin-vscode
kin-pilot Archived Agent shell (Codex fork) — replaced by kin-mcp
KinLab 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

Yorumlar (0)

Sonuc bulunamadi