GUIDE · AGENTS

Coding-agent integration

Search primitive

Literal search requires an agent to enumerate inflections for every task. A query for 걷다 may need 걷고, 걸어, and 걸었다. kfind compiles the lemma and POS into one plan, so identical input produces the same candidates and rule provenance.

kfind does not select a word sense. The agent reads the code around each broadly recalled span and keeps the candidates relevant to the task. Separating morphology from context makes the search reproducible without removing contextual judgment from the agent.

Recommended workflow

1. Scope and POS

   Narrow the file paths and tag each atom with n:, v:, or another explicit POS.

2. Recall-first boundary

   Use --embedded --boundary any to avoid resource startup and structural rejection.

3. Structured output

   Read UTF-8 spans, POS, and rule provenance from --json output.

4. Context review

   Inspect adjacent code and discard irrelevant homographs.

kfind --embedded --boundary any --json 'n:사용자 v:검증하다' src
kfind --embedded --boundary any --pos verb --json 걷다 crates

Integration installation and removal

kfind --init installs an agent-specific SKILL.md and project hooks in the current project. Interactive terminals offer a target picker. Automation can repeat --agent or supply target names on stdin. Existing unmanaged skills and agent settings are preserved.

kfind --init
kfind --init --agent codex --agent claude-code
printf 'codex
gemini
' | kfind --init

Remove the same integrations with --uninstall.

kfind --uninstall --agent codex --agent claude-code
printf 'codex
gemini
' | kfind --uninstall

Removal deletes only kfind-managed skills and kfind --agent-hook handlers. Other agent settings and hooks are preserved, and an already absent integration is a successful no-op.

A Homebrew-managed skill points to the stable opt path instead of a versioned Cellar path. Existing project links therefore use the new guidance after brew upgrade.

Project hooks run after each agent's trust review. In Codex, inspect and trust them with /hooks. The SessionStart hook adds an instruction to use kfind for Korean lemma and inflection searches in source code and documentation, even when the skill is not selected automatically. The pre-tool hook blocks rg, grep variants, and git grep when their search pattern contains Korean text without explicit fixed-string mode, then directs the agent to kfind. Exact searches with -F, --fixed-strings, or fgrep are allowed.

Supported agents

All three integrations use the same search contract. Each agent reads the repository-local skill, the SessionStart hook always injects its selection rule, and the pre-tool hook checks literal shell searches.

Automation patterns

A forbidden-expression check can use the --quiet exit status. Refactoring discovery retains JSON Lines and deduplicates by path and span. When lemma order matters, use a phrase query and --max-gap instead of merging separate commands.

kfind --pos verb --quiet 사용하다 docs && exit 1
kfind --embedded --boundary any --json 'n:권한 v:검증하다' src | jq -c 'select(.type == "match")'

Reduce the path and glob before changing the search policy when output is large. A separate full-POS smart search is available when a human workflow needs structural precision.

Integration contract

Results go to stdout; diagnostics and errors go to stderr. Exit status 0 means at least one match, 1 means no match, and 2 reports usage, input, or resource errors. Every JSON Lines match record contains the path, line, source text, UTF-8 byte spans, and provenance.

Bound large output by path and glob first. Unlike the interactive TTY pager, --json, --count, and --quiet remain non-interactive streams. Agents parse JSON fields and exit statuses, never localized human-readable output.