Kontrua - Context that stays true to your code

CLI

Run Kontrua locally with your own Anthropic API key.

Installation

Install globally:

npm install -g kontrua

Or as a dev dependency:

npm install -D kontrua

Requires Node.js 20+ and a git repository.

Commands

Command	Description
`kontrua init`	Scaffold .kontrua.yml config and install git hooks (post-commit, post-merge)
`kontrua update`	Read recent git changes and update documentation
`kontrua preview`	Dry run - shows what would change without writing files
`kontrua ci <provider>`	Generate CI/CD config (github, gitlab)
`kontrua context pull`	Fetch the latest context artifacts from your Kontrua instance into the working tree

Pulls the repository's current context layer (AGENTS.md, codemap, conventions, and architecture facts when enabled) from Kontrua into your working tree - useful for local agents that read files rather than MCP. Authenticate with a per-repo API token from the dashboard:

export KONTRUA_TOKEN=<your repo API token>
kontrua context pull                # write artifacts into the current directory
kontrua context pull --dry-run      # preview without writing
kontrua context pull --include-docs # also pull doc views (README, API, changelog)

Flag	Description
`--url <url>`	Kontrua instance base URL (default: https://kontrua.com)
`--token <token>`	Per-repo API token (or set KONTRUA_TOKEN)
`--dir <path>`	Directory to write into (default: current directory)
`--include-docs`	Also pull doc views
`--dry-run`	Show what would be written without writing

MCP server

Kontrua also serves the context layer over the Model Context Protocol, so MCP clients (Claude Code, Cursor, and others) can fetch fresh context on demand instead of reading files. Point your client at the endpoint with the same per-repo API token as a Bearer header:

{
  "mcpServers": {
    "kontrua": {
      "type": "http",
      "url": "https://kontrua.com/api/mcp",
      "headers": { "Authorization": "Bearer <your repo API token>" }
    }
  }
}

The server exposes two tools: get_context (the current artifacts, optionally with doc views) and get_freshness (freshness state, commit lag, last refresh). The token maps to exactly one repository, so an agent can never read another tenant's context.

kontrua update flags

Flag	Description
`--repo <path>`	Path to repo root (default: current directory)
`--since <ref>`	Update based on changes since a git ref (e.g. HEAD~5)
`--range <range>`	Update based on a git ref range (e.g. abc123..def456)
`--trigger <type>`	Trigger type: commit or merge (used by git hooks)
`--dry-run`	Preview changes without writing files

Output modes

Configured via output.mode in .kontrua.yml:

Mode	Behavior
`file-only`	Write files to disk. You stage and commit manually.
`commit`	Auto-commit doc changes after generation.
`pr`	Create a local branch with doc changes.

.kontrua.yml

Running kontrua init creates this default config:

.kontrua.yml

version: 1

ai:
  model: claude-sonnet-4-6
  # apiKey: ${ANTHROPIC_API_KEY}

docs:
  readme:
    enabled: true
    template: default
    output: README.md

  api:
    enabled: true
    template: default
    output: docs/API.md
    include:
      - "src/**/*.ts"
      - "src/**/*.js"

  architecture:
    enabled: true
    template: default
    output: docs/ARCHITECTURE.md

  changelog:
    enabled: true
    template: default
    output: CHANGELOG.md
    format: keepachangelog

output:
  mode: file-only
  commitMessage: "docs: auto-update documentation"
  prBranch: docs/auto-update

exclude:
  - "node_modules/**"
  - "dist/**"
  - "**/*.test.ts"
  - "**/*.spec.ts"

Config reference

Key	Description
`ai.model`	Which Claude model to use (default: claude-sonnet-4-6)
`ai.apiKey`	API key via env var reference ${ANTHROPIC_API_KEY}, or set the env var directly
`docs.*`	Enable/disable each doc type, set output paths, choose templates
`docs.api.include`	Glob patterns for source files (use ['auto'] to auto-detect)
`docs.changelog.format`	keepachangelog or conventional
`output.mode`	file-only, commit, or pr
`exclude`	Glob patterns to skip

The CLI calls the Anthropic API directly using your API key. It does not connect to the Kontrua server, use your Kontrua account, or count against your SaaS quota.

Ready to keep your repo's context current?

Connect your first repository and Kontrua opens a reviewed PR with AGENTS.md, a codemap, and your conventions.

Get started for free View pricing