Getting Started

ktext is a single binary. Install it with go install or download a release, then run it in any Git repository.

Install

go install github.com/arithmetike/ktext/cmd/ktext@latest

Or download a pre-built binary for your platform from the releases page. Binaries are available for Linux, macOS, and Windows on amd64 and arm64.

ktext init

Run ktext init at the root of any repository. The scanner reads your README, Makefile, package manifests (package.json, go.mod, Cargo.toml), ADRs, CONTRIBUTING.md, directory structure, and docker-compose files to make initial guesses.

$ ktext init
Scanning repo...
  ✓  Identity: my-service (service)
  ✓  Purpose from README
  ✓  Build commands from package.json (3 scripts)
  ✓  Directory structure (6 directories)
  ✓  4 decisions from ADRs

Review discovered values (Enter to accept, or type a new value):
  name       my-service
  url        https://github.com/org/my-service
  purpose    Handles payment processing for the checkout flow.

Written to CONTEXT.yaml (score: 72/100)
Run 'ktext validate' for detailed feedback.

Every field is reviewed interactively. Press Enter to accept a discovered value, or type a replacement. The file is only written after the review is complete.

If a CONTEXT.yaml already exists, ktext init will not overwrite it. Edit the file directly or delete it and re-run.

ktext validate

Scores the CONTEXT.yaml in the current directory across eight sections. Exits 0 if the score meets the threshold, 1 if it does not.

$ ktext validate
CONTEXT.yaml — 86/100

  ✓  identity      15/15
  ✓  constraints   18/20
  ✓  decisions     12/15
  ✓  conventions   12/15
  ✓  risks          8/10
  ✓  dependencies   8/10
  ✓  working        8/10
  ✗  ownership      5/5

Suggested fixes:
  • constraints[1]: "be careful with auth" → add actionable language: must, never, always, require, etc.
  • decisions[0]: rationale is too short — expand with specific reasons

PASS  86/80

ktext export

Renders CONTEXT.yaml to a different format. Output goes to stdout by default so you can inspect it before writing.

ktext export xml               # render to stdout
ktext export -write xml        # write to context.xml
ktext export json              # render to stdout
ktext export -list             # list all supported formats

Load context at the start of an agent session

Once you have a CONTEXT.yaml, the next step is making sure your agent actually loads it. The goal is to get ktext export xml output into the agent's context before it starts any work.

Claude Code

Add a SessionStart hook to .claude/settings.json at the root of your project. Claude Code runs it automatically at the start of every new session and injects the output into context — no prompting required.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|compact",
        "hooks": [
          {
            "type": "command",
            "command": "ktext export xml"
          }
        ]
      }
    ]
  }
}

The compact matcher re-injects context after a context window compaction, so the agent never loses it mid-session.

Other tools (Cursor, Copilot, Windsurf, Cline)

Most other tools don't support dynamic context injection at session start yet. The fallback is to add a single line to your tool's instruction file telling the agent to run the export itself.

Run `ktext export xml` at the start of every session to load project context.

Use in CI

Add a validate step to any CI pipeline to enforce a minimum quality score on every pull request.

# .github/workflows/context.yml
- name: Validate CONTEXT.yaml
  run: |
    go install github.com/arithmetike/ktext/cmd/ktext@latest
    ktext validate -threshold 80

A score below the threshold exits 1 and fails the step. The output includes specific fixes so developers know exactly what to improve.