Introduction

Overview & Architecture

ink is an open-source CLI tool designed for engineers who want to retain what they build. Every time you write code and commit, it parses your Git diff, filters irrelevant lockfiles, and prompts an LLM to extract architectural rationale, trade-offs, and concepts directly into your local Obsidian vault.

100% Local Markdown Notes

Notes are stored directly in your Obsidian vault as standard Markdown files with bidirectional wikilinks ([[Concept]]).

Active Recall & SM-2 Quizzes

Automatically schedules recall reviews using SuperMemo-2 spaced repetition so you never forget how you solved complex problems before technical interviews.

Setup

Installation & Global CLI Setup

Clone the repository, compile the TypeScript source with npm run build, and link it globally with npm link so the command is instantly available in any terminal window and across all your repositories:

Terminal (PowerShell / macOS / Linux)

# 1. Clone repository

$ git clone https://github.com/Tanay-77/ink.git

$ cd ink

# 2. Install dependencies

$ npm install

# 3. Compile TypeScript into dist/

$ npm run build

# 4. Register global CLI symlink

$ npm link

Important: Run both 'npm run build' and 'npm link'

• npm run build compiles TypeScript files into executable ES modules in dist/cli.js.
• npm link links that executable into your system PATH so you can type ink anywhere.

Verify with ink --help. When updating your code later, just run npm run build.

Walkthrough

3-Minute Quickstart

1Set Your Global API Key Once

Save your API key in your home directory so all projects detect it automatically:

mkdir -p ~/.ink && echo "API_KEY=your_key" > ~/.ink/.env

2Initialize in Any Repository

Navigate into your project folder and specify your Obsidian vault path:

$ ink init

3Generate Your First Study Note

Analyze your latest commit on-demand:

$ ink run HEAD

✓ Open Obsidian — your note is already linked under commits/ and concepts/!

Settings

Configuration & API Keys

API keys are stored in your home directory (~/.ink/.env), while per-project preferences are saved in .ink.json:

{
  "vaultPath": "C:/Users/name/Documents/ObsidianVault",
  "provider": "gemini",
  "model": "gemini-2.0-flash",
  "ignore": ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"],
  "maxDiffChars": 24000,
  "fuzzyThreshold": 0.75
}

vaultPath (required)Path to your Obsidian vault.

ignore (array)Files excluded from diff parsing.

maxDiffChars (number)Diff character limit (default 24,000).

Providers

Supported AI Models

ink works with any major AI provider:

Provider	Default Model	Environment Key	Performance
Google Gemini (Default)	gemini-2.0-flash	GEMINI_API_KEY	Sub-second latency, generous free tier
Anthropic Claude	claude-3-5-sonnet-latest	ANTHROPIC_API_KEY	Deep architectural nuance and edge cases
OpenAI	gpt-4o	OPENAI_API_KEY	Solid general-purpose diff analysis

CLI

CLI Command Reference

$ ink init

Setup

Interactively configures your Obsidian vault path, AI provider, and target model. Generates .ink.json.

Enter Obsidian vault path: /Users/tanay/Vault

Choose provider (gemini | anthropic | openai) [gemini]: gemini

Choose model name [gemini-2.0-flash]: gemini-2.0-flash

✓ Configuration written to .ink.json

$ ink run [sha]

On-demand

Analyzes a specific commit or default latest (HEAD), filters file diffs, extracts architectural concepts, and writes Markdown notes with bidirectional wikilinks to your Obsidian vault.

$ ink run HEAD

$ ink run a1b2c3d --model gemini-2.0-flash

$ ink install-hook

Background Automation

Installs an asynchronous, non-blocking post-commit hook in .git/hooks/post-commit. Every time you commit, notes generate silently in the background without blocking git.

$ ink install-hook

To remove the hook cleanly: $ ink uninstall-hook

$ ink quiz [--cli]

Active Recall

Inspects your Obsidian vault for concept notes due for review today based on SM-2 spaced repetition. Generates an Obsidian review note or runs interactive flashcards directly in the terminal with --cli.

$ ink quiz --cli

$ ink explain [sha]

Interview Practice

Puts you in the hot seat! The CLI prompts you to articulate your commit in plain words like in a Staff/Principal interview. Scores your response from 0 to 5 on accuracy, missed edge cases, and follow-ups.

$ ink explain HEAD

Storage & Organization

Obsidian Vault Structure & Multi-Repo Graph

Inside your Obsidian vault, ink maintains a clean, three-folder hierarchy with standard bidirectional wikilinks ([[Concept]]):

MyObsidianVault/
├── commits/
│   ├── 2026-10-24-feat-auth-middleware.md
│   └── 2026-10-25-refactor-database-queries.md
├── concepts/
│   ├── JWT-Blacklisting.md
│   └── Connection-Pool-Exhaustion.md
└── quizzes/
    └── 2026-10-24-daily-quiz.md

Multi-Repo Knowledge Graph

Point multiple repositories to the same Obsidian vault. Concepts like [[OAuth2]] or [[Redis Caching]] automatically interconnect across frontend, backend, and microservices in Obsidian's graph view.

SM-2 Spaced Repetition Frontmatter

Every concept note includes frontmatter metadata (interval, easeFactor, nextReviewDate), fully compatible with Obsidian flashcard plugins.

Assistance

Troubleshooting & FAQ

"command not found: ink"

Make sure you ran npm run build followed by npm link in the ink root directory. On Windows, verify that your global npm path (%AppData%\npm) is in your user PATH.

"Missing API key environment variable"

Create ~/.ink/.env or export API_KEY in your terminal. Restart your terminal window after editing environment variables.

Does ink slow down my Git commits?

No. The background hook spawns a detached, asynchronous child process. Your git commit finishes in milliseconds without waiting for the network response.

Are private codebases safe?

Yes. ink has no central backend, database, or telemetry. Diff chunks are sent directly from your terminal to your configured AI provider (Google, Anthropic, or OpenAI) using your own API key.