Getting started

Ingrain runs as a hook inside your agentic coding harness — Claude Code, Cursor, or spec-kit. The harness invokes ingrain automatically at the right moments.

This page walks through that flow end to end. It assumes you have the CLI installed and on your PATH.

1. Bring your own LLM key

Ingrain runs the analysis through an LLM provider you supply credentials for — OpenAI, Anthropic, or Google. Pick one, then drop the provider name and your API key into ~/.ingrain/conf.toml:

[agent.model]
provider = "openai"
name = "gpt-5.4-mini"

[agent.apiKeys]
openai = "sk-..."

Open the file quickly (it is seeded on first run):

ingrain config

See [agent.model] for supported providers and [agent.apiKeys] for which key each provider needs.

2. Register the hook in your harness

Run the init variant matching the harness you use. This is a one-time setup per machine — it writes the hook entry into the harness’s own configuration.

Claude Code

ingrain init-claude

Registers a PreToolUse hook in your Claude Code settings so Claude invokes ingrain hook --harness=claude at the right lifecycle points.

Cursor

ingrain init-cursor

Same idea, configured for Cursor’s hook format.

spec-kit

ingrain init-speckit

Interactive — discovers spec-kit repos in your workspace and lets you pick which ones to register the after_plan hook into.

3. Drive your harness as usual

Use Claude Code, Cursor, or spec-kit normally. When the harness reaches a hook point — Claude Code about to apply a generated plan, or spec-kit just finishing one — it calls ingrain hook for you.

4. Review threats and mitigations

The harness invokes ingrain hook non-interactively, so Ingrain opens a new terminal window to run the TUI. The window uses your platform’s terminal — Windows Terminal or PowerShell on Windows, the first detected emulator on Linux, iTerm or Terminal.app on macOS. If detection fails, the hook errors out and points you at [hook].terminal in conf.toml — see [hook] configuration.

The TUI streams the analysis:

TUI controls

Key	Action
↑ / ↓	Navigate items
← / →	Rotate between groups / submit actions
Enter	Toggle selection / submit
Ctrl+C	Exit without submitting

When you submit, the spawned terminal closes automatically and the hook returns the review to your harness:

• Claude Code receives a deny response with the selected mitigations as Markdown, prompting Claude to incorporate them before continuing.
• Spec-kit receives the review on stdout in its after_plan output format.

If you exit the TUI without submitting (Ctrl+C or closing the spawned window), the hook returns “no opinion” and your harness proceeds unchanged.

Optional: run a one-off analysis manually

For ad-hoc reviews outside any harness, point analyze at a Markdown task description directly:

ingrain analyze --description-file ./task.md

The first # heading becomes the task title; the rest is what the agent reasons over. Pass --review-file ./review.md to also write the result to disk. See analyze for all flags.

Next steps

• Browse the full command reference.
• Tune defaults via Configuration.