https://github.com/firelock-ai/kin
Local-first semantic version control for AI-native teams. Git stores text history. Kin understands code.
https://github.com/firelock-ai/kin
ai ai-agents ai-native developer-tools graph-database mcp open-source rust semantic semantic-version-control tree-sitter vcs version-control
Last synced: 20 days ago
JSON representation
Local-first semantic version control for AI-native teams. Git stores text history. Kin understands code.
- Host: GitHub
- URL: https://github.com/firelock-ai/kin
- Owner: firelock-ai
- License: apache-2.0
- Created: 2026-03-10T21:09:53.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-16T03:01:46.000Z (20 days ago)
- Last Synced: 2026-06-16T03:14:57.478Z (20 days ago)
- Topics: ai, ai-agents, ai-native, developer-tools, graph-database, mcp, open-source, rust, semantic, semantic-version-control, tree-sitter, vcs, version-control
- Language: Rust
- Homepage: https://firelock.ai/labs/kin
- Size: 9.87 MB
- Stars: 42
- Watchers: 1
- Forks: 3
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
# Kin — The Semantic System of Record for Software Work
Kin is a semantic, graph-first repository and collaboration substrate for AI-native software development. Unlike traditional file-first, diff-first systems (like Git), Kin represents software as a semantic graph of entities (functions, methods, classes, structs, traits, enums, interfaces, types, constants) and relations (calls, imports, references, inheritance).
In Kin, the graph is the source of authority. The filesystem is a derived projection over that graph truth, made transparently available to existing editors and compilers through the `kin-vfs` virtual filesystem.
## Core Features
- **Semantic VCS**: Version control at the level of entities and relations instead of lines and files.
- **AI-native context packs**: Build structured context packs containing a target entity plus its caller/callee neighborhood in a single call (`kin context`).
- **Trace & dataflow**: Trace call chains and dataflow dependencies in one step instead of looping over file reads (`kin trace`, `kin trace-data-flow`).
- **Ejectable brownfield compatibility**: Works alongside Git and traditional toolchains. `kin eject` removes Kin and restores files to their pre-init state, so there is no data lock-in.
---
## Installation
Install Kin with a single command:
```sh
curl -fsSL https://get.kinlab.dev/install | sh
```
The installer downloads the latest release from GitHub, places the `kin` and `kin-vfs`
binaries into `~/.kin/bin`, updates your shell profile (`.zshrc` / `.bashrc`), and then
runs the interactive setup wizard.
### Installer configuration
Configure the installer with environment variables:
- `KIN_VERSION`: Pin a specific version to download (e.g. `0.1.0`). If omitted, the latest release is resolved automatically.
- `KIN_DIR`: Custom installation directory (defaults to `~/.kin`).
- `KIN_NO_SETUP`: Set to `1` to skip the interactive setup wizard after the binaries are downloaded.
### Runtime configuration
The Kin daemon is the canonical authority for graph truth. Commands that analyze the
graph in-process (`kin merge`, `kin release`, `kin semver`, `kin rollback`, `kin git export`)
read from the daemon and auto-start it as needed — no configuration required for normal use.
- `KIN_NO_DAEMON`: Set to `1` to disable daemon auto-start. The CLI will only use an
already-running daemon (or `KIN_DAEMON_URL`).
- `KIN_DAEMON_URL`: Point the CLI at an explicit daemon endpoint instead of the
repo-local one.
- `KIN_ALLOW_DAEMON_BOOTSTRAP_ADMIN`: Offline/admin escape hatch. Set to `1` to let
the above read-only commands fall back to reading the local `.kin` snapshot directly
when the daemon cannot be reached. Not needed for normal use, and never used for
writes — all graph mutations still route through the daemon.
---
## Quickstart
See [docs/quickstart.md](docs/quickstart.md) for the full end-to-end walkthrough.
### 1. Initialize a repository
Build a semantic graph over your codebase:
```sh
kin init
```
*Options:*
- `[PATH]`: Directory to initialize (defaults to the current directory).
- `--force`: Initialize even if a `.git/` directory is detected.
- `--git-history `: Git history import depth (default: `recent`).
- `--no-lsp`: Skip LSP enrichment for a faster, tree-sitter-only init.
### 2. Add embeddings (enables semantic search)
`kin init` builds the graph instantly without embeddings. Run `kin embed` to add the
vector index that powers semantic search and `kin locate`:
```sh
kin embed
```
Embeddings are generated locally with `nomic-embed-text-v1.5` (768 dimensions; override
via `KIN_EMBED_MODEL_ID`). `kin status --json` reports embedding coverage under its
`enrichment` block (`embeddingsIndexed` / `embeddingsPending` / `embeddingsTotal`).
### 3. Configure your system and shell
Run the setup wizard, or run health checks at any time:
```sh
kin setup
```
*Options:*
- `status`: Show what's installed.
- `doctor`: Run a quick health check.
- `--mode `: Repository operation mode.
- `--shell `: Target shell for profile updates.
- `--auto-daemon`: Auto-start `kin-daemon` when entering workspaces.
### 4. Everyday commands
- **Status of the working copy**:
```sh
kin status [--json]
```
- **Commit changes semantically**:
```sh
kin commit -m "commit message"
```
- **Show the change log**:
```sh
kin log [-n ]
```
- **Semantic diff**:
```sh
kin diff [] []
```
- **Search entities** (add `--semantic` for vector similarity over what is embedded):
```sh
kin search "" [--semantic] [--show-body]
```
- **Locate files relevant to an issue**:
```sh
kin locate "" [--explain]
```
- **Eject and restore files**:
```sh
kin eject [--force]
```
---
## MCP Server Integration
Kin ships with a built-in MCP (Model Context Protocol) server that exposes semantic tools
to AI assistants (Claude, Cursor, Gemini, Codex, etc.). It runs as a stdio server that the
MCP client launches as a subprocess:
```sh
kin mcp start
```
For the full tool surface, see [docs/mcp-tools.md](docs/mcp-tools.md).
---
## Architecture & Thesis
To understand the philosophy behind Kin, see the [thesis document](docs/thesis.md).