A knowledge-base (KB) driven agent, purpose-built for coding.
- DESIGN PHILOSOPHY: make the KB the central source of truth for every project.
- THE CORE GOAL: an agent that gets smarter and more useful the more you use it.
Every session's discoveries are distilled into durable knowledge, so it starts each new task already knowing what the last one learned.
English | 简体中文
- Tree-sitter AST parsing: hk2 uses native tree-sitter grammars for precise symbol extraction across 14 packages (15 grammars, since
tree-sitter-typescriptexports bothtypescriptandtsx). Falls back to regex-based parsers if grammars are not installed. - Code knowledge graph: call chains, class hierarchy, imports, and inheritance are stored as a graph under
~/.hk2/kb/<projectId>/graph/. Traversable viakb_callchain,kb_class,kb_refs,kb_implements. - Three-space KB: every project KB is split into Holy Space (stable design knowledge), Eden Space (frequently-updated catalogs/patterns), and Index Space (BM25 + graph + per-space indexes).
- Document parsing: Markdown, JSON, YAML, HTML, SGML, plain text are parsed with stdlib. PDF and Word (.docx) supported via optional
pdf-parseandmammoth. Legacy Office binaries (.doc, .pptx, .ppt) are extracted dependency-free. Docs are routed into Eden Space asdoc:<relpath>entries. - Per-request knowledge graph: for each user message, hk2 retrieves related symbols, call chains, class membership, knowledge entries, and docs from the KB, then injects them as context before the LLM responds.
- KB-first policy: the agent always tries KB tools (
kb_search,kb_symbol,kb_callchain,kb_class,kb_refs,kb_implements,kb_knowledge, etc.) before falling back tobash grep/find. Mid-turn guardrails detect violations and nudge the agent back to the KB. - Resumable builds:
/kb initsaves a checkpoint every 100 files (configurable). If interrupted, re-running resumes from the checkpoint — no re-parsing. - Auto-generated summaries: at end of
/kb init, an LLM authors three Eden entries:project-overview,architecture-diagram,architecture-decisions. Always available viakb_knowledge. - Multi-project, multi-model: one
~/.hk2/install manages unlimited projects (UUID-isolated KBs) and unlimited LLM providers/models. - Any language: C/C++, C#, JavaScript/TypeScript, Python, Go, Rust, Java, Kotlin, Scala, Ruby, PHP, Swift, Bash/Zsh, lex/yacc.
- Node.js >= 18 (Node 20 LTS recommended for Tree-sitter native compatibility)
npm installfor Tree-sitter native bindings (14 language packages)
Tree-sitter compatibility note: very new Node versions (e.g. Node 25+) may have N-API / V8 ABI mismatches with the prebuilt Tree-sitter binaries on some platforms. If
/kb initlogstree-sitter parse failed, hk2 transparently falls back to its regex-based parsers — symbol coverage is somewhat lower but the system is fully functional. For maximum precision install on Node 20 LTS or runnpm rebuildto recompile from source.
hk2 is not published to npm. Install from source:
Creates a self-contained copy of the source tree at ~/.hk2, symlinks hk2 into your PATH,
and runs npm install to build Tree-sitter native bindings.
~/.hk2serves two roles: it is the config / data home (HK2_HOME-models.json,projects.json,kb/,sessions/,logs/) and the default install dir for the source copy. Reinstalls PRESERVE user data: the installer moves the data items aside, refreshes the code tree, then moves them back (pass--preserve-data=offfor the legacy wipe). Prefernpm linkif you already have a checkout, or setHK2_INSTALL_DIRto a separate path.
git clone <repo-url> hk2 && cd hk2
./install.shCustom prefix or install location (prefix also settable via the HK2_PREFIX env var):
./install.sh --prefix=$HOME/.local
./install.sh --prefix /usr/local # same as default
HK2_INSTALL_DIR=~/.hk2-src ./install.sh # keep the source copy out of the config home
./install.sh --no-npm-install # skip Tree-sitter (regex fallback)
./install.sh --preserve-data=off # legacy wipe: do NOT preserve user data on reinstallOptional PDF / Word parsing:
cd ~/.hk2 && npm install # installs pdf-parse + mammothUninstall: remove the symlink and the source copy. Because ~/.hk2 also holds
your config and KBs, deleting the whole directory wipes those too - back up
models.json / projects.json / kb/ first, or just remove the symlink:
rm -f /usr/local/bin/hk2 # drop the launcher
rm -rf ~/.hk2/node_modules ~/.hk2/bin # remove the installed source copy, keep config + KBsCreates a live symlink to the working tree. Useful if you are hacking on hk2 itself and want changes to take effect immediately.
git clone <repo-url> hk2 && cd hk2
npm linkUninstall: npm unlink -g hk2
hk2 --help# Enter the interactive REPL
hk2Inside the REPL:
# 1. Register a project
/project init --name=myapp --source=/path/to/repo --source-root=src
# 2. Build the code index (Index Space)
/kb init
# 3. Deep-study the whole project → auto-generate Eden knowledge entries
/kb knowledge learn
# or deep-study documents (PDF / Word / PPT / Markdown) into a space:
/kb knowledge learn --space=eden --file=docs/spec.pdf
# or scope the code study to one subdirectory:
/kb knowledge learn --base-dir=src/storage
# 4. Ask a question (the agent retrieves KB context + uses tools automatically)
How does login verify the password?
# 5. Explicit KB queries
/kb search password verification
/kb symbol login
/kb neighbors 12:345
/kb knowledge list
/kb knowledge show spi-extension-pattern
# 6. Switch projects / models
/model list
/model set-default local/gpt-4o
/model use local/gpt-4o # session only
/project list
/quit
| Space | Contents | Update policy |
|---|---|---|
| Holy | Stable design knowledge (architecture, algorithms, key patterns). Manually authored or imported from authoritative sources. | Always requires explicit user approval, even when HK2_ENABLE_AUTOUPDATEKB=1 or HK2_ENABLE_AUTO_LEARN=1. |
| Eden | Frequently-updated knowledge (function catalogs, command lists, observed patterns, module summaries, parsed docs, auto-generated summaries). | Auto-updatable when HK2_ENABLE_AUTO_LEARN=1; otherwise prompts y/N. |
| Index | Code index (BM25 over symbols), knowledge graph (call chains / class hierarchy / imports / inheritance), and per-space indexes over Holy/Eden entries. | Auto-updatable when HK2_ENABLE_AUTOUPDATEKB=1; otherwise prompts y/N. |
Every project's Holy Space carries one permanent, protected entry — hk2-supreme-code — holding the project's fundamental laws: short, imperative rules that EVERY hk2 operation (reading, writing, editing, planning, answering) must obey and can never violate. It is created empty by /kb init (legacy projects get an empty shell auto-created), so nothing is enforced until you write laws into it.
- Design purpose: a single, always-visible place for the project owner to encode non-negotiable constraints — security policies, coding standards, compliance requirements — that outrank the agent's general preferences and every other KB entry.
- Injection: on each request the items are rendered into the system prompt as a
# Project Supreme Code (MUST OBEY — never violate)section placed before the KB knowledge-graph context. If an operation would violate any item, the agent must refuse it, cite the item's number, and propose a compliant alternative. - Protection: the entry itself can never be deleted, renamed, moved, emptied, imported over, or auto-updated — enforced at both the command layer and the storage layer.
Usage (the only way to modify it; every write requires an explicit y/N confirmation):
/kb code list # show all items
/kb code add --code-content="API keys are strictly forbidden in any code file"
/kb code add 1 --code-content="..." # update item 1 in place
/kb code add --code-gen="draft one rule about commit message format"
/kb code del 2 # delete item 2; later items shift up
Limits: max 100 items, 200 characters each, numbered 1..N with no gaps (/kb code add without an id appends as item N+1; an id > N+1 is rejected). Keep items short and imperative — genuinely complex rules belong in their own Holy entry, referenced from a code item as **KB(entry-id)**. /kb status shows the current count.
On /kb init, hk2 builds a code knowledge graph from the AST:
~/.hk2/kb/<projectId>/graph/
nodes.json id → node record (function / method / class / interface / struct / field)
edges.calls.json srcId → [calleeIds, ...]
edges.imports.json srcId → [importedFileNodeIds, ...]
edges.inherits.json srcId → [baseClassIds, ...]
edges.contains.json srcId → [memberIds, ...]
by_kind.json kind → [nodeIds, ...]
by_qual.json qualName → nodeId
meta.json counts + version
The graph is queried via:
- kb_callchain — bounded DFS over the call graph (forward, backward, both)
- kb_class — class / interface / struct lookup with members + implementations
- kb_refs — who calls / imports / derives from a symbol
- kb_implements — find every class that implements an interface
/kb init and /kb knowledge learn produce complementary sets of LLM-authored Eden entries. None require manual writing — both commands overwrite prior versions on each run.
/kb init writes 3 high-level structural entries (skipped with --skip-summary):
| Entry id | Contents |
|---|---|
project-overview |
600–900-word prose summary: what the project does, high-level architecture, key modules, notable patterns. |
architecture-diagram |
A Mermaid flowchart of module / layer relationships with a short legend. |
architecture-decisions |
4–8 ADR-style entries inferred from detected technologies, each with concrete modification suggestions. |
/kb knowledge learn is the unified deep-study command (it absorbed the former /kb knowledge init, which now aliases to it). It has two modes. CODE mode (no --file; --base-dir matching an indexed subdirectory, or bare) writes 3 project-wide survey entries as Phase 0, then N topic-specific entries as Phase 2. DOC mode (--file=<path> or a non-indexed --base-dir) deep-studies Markdown / PDF / Word / PowerPoint documents into the chosen space:
| Entry id | Phase | Contents |
|---|---|---|
api-docs |
0 | Numbered reference for the most important public / exported symbols across the whole project. |
code-walkthrough |
0 | 4–8 sections walking through the most central core abstractions. |
usage-examples |
0 | 3–5 numbered quickstart examples using real public symbols. |
<topic-id> (dynamic) |
2 | One entry per LLM-planned topic, each focused on a coherent subsystem (e.g. buffer-pool, transaction-mgmt, wal-replay). |
DOC mode (--file / non-indexed --base-dir) extracts entries from documents; large files are split into sequential parts so nothing is silently truncated, and every document is guaranteed to be covered by a batch (the planner's omissions get single-file fallback batches).
Scale behavior (large projects like postgres, ~3500 files): above 300 indexed files the planner switches from file-level to directory-level planning — the LLM groups directories (a ~30x smaller map), and each directory token is deterministically expanded into its concrete files, split into ≤30-file batches. If the LLM plan is still unusable (reasoning models can spend their whole budget thinking), the command retries once with reasoning disabled and finally falls back to deterministic directory grouping — the study always proceeds with full file coverage.
Plan timeouts: slow providers can exceed the default 300s planning budget; override with --plan-timeout-ms=N (or HK2_PLAN_TIMEOUT_MS).
Retrieve any of them via kb_knowledge("<id>") or kb_search_knowledge("overview").
| Command | Description |
|---|---|
/kb knowledge list [--space=holy|eden] |
List knowledge entries |
/kb knowledge show <id> |
Show full entry (searches both spaces) |
/kb knowledge add [--space=holy|eden] [--id=...] --title="..." [--intro="..." | --intro-file=PATH] [--key-files=...] [--key-symbols=...] [--keywords=...] |
Manually add an entry |
/kb knowledge learn [--space=eden|holy] [--file=PATH] [--base-dir=DIR] [--per-batch-chars=N] [--dry-run] [--no-survey] [--model=<provider>/<model-id>] [--plan-timeout-ms=N] |
Unified deep-study command; --model drives every learn LLM call (Phase 0 survey / Phase 1 planning / Phase 2 extraction / validation) with the given registry model instead of the current session model. CODE mode (bare, or --base-dir matching an indexed subdirectory): two-phase deep-study of indexed source files; Phase 0 writes the three project-wide survey entries; Phase 1 plans topic batches (scale-aware for large projects like postgres), Phase 2 executes each batch. Falls back to deterministic directory grouping when the LLM plan is unusable — never aborts. DOC mode (--file or a non-indexed --base-dir): deep-study Markdown / PDF / Word / PowerPoint / text documents into --space. Legacy init/bootstrap/scan aliases route here (whole-project CODE mode). |
/kb knowledge export <eden|holy|all> <path> |
Export entries to a JSON file (version 2 format with per-entry space tags) |
/kb knowledge import <path> [eden|holy|adaptive] [--overwrite] |
Import entries from JSON. adaptive routes each entry to its original space. Holy imports always prompt y/N. |
/kb knowledge housekeep <eden|holy|all> [--model=<provider>/<model-id>] |
LLM-assisted: remove broken entries, merge duplicate/similar entries (y/N); with all, resolve Eden↔Holy conflicts via a per-pair choice menu. Supreme-code never touched; knowledge indexes rebuilt on change. |
/kb knowledge empty <eden|holy|all> |
Remove ALL entries from the specified space(s). Irreversible, always prompts y/N. |
/kb knowledge del <id> |
Delete an entry (requires confirmation) |
/kb transform <id> <from> <to> |
Move an entry between Holy and Eden (requires confirmation) |
hk2 ships two interactive front-ends over the same session, slash commands, and agent-turn pipeline:
- Line REPL (default) —
hk2. The classic readline prompt (hk2(project|Eden/N Holy/N|model)>), status bar, and tool cards. Tab completes slash commands AND their data arguments (model refs, session ids, project ids — fetched live on Tab). - Inline TUI —
hk2 --tui(orHK2_UI=tui). A Claude Code-style interface: a bordered multi-line input box pinned at the bottom, streaming markdown answers and tool-call cards in the terminal's native scrollback, a live status line, slash-command completion, and arrow-key confirmation modals. Needs a TTY terminal; anything less (piped stdin,TERM=dumb) falls back to the REPL automatically.--repl/HK2_UI=replforce the classic REPL.
TUI keys:
| Key | Action |
|---|---|
| enter | Send the message (empty input is a no-op) |
\ + enter |
Continue on a new line instead of sending (slash commands submit anyway) |
| alt+enter / ctrl+j | Insert a real newline |
| ↑ / ↓ | History (single line) or move one wrapped row |
| ← / →, home / end, ctrl+a / ctrl+e | Cursor movement |
| ctrl+k / ctrl+u / ctrl+w / alt+backspace | Kill to line end / line start / word before cursor |
| Tab | Accept the highlighted slash completion |
/ + prefix |
LIVE completion menu in the REPL too (opens as you type, no Tab needed; ↑↓ select, pageup/pagedown jump 5, Tab/Enter accept, Enter on a unique exact match submits, esc closes until the text changes). Derived from the registered commands; data arguments complete too: `/model use |
| ctrl+r | Incremental history search: type a substring, ↑↓ (or repeat ctrl+r) cycle matches, enter picks one INTO the box, esc closes |
| esc / ctrl+g | While a turn runs: interrupt it. Otherwise: close the completion menu / cancel the open modal |
| ctrl+l | Clear the screen (transcript stays in the scrollback) |
| ctrl+o | Expand the most recent tool result into the transcript (the compact line shows one line + "+N lines") |
| ctrl+c | Clear the input; if empty and a turn is running, abort it; if empty and idle, press twice consecutively to exit (any other key re-arms the window) |
| ctrl+d | Exit on an empty buffer (forward-delete otherwise) |
The interface is responsive: wide terminals (≥ 88 cols) get the full welcome
card with the tips panel, 60–87 cols a compact single-column card, and
narrower ones a two-line summary — nothing ever wraps past the terminal edge.
Returning users (and screens shorter than 30 rows) always get the compact
form; /clear prints a one-line session summary instead of redrawing the
whole card. Selection in menus and modals is always marked by the ❯ glyph,
never by color alone. Modal prompts wrap their question text and show a
key-hint row (↑↓ select · enter confirm · esc cancel · y/n/e).
Thinking output is collapsed by default in the TUI (Thought for Ns after
the window closes); set HK2_HIDE_THINKING=0 to stream the reasoning live,
exactly like the REPL.
Zero-setup first run: when no model is configured, hk2 --tui
automatically imports one from Claude Code's ~/.claude/settings.json
(the env block: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN /
ANTHROPIC_API_KEY, with ANTHROPIC_DEFAULT_*_MODEL as the model list).
A notice line under the welcome card reports the import. Fill-only — an
existing default is never overwritten; set HK2_AUTOIMPORT_CLAUDE=0 to
disable.
Everything else — /model, /kb, plan confirmation menus, knowledge-save
y/N/E prompts, session resume (hk2 --tui --resume), mid-task input
queuing — is the same code as the REPL. Input history persists at
~/.hk2/history.jsonl (capped at 1000 entries).
Two safety properties of that history and config storage: inputs carrying
credentials (--token=…, Authorization headers,
password=/secret= values) are never persisted at all, and
~/.hk2/history.jsonl / models.json are kept owner-only (0600, migrated
on boot; ~/.hk2 itself is 0700).
Chat still requires an initialized project: hk2 is KB-driven, so until
/project init + /kb init have run, messages are refused with a setup
pointer — even when the first-run import already configured a model.
Type /help for the full list, or /help <command> (e.g. /help kb, /help knowledge) for detailed usage and parameters of a single command. Every family also supports <command> help (e.g. /model help set, /kb knowledge help learn). Common commands:
| Command | Description |
|---|---|
/model list |
List all providers / models |
/model add <prov> <id> [--api=...] [--base-url=...] [--api-key=...] [--reasoning] [--context-window=N] [--max-tokens=N] [--temperature=N] [--name=NAME] [--model-type=TYPE] [--model-options=JSON] |
Add a model (--model-options sets model-specific feature options as a JSON object, e.g. --model-options='{"enable_thinking":true}'; default is no options; model types with declared features validate the options — e.g. --model-type=glm-5.3 (or glm-5.3-flash) accepts {"reasoning_effort":"max"} with max (deep reasoning) the default/recommended, or high (enhanced) / low (light)) |
/model set <prov>/<id> [--name=...] [--id=NEW_ID] [--reasoning=on|off] [--context-window=N] [--max-tokens=N] [--temperature=N] [--model-options=JSON] [--api=...] [--base-url=...] [--api-key=...] |
Modify a model's persisted settings (--id renames the model id / ref; the wire model code sent to the API is unaffected; --model-options replaces the model-specific options object wholesale — pass '{}' to clear; validated against the model type's declared features, e.g. glm-5.3 / glm-5.3-flash reasoning_effort ∈ max/high/low) |
/model set-default <prov>/<id> |
Set global default (persisted) |
/model set-default current <prov>/<id> |
Set the current project's default model (overrides the global default; --clear removes the override) |
/model use <prov>/<id> |
Choose model for current session only |
/model set-phase --phase=<name> <prov>/<id> [--clear] |
Per-project model override for one agent phase (rewrite-query, request-assess, plan-review, code-review); --clear removes the override so the phase falls back to the session model |
/model add-mcpserver <prov>/<id> --type=http --name=<NAME> [--options=JSON] |
Attach an MCP server to an existing model; its tools appear to the agent as mcp__<name>__<tool>. http options: {"url":..., "headers":{"Authorization":"Bearer $APIKEY"}} ($APIKEY is substituted with the provider's --api-key at use time) |
/model del <prov>/<id> |
Delete |
/model show |
Show current default details |
/model types |
List all supported --model-type values |
/model help [sub] |
Full /model usage; /model help set drills into one subcommand |
/project init --name=... --source=... [--source-root=...] |
Register a new project |
/project list |
List all projects |
/project set current <id|name> |
Switch current project: saves the current session under the old project and starts a fresh session on the target (equivalent to /quit then hk2 --project=<target>; model/KB/status reset). Switching to the already-current project is a no-op |
/project set name <new-name> |
Rename |
/project show |
Current project details |
/project drop <id|name> |
Remove a project (KB preserved) |
/kb init [--full] [--checkpoint-interval=N] [--no-resume] [--no-checkpoint] [--skip-summary] |
Build KB for current project (resumable, auto-generated summaries) |
/kb update |
Incremental update (Index Space); auto-detects a legacy KB and upgrades it to the current layout losslessly (knowledge snapshot to backup/pre-upgrade-<ts>/ first, then includeGlobs / supreme-code / doc-graph / parser-version fixes; a parser-version change triggers a full re-index) |
/kb status |
KB statistics (per-space counts) |
/kb search <query> [--top-k=N] |
BM25 + reranking symbol search |
/kb symbol <name> |
Look up symbol by exact name |
/kb neighbors <symbol_id> |
Call-graph neighbors |
/kb knowledge list |
List Holy + Eden entries |
/kb knowledge show <id> |
Show full entry |
/kb knowledge add [...] |
Manually add an entry |
/kb knowledge learn [--dry-run] [--base-dir=PATH] [--file=PATH] [--space=eden|holy] [--per-batch-chars=N] [--no-survey] [--plan-timeout-ms=N] |
Deep-study project code (or one subdirectory / documents) → auto-generate knowledge. Full flag docs: /help knowledge |
/kb knowledge export <scope> <path> |
Export entries to JSON |
/kb knowledge import <path> [eden|holy|adaptive] [--overwrite] |
Import entries (adaptive routes by original space) |
/kb knowledge housekeep <scope> |
LLM-assisted dedup/merge + conflict resolution |
/kb knowledge empty <scope> |
Remove ALL entries from space(s) |
/kb knowledge del <id> |
Delete entry |
/kb transform <id> <from> <to> |
Move between Holy and Eden |
/kb drop |
Delete KB (confirm required) |
/session info |
Current session id, project, message count |
/session list |
Recent sessions |
/session new |
Start a new session |
/session resume <id> |
Resume a previous session |
/review code |
Manually regression-check the just-completed task (code phase; plan reserved). The reviewer's thinking stream (✎ thinking) and analysis — requirement re-analysis, per-point coverage check, correctness check, conclusion — stream live; an unparseable verdict is reported as UNKNOWN, never as "no issues found" |
/theme |
List current tool-card frame colors vs built-in defaults |
/theme set <key> <color> |
Customize tool-card border/title colors, persisted (key: bash, kb_*, *, or an exact tool name like read; color: #rrggbb, ansi:0-255, or a built-in token accent/muted/dim/success/error/warning/border/bashMode/pythonMode; resolution priority: exact tool name > group key > * wildcard > built-in default) |
/theme reset [key] |
Drop one custom color, or the whole custom theme with no arg |
/theme preview |
Print sample tool cards for the three built-in groups with current colors |
/theme title-follow [on|off] |
Toggle the top-border title following the frame color instead of the fixed muted hue |
/clear |
Clear conversation context |
/compact |
Summarize earlier messages |
/help /quit /exit |
Help / exit |
The agent can call these tools mid-turn (OpenAI/Anthropic native tool-calling):
| Tool | Description |
|---|---|
read |
Read file contents (line-numbered, offset/limit). Code files known to the KB get an ## Outline (from KB) section prepended and a tag field returned for stale-anchor protection. |
write |
Create or overwrite a file |
edit |
Precise string replacement (supports multiple disjoint edits). Optional tag rejects stale-anchor edits. |
bash |
Execute shell commands (sandboxed to workspace) |
find |
Glob-pattern file search |
grep |
Regex content search |
ast_grep |
Structural code search with $$$IDENT / $IDENT / $_ metavariables (ast-grep style). When the pattern is a single exact identifier the KB knows, prepends a kb-first hint toward kb_symbol. |
ast_edit |
Structural rewrite across files. Returns a unified-diff preview + proposalId; never writes itself. Optional tag validates target files at preview time. |
resolve |
Apply or discard a previously-previewed ast_edit proposal. Re-validates tags at apply time, rolls back on any failure. |
plan |
The triage assistant's interface for surfacing a user-confirmed execution plan. The LLM calls it when it decides a task is complex enough to warrant a strategy decision (multiple distinct phases, a design choice the user should confirm, or several affected subsystems); simple tasks skip straight to execution. It returns a one-line summary plus 2–5 ordered steps, each with 2–4 candidate strategies (one marked recommended), and surfaces the plan for per-step strategy selection. |
plan_step |
Mark a step of a currently confirmed plan as done and advance the live progress panel. Call it exactly once after finishing each confirmed plan step (the one returned by plan); step is 1-based (omit to advance the current step). Pure progress-UX signal - no-op when no plan is active, and the panel clears automatically after the last step. Do not call it before plan returns a confirmed plan. |
kb_search |
BM25 symbol search (with LLM query rewrite by default) |
kb_symbol |
Look up symbol by exact name |
kb_outline |
File outline from the KB index — name / kind / lines / signature per symbol. Cheaper than read for "what's in this file?" questions. Returns a tag for downstream edit safety. |
kb_neighbors |
Call-graph 1-hop neighbors (legacy) |
kb_callchain |
Bounded DFS over the call graph (forward / backward / both) |
kb_class |
Class / interface / struct lookup with members, super-classes, implementations |
kb_refs |
Find callers, importers, derived classes for a symbol |
kb_implements |
Find every class that implements an interface or extends a base class |
kb_knowledge |
Look up a knowledge entry by id (Holy + Eden) |
kb_search_knowledge |
Search knowledge entries by natural-language query |
kb_save_knowledge |
Save a new knowledge entry to Holy or Eden |
mcp__<server>__<tool> |
Tools from MCP servers attached to the active model via /model add-mcpserver (e.g. mcp__web-reader__webReader). Each agent turn attaches them after the built-ins; unreachable servers are skipped with a warning |
Every code-discovery path favours the KB index over fresh parsing:
kb_outline,kb_symbol,kb_search, and the graph tools read directly from the index — no filesystem hit, no reparse.readon a code file prepends the KB-sourced outline so the agent sees structure before content.bash grep/find/catand directreadcalls without a prior KB tool get a one-time[kb-first policy hint]prepend; after the agent uses any KB tool the hint stops, signalling that subsequent bash/read fallbacks are intentional.ast_grepwith a single exact identifier emits the same hint towardkb_symbol.
| Token | Meaning |
|---|---|
$$$IDENT |
Multi-wildcard capture — matches any text (multi-line, non-greedy). IDENT is captured into meta.IDENT for substitution. |
$IDENT |
Single identifier capture — matches [A-Za-z_][A-Za-z0-9_]*. |
$_ |
Anonymous single-token wildcard (no capture). |
| other | Literal text, regex-escaped. |
Examples:
ast_grep("console.log($$$)")— any console.log callast_grep("function $NAME($$$)", path="src")— captures function namesast_edit({ops:[{pat:"console.log($$$ARGS)", out:"logger.info($$$ARGS)"}], paths:["src"]})— codemod every console.log → logger.info, args preserved (named captures round-trip; anonymous$$$does not)
read and kb_outline results include a tag (the first 8 hex chars of the file's content hash). Echo it into subsequent edit or ast_edit calls and the tool rejects the change if the file was modified since the tag was minted:
read({path:"src/foo.js"}) → {tag:"a1b2c3d4", ...}
edit({path:"src/foo.js", old_string:..., new_string:..., tag:"a1b2c3d4"})
→ ok on match, error: "stale tag: file changed since read..." on mismatch
The following capabilities are intentionally not implemented yet, because they don't have a clean kb-first story and require multi-thousand-line integrations:
- LSP integration — would require spawning language servers, JSON-RPC capability negotiation, and diagnostics streaming. The KB symbol index already covers most "what does the IDE know?" queries; LSP would only add value for live diagnostics and rename refactors across unindexed files. Defer until that gap becomes blocking.
- DAP debugging — would require spawning debug adapters (gdb, lldb-dap, debugpy, dlv), breakpoint/step/variable protocols. Same scope as LSP. Defer until there's a concrete debugging workflow need.
- Full hashline grammar (
SWAP.BLK,INS.PRE/POST/HEAD/TAIL,MV,REM) — v1 ships only thetagsafety mechanism. The full line-anchored grammar is a future addition once the preview/accept flow is proven. - AST-aware ast_grep matching — v1 uses a regex approximation (translates metavariables to capture groups). Full ast-grep pattern parity (true AST-boundary matching) is iterative.
A status bar is pinned to the bottom of the terminal (TTY mode only):
streaming │ postgres|kb|glm-5.2 │ ↑1.4k ↓120 0.1%/1.0M │ 4.2s
↑1.4k— latest LLM call's input tokens↓120— latest LLM call's output tokens0.1%— current context usage (latest input / context window)1.0M— context window size
Updates live during streaming, tool calls, and phase transitions.
When a task is complex enough, the agent calls plan to surface a user-confirmed
execution plan. A live progress panel is then pinned above the status bar showing
the plan's steps - which are done, which is in progress, and which are pending:
▣ Plan: sync README docs with code
✓ 1. Add missing plan_step tool
▶ 2. Document the progress panel
3. Fix tree-sitter package count
4. Commit and push
After finishing each confirmed step, the agent calls plan_step once to advance
the panel. Marking the last step done clears the panel automatically - no
separate finish call is needed. Simple tasks that skip plan never show a
panel. See the plan and plan_step entries in Agent tools.
When HK2_ENABLE_PLANREVIEW=1 (default off), after the user confirms a plan,
an LLM re-analyzes the requirement, checks the plan for coverage (every needed
part delivered), ordering, feasibility, risks, and unstated assumptions, and
surfaces any issues one-by-one for confirmation before execution begins. The
reviewer's thinking stream (reasoning_content) renders live as ✎ thinking
(dim italic, capped at 9 lines by default — set HK2_HIDE_THINKING=0 for the
full stream), followed by its analysis, which also streams live; an
unparseable verdict is reported as
UNKNOWN, never as "no issues found"; see the env-var table. Reviews always
run with reasoning enabled and no fixed timeout — the reviewer waits for the
LLM to finish (the user can still abort), so a deep review is never cut off
mid-reply.
When HK2_ENABLE_CODEREVIEW=1 (default off), after the entire plan finishes
executing, hk2 runs a Code Review step that checks the completed result — the
working-tree diff, the changed files, and the agent's final summary — for
correctness, completeness, and quality. The reviewer's thinking stream
(reasoning_content) renders live as ✎ thinking (dim italic, capped at 9
lines by default — set HK2_HIDE_THINKING=0 for the full stream), followed
by its analysis (plan re-analysis, per-point coverage check, correctness
check, conclusion), which streams
live while it reviews; any issues it finds are then listed one-by-one with
detail and a suggestion. A reply whose JSON verdict cannot be parsed is
reported as UNKNOWN, never as "no issues found". The review model is
configurable via /model set-phase --phase=code-review <ref> (same mechanism
as plan-review); when unset it uses the session model. See the env-var
table. Like plan review, it always runs with reasoning enabled and no fixed
timeout — the reviewer waits for the LLM to finish (the user can still
abort).
While a task runs, a one-line input box (» add instruction ▏) is pinned just
above the plan panel / status bar, and the real terminal cursor is docked
inside the box — a blinking caret sits exactly where your typing will land
(and follows mid-text edits). What you type is echoed there — the
streaming agent output above can never disturb your in-progress text. You can
keep typing while the agent is working. Plain text entered mid-task is
queued (echoed as ✓ queued #N · delivered after the current action) and
injected into the RUNNING conversation at the agent loop's round boundary —
after the current action (the LLM call plus all of its tool calls) completes,
before the next LLM call starts. The model receives them as in-task guidance
("fold into the work in progress, do not restart from scratch"), so the
current action is never disturbed. Slash commands keep the legacy behavior
(they run after the turn ends, since they may switch model / KB / project
state the in-flight turn still depends on); plan-confirmation menus are
unaffected. If the task finishes before a queued instruction can be delivered
mid-run, it is handed to a fresh turn right after — nothing you type is lost.
~/.hk2/
├── models.json # Multi-provider model registry
├── projects.json # Project registry + current pointer
├── setting.json # Global filesystem-permission baseline (optional)
├── settings/
│ └── <project-id>/setting.json # Managed per-project permission overrides
├── kb/
│ └── <projectId>/ # Per-project KB
│ ├── meta.json # KB metadata
│ ├── holy/ # Holy Space — stable knowledge entries
│ │ └── <entry-id>.json
│ ├── eden/ # Eden Space — frequently-updated knowledge
│ │ └── <entry-id>.json
│ ├── graph/ # Knowledge graph (Index Space)
│ │ ├── nodes.json
│ │ ├── edges.calls.json
│ │ ├── edges.imports.json
│ │ ├── edges.inherits.json
│ │ ├── edges.contains.json
│ │ ├── by_kind.json
│ │ ├── by_qual.json
│ │ └── meta.json
│ ├── files.json # Index Space — file registry
│ ├── inverted.json # Index Space — BM25 inverted index
│ ├── callgraph.json # Index Space — legacy callgraph (derived from graph)
│ ├── symbols.0000.json # Index Space — sharded symbol table
│ ├── stats.json # Index Space — build statistics
│ ├── checkpoint.json # Resumable build state (transient)
│ └── summaries/ # Per-symbol summaries (on-demand)
├── sessions/
│ └── <projectId>/
│ └── <sessionId>.jsonl # session transcript (JSONL)
└── logs/
hk2 restricts every path-touching agent tool (read/write/edit/find/grep/ast_grep/ast_edit/resolve, plus best-effort scanning of bash commands) with a Unix-style r / w / x permission model:
- Default deny outside the project. Paths inside the current project root(s) (
cwd+HK2_PROJECT_SOURCE) are fully operable —rwxfor both files and directories (the inside-project default is deliberately permissive: your own project is trusted). Any path outside those roots is absolutely denied unless a rule below grants it. - Permission modes mirror the filesystem:
r= read file / list dir,w= create/modify/delete,x= execute (bash commands referencing the path). - A rule on a directory covers everything inside it (like dir permission bits); a rule on a file covers just that file.
Two layers, merged (see setting.example.json at the repo root). Both live under HK2_HOME — deliberately outside the agent-writable project tree, so the model can never rewrite the rules that bound its own sandbox (a setting.json inside the project root is NOT loaded; it only produces a load-time migration hint):
~/.hk2/setting.json— global baseline~/.hk2/settings/<project-id>/setting.json— per-project override; wins over global on the same target. The project id is taken fromHK2_PROJECT_ID(set automatically in interactive mode) or resolved fromprojects.jsonby source path; an unregistered project simply has no project layer.
{
"permissions": [
{ "path": "/tmp/scratch", "allow": "rw" },
{ "path": "~/Documents/notes", "allow": "r" },
{ "path": "secrets", "deny": "rwx" },
{ "path": "node_modules", "deny": "w" }
]
}Rule resolution: longest matching prefix wins; on equal prefixes the project layer beats the global layer, and deny beats allow within a layer. An allow rule listing only r means read-only — it does not fall back to the permissive inside-project default, so explicit rules fully determine the mode set for their target.
Relative paths resolve against the project root. ~ expands to the user home. A trailing /** is accepted and equivalent to the bare directory (rules are always recursive).
Migration note: before this layout existed, the per-project file was
<project-root>/setting.json. That location is ignored now — move your rules to~/.hk2/settings/<project-id>/setting.json(or merge them into the global file). The ignored-legacy-file warning printed at load time names both paths.
The permission configuration is agent read-only. Even when an allow rule covers HK2_HOME, write access to ~/.hk2/setting.json and anything under ~/.hk2/settings/ is hard-denied for the agent — only the human user edits the sandbox definition.
bash enforcement is best-effort: the command is scanned for explicit absolute / ../-style paths, slash-bearing relative operands (resolved against the command's effective base directory, tracked through cd sequences), and executed targets (interpreter operands like bash script.sh / node x.js, or a directly invoked absolute binary). Executed targets require x; data operands require r (read-only commands) or w (mutating commands like rm/mv/redirects). A shell is Turing-complete, so this is a guardrail against accidental damage rather than a hard sandbox; the dedicated file tools above are the hardened path.
Recursive tools (find/grep/ast_grep/ast_edit directory expansion) re-check r on every directory they descend into and every file they emit — a deny rule on a subdirectory holds even when the walk started at an ancestor (project root). Writes staged by ast_edit are re-verified per file (lexical + symlink-resolved) at resolve time.
The project KB is treated as equivalent to the project's files. KB surfaces that mirror real file content follow the same r permission as a read(): kb_search snippets/slices, kb_symbol, kb_outline and kb_class doc strings, the per-turn auto-injected context (symbol snippets, docs/ texts, structured doc tables), and slice loading all suppress content whose source file is denied by setting.json — while pure metadata (names, kinds, signatures, line ranges, knowledge entries) stays visible so navigation keeps working.
Symlink indirection is covered: a path that is lexically inside the project but resolves (via symlink) to an outside location is denied — the real path is re-checked with the same rules (and an allow rule written against either spelling matches both).
Invalid config (e.g. "allow": "q", a missing allow/deny field, or an entry carrying both) is reported as a load-time warning naming the dropped entry — only the offending rule is dropped, the system degrades to deny-by-default rather than crashing, and every other rule keeps working. An empty permissions: [] array is a valid "no rules" config and produces no warning.
Each model has an id and a name. The id is the accounting key used in
provider/id refs (e.g. local/glm-4.7) and may carry a trailing bracketed
context-window hint such as [1m]. The name is the model code actually
sent in the API request body (the wire model field) — set it to the
exact string the provider expects (e.g. glm-4.7, never GLM 4.7). Keeping
the hint on id and the clean code on name avoids "model code does not
exist" errors (e.g. BigModel's [modelCode: not found]) on gateways that
reject glm-4.7[1m].
{
"providers": {
"local": {
"api": "openai",
"baseUrl": "http://10.16.6.162:18000",
"apiKey": "sk-glm4-local",
"models": [
{
"id": "glm-4.7",
"name": "glm-4.7",
"contextWindow": 131072,
"maxTokens": 32768,
"temperature": 0.2,
"reasoning": true
}
]
},
"anthropic": {
"api": "anthropic",
"apiKey": "...",
"models": [
{ "id": "claude-opus-4-7", "name": "claude-opus-4-7", "contextWindow": 200000, "maxTokens": 32000, "reasoning": true }
]
}
},
"default": "local/glm-4.7"
}{
"current": "8ce5c38d-214c-4e0d-8ed1-30045dd3c99d",
"projects": {
"8ce5c38d-214c-4e0d-8ed1-30045dd3c99d": {
"id": "8ce5c38d-214c-4e0d-8ed1-30045dd3c99d",
"name": "myapp",
"sourcePath": "/path/to/repo",
"sourceRoot": "src",
"includeGlobs": ["**/*.js", "**/*.ts", "**/*.py", "..."],
"excludeGlobs": ["**/node_modules/**", "..."],
"extraRoots": [],
"kbBuiltAt": "2026-07-24T16:41:44.248Z",
"createdAt": "2026-07-24T16:41:43.000Z"
}
}
}| Variable | Description | Default |
|---|---|---|
HK2_HOME |
Override ~/.hk2 location |
~/.hk2 |
HK2_AUTOIMPORT_CLAUDE |
When 0, disables the first-run model import from Claude Code's ~/.claude/settings.json (TUI only) |
on |
HK2_LLM_RETRY_UNKNOWN_POST |
LLM requests with an UNKNOWN outcome (mid-flight transport failures — reset / read- or write-phase timeout AFTER the request was sent — and HTTP 500/502/503/504, which a reverse proxy can return after the upstream already ran the inference) are retried BY DEFAULT: for interactive CLI use a dead turn on a transient nginx 502 is worse than the rare duplicate request behind the retry. Set 0 to opt out (duplicate requests / duplicate billing concerns; providers expose no idempotency key, so classification is the only guard). Connection-establishment failures (refused / DNS / undici connect-timeout / connect-phase ETIMEDOUT, surfaced as (CODE) or (CODE/connect) in the error message) and HTTP 408/429 (refused before execution) are outcome-safe and ALWAYS retried. All retries bounded by HK2_LLMAPI_NUMOFRETRIES. |
1 |
HK2_UI |
Interactive front-end: tui selects the Claude Code-style inline TUI, repl (default) the classic line REPL. The --tui / --repl flags take precedence. |
repl |
HK2_KB_DIR |
Override KB root | $HK2_HOME/kb |
HK2_KB_NAME |
KB name for legacy --mode commands |
Current project id, or default |
HK2_PROJECT_SOURCE |
Project source root for tool sandbox (set automatically in interactive mode) | - |
HK2_PROJECT_ID |
Project id used to locate the managed per-project permission file $HK2_HOME/settings/<id>/setting.json (set automatically in interactive mode; falls back to a projects.json source-path lookup) |
- |
HK2_PREFIX |
Install prefix used by install.sh for the hk2 symlink |
/usr/local |
HK2_INSTALL_DIR |
Self-contained copy location used by install.sh (defaults to HK2_HOME, i.e. ~/.hk2) |
~/.hk2 |
HK2_ENABLE_QUERYREWRITE |
When 1, hk2 uses an LLM call to rewrite each user query to English function names + keywords before BM25 retrieval (both at turn start and on each kb_search tool call). |
1 |
HK2_ENABLE_REQUEST_ASSESS |
When 1 (and HK2_ENABLE_QUERYREWRITE=1), hk2 first asks the LLM whether a user request is clear. If not, it surfaces the unclear aspects plus candidate interpretations as a numbered menu (with a free-text "something else" option) and feeds the chosen clarification back into the query rewrite. The assessment model is configurable via /model set-phase --phase=request-assess <ref> (same mechanism as rewrite-query); when unset it uses the session model. Active only in interactive TTY mode; one bounded round. Best-effort: any failure falls through to the normal rewrite. |
1 |
HK2_ENABLE_PHASEMODEL_FALLBACK |
What to do when a phase model configured via /model set-phase (e.g. rewrite-query, request-assess) is unreachable (connection refused / timeout / HTTP error). 1: print a warning and re-run the phase on the current session (main) model so the phase still completes. 0: print a warning and skip the phase entirely (the rewrite falls back to the raw query; the assessment round is skipped). Never silently succeeds: a dead phase model always produces a warning, and phaseModelFallback is recorded in the session transcript for auditing. Applies to rewrite-query and request-assess only — the review phases (plan-review, code-review<
A630
/code>) always skip on an unreachable model (warning printed, never a fallback), since silently substituting a model would change what reviewed the plan/code; |
1 |
HK2_ENABLE_PLANREVIEW |
When 1, after the user confirms a plan, hk2 asks an LLM to review the finalized plan before execution begins. The reviewer re-analyzes the requirement as a numbered checklist, then checks per-point coverage (which step covers each requirement, complete/partial/missing), ordering and contradictions, feasibility of each chosen strategy, and unstated risks/assumptions. The analysis streams live; issues are surfaced one-by-one for confirmation (accept the reviewer's suggestion / dismiss / type your own) and the confirmed resolutions are appended to the plan returned to the agent. An unparseable JSON verdict is reported as UNKNOWN, never as "no issues found". The review model is configurable via /model set-phase --phase=plan-review <ref> (same mechanism as rewrite-query); when unset it uses the session model. Active only in interactive TTY mode. Best-effort: any failure returns the already-confirmed plan unchanged. |
0 |
HK2_ENABLE_CODEREVIEW |
When 1, after the entire plan finishes executing, hk2 runs a Code Review step on the completed result (working-tree diff, changed files, and the agent's final summary) for correctness, completeness, and quality. The reviewer's analysis (plan re-analysis, per-point coverage check, correctness check, conclusion) streams live; issues are then listed one-by-one with detail and a suggestion. An unparseable JSON verdict is reported as UNKNOWN, never as "no issues found". The review model is configurable via /model set-phase --phase=code-review <ref> (same mechanism as plan-review); when unset it uses the session model. Active only in interactive TTY mode. Best-effort: any failure is reported and the turn ends normally. |
0 |
HK2_ENABLE_AUTOUPDATEKB |
When 1, hk2 silently runs an incremental /kb update (Index Space) at end of any turn where the agent fell back to bash to search source files. |
0 |
HK2_ENABLE_AUTO_LEARN |
When 1, hk2 silently asks the model to extract a reusable knowledge entry from the just-finished conversation and saves it to Eden Space. Holy Space ALWAYS prompts y/N regardless of this flag. | 0 |
HK2_KB_LEARN_COOLDOWN_MIN |
When a positive number of minutes, the end-of-turn [kb learn] fallback is skipped while a knowledge capture for this session's task was handled within that window (an agent kb_save_knowledge save/decline, an answered end-of-turn proposal, or the extraction model's skip). The anchor is restored across --resume from the transcript. When the agent already saved knowledge via kb_save_knowledge this turn, [kb learn] is ALWAYS skipped regardless of this variable. |
0 (OFF) |
HK2_KB_LEARN_VALIDATE |
When 1, before an end-of-turn [kb learn] entry is written, hk2 validates it against existing KB entries (id/title/keyword pre-filter + one semantic LLM check): essentially-identical content is skipped (no duplicate learning), related entries are UPDATED in place via a merged intro, and direct conflicts are resolved — Holy conflicts ALWAYS defer to the user, Eden conflicts follow the validator's winner with the reason printed. Creating a new entry beside related ones prints the reason it was not an update. Validation is best-effort: any failure falls through as a normal new entry. |
1 |
HK2_ENABLE_AUTOCOMPACT |
When 1, hk2 auto-compacts the prior conversation at the start of a turn once the measured context length reaches HK2_AUTOCOMPACT_PCTUSED% of the model's context window. Compaction keeps the last 4 user/assistant turns verbatim and LLM-summarizes earlier turns (including their tool results) into a single system message, falling back to naive truncation if the LLM fails. Runs only at the turn boundary, never mid-turn. |
0 |
HK2_AUTOCOMPACT_PCTUSED |
Integer 1-100 context-usage threshold percentage. Auto-compaction only triggers when the measured context length ≥ model context window × HK2_AUTOCOMPACT_PCTUSED / 100. |
90 |
HK2_KB_CHECKPOINT_INTERVAL |
Save /kb init checkpoint every N files |
100 |
HK2_PLAN_TIMEOUT_MS |
/kb knowledge learn Phase 1 planning call timeout in ms. Slow providers (reasoning models on large file maps) can exceed the default 300s. Per-run override: --plan-timeout-ms=N. |
300000 |
HK2_LLMAPI_TIMEOUT_MS |
Default timeout (ms) for every LLM API request (chat completions / messages, streaming and non-streaming). Resolution precedence: per-call opts.timeoutMs > per-model config.timeout (always stamped at resolve time from this same variable) > this env default. Explicit 0 means NO timeout (no abort timer armed — the plan-review / code-review phases rely on this). Unset / invalid / negative values fall back to the default. |
3600000 (3600s) |
HK2_LLMAPI_TIMEOUT_MS_SIMPLE |
Timeout (ms) for the lightweight single-shot LLM phases: query rewrite (rewriting query) and request-clarity assessment (assessing request), both turn-start passes and the kb_search tool's inline rewrite. Resolved via llmApiTimeoutMsSimple() (lib/llm/timeout.js) inside rewriteQuery / assessRequest; a per-call opts.timeoutMs still beats it. Explicit 0 means no timeout. Unset / invalid / negative fall back to the default. Previously hardcoded at 15000ms (15s). |
300000 (300s) |
HK2_WELCOME |
TUI welcome card tier: full shows the logo card with the tips panel whenever the terminal width allows (>= 88 cols; narrower terminals still degrade to the single-column / two-line layouts), compact skips the logo card but very narrow terminals still get the two-line summary, auto (default) full on first run and compact for returning users / screens shorter than 30 rows. |
auto |
HK2_LLMAPI_NUMOFRETRIES |
Max consecutive retries when an LLM API call fails transiently (network errors like fetch failed, HTTP 408/429/5xx, request timeouts), so a momentary network hiccup or provider blip no longer aborts the whole agent task. A failed call is retried with exponential backoff (1s → 30s cap) up to N times after the first failure (N+1 total attempts); a {type:'retry'} event is emitted between attempts so consumers reset partial output. Deterministic client errors (other 4xx) and user aborts (ESC) are NOT retried. Explicit 0 disables retries (exactly one attempt); unset / invalid / negative fall back to the default. |
10 |
HK2_INDEX_PARALLEL |
Parallelism of the KB index parse pool (/kb init / /kb update). 0 or unset = auto (host CPU count); a positive integer pins the width. |
0 |
HK2_DEBUG |
Print error stacks | - |
HK2_NO_COLOR |
When 1, disable ANSI colors (also honors the standard NO_COLOR env var). |
- |
HK2_ASCII |
When 1, force ASCII fallbacks for box-drawing / spinner / icons instead of UTF-8 glyphs (useful on non-UTF-8 terminals). | - |
HK2_HIDE_THINKING |
When unset or 1 (default), the ✎ thinking reasoning window renders at most 9 content lines, then a dim notice reports how many lines were hidden (in the TUI, thinking is collapsed to one Thought for Ns line while it runs). When 0, the full reasoning stream is rendered (previous behavior; in the TUI, live). |
1 |
ANTHROPIC_API_KEY |
Auto-creates an anthropic provider on first init |
- |
OPENAI_API_KEY |
Auto-creates an openai provider on first init |
- |
# Register a project from CLI (equivalent to /project init in REPL)
hk2 --mode=project-init --name=myapp --source=/path/to/repo --source-root=src
# Build KB for the current project
hk2 --mode=build-kb
# Incrementally update the KB
hk2 --mode=update-kb
# Enter the REPL with a specific project pre-selected
hk2 --project=myapp # by name
hk2 --project-id=8ce5c38d-214c-4e0d-8ed1-30045dd3c99d # by UUID
# List all registered projects and exit (current marked with '*')
hk2 --project-list
# Legacy REPL (command-style, no agent loop)
hk2 --run-mode=serveThe KB indexer prefers native tree-sitter grammars for AST-accurate symbol
extraction across 14 packages (15 grammars, since tree-sitter-typescript
exports both typescript and tsx):
- C, C++, C#
- JavaScript, TypeScript, JSX/TSX
- Python, Go, Rust
- Java, Kotlin, Scala
- Ruby, PHP
- Bash / Zsh
If a grammar or the tree-sitter native binding is unavailable, hk2 transparently
falls back to regex-based parsers (lower coverage, same Symbol[] shape). C/C++
and lex/yacc (.y/.l) sources additionally have dedicated regex parsers used
in the fallback path.
hk2/
├── bin/
│ └── hk2 # Single entry point (#!/usr/bin/env node)
├── install.sh # Installer (copies tree, symlinks bin, runs npm install)
├── src/
│ ├── cli.js # Argument parsing + dispatch (defaults to interactive)
│ ├── commands/
│ │ ├── interactive.js # Default interactive REPL (agent loop + status bar)
│ │ ├── build_kb.js # --mode=build-kb
│ │ ├── update_kb.js # --mode=update-kb
│ │ ├── search.js # Legacy serve-mode code search helper
│ │ ├── explain.js # Legacy serve-mode explanation helper
│ │ └── serve.js # --run-mode=serve (legacy REPL)
│ └── slash/
│ ├── index.js # Slash command dispatcher (quote-aware tokenizer)
│ ├── model.js # /model
│ ├── project.js # /project
│ ├── kb.js # /kb (incl. knowledge learn/export/import/transform)
│ └── session.js # /session
├── lib/
│ ├── config/
│ │ └── home.js # $HOME/.hk2 config layer
│ ├── agent/
│ │ ├── loop.js # Agent turn loop (stuck detection, tool cache)
│ │ ├── tools.js # Tool registry + KbFirstGuard (incl. graph tools)
│ │ ├── system_prompt.js # System prompt builder + KB policy
│ │ ├── graph.js # Per-request knowledge graph builder
│ │ ├── statusbar.js # persistent bottom status bar
│ │ └── transcript.js # JSONL session transcript
│ ├── parser/
│ │ ├── ast.js # AST dispatcher (tree-sitter → regex fallback)
│ │ ├── ts_parser.js # Tree-sitter multi-language parser
│ │ ├── doc_parser.js # Document parser (md/json/yaml/html/sgml/pdf/docx/doc/pptx/ppt)
│ │ ├── c_parser.js # Legacy C parser (fallback)
│ │ ├── ylex_parser.js # Legacy Y/L parser (fallback)
│ │ └── generic_parser.js # Legacy regex parser for other languages (fallback)
│ ├── graph/
│ │ ├── builder.js # Build nodes + edges from Symbol[]
│ │ └── traverse.js # Pure BFS / call-chain helpers
│ ├── index/
│ │ ├── indexer.js # Walk → parse → BM25 + callgraph + graph + Eden docs
│ │ ├── walker.js # Glob walker (include/exclude + .gitignore)
│ │ ├── gitignore.js # .gitignore loader
│ │ ├── checkpoint.js # Resumable build checkpoint
│ │ ├── summarize.js # LLM-authored Eden summaries
│ │ ├── bm25.js # BM25 index
│ │ ├── callgraph.js # Legacy callgraph (derived from graph)
│ │ ├── text_tokenizer.js # Tokenizer for BM25
│ │ └── registry.js # KB registration + PARSER_VERSION
│ ├── retrieval/ # KB retrieval + runtime cache (code_search, kb_runtime)
│ ├── llm/ # LLM client (OpenAI / Anthropic, tool-call + usage)
│ ├── store/ # KB storage (holy/eden/index/graph paths)
│ └── util/
└── package.json