dsh-knowcode

🛠 CLI Usage (Microsoft tgrep-style)

dsh-knowcode ships with the knowcode executable CLI for terminal usage and CI/CD pipelines.

Not sure you have the knowcode command yet? It is not a separate download — see Installation & Quickstart above for the four ways to obtain it. Quick check: knowcode --version.

Throughout this section, knowcode … can always be replaced by ./bin/knowcode.js … when running from a clone.

Which command do I need?

serve indexes the workspace by itself — index is optional. There is no need to index before serving.

On startup, and before it announces readiness, serve reconciles the graph with the filesystem:

Workspace state	What serve does
Never indexed	Walks the workspace and indexes everything — Index stale: N added, 0 changed, 0 deleted. Re-indexing...
Index already current	Index is up-to-date (N files checked) — no file is read, thanks to a modification-time fast path
Files added, changed or deleted	Re-indexes only those files
--force-index	Re-parses everything, ignoring the stale check

Both routes build the same graph, including the TESTS_FOR and DOCUMENTS links, so serving a fresh workspace and indexing one produce identical results.

You want to…	Use
Just use it	serve — or let the plugin's autoStartDaemon start one for you
Index once in CI without leaving a process behind	index (it starts a daemon, indexes, and stops it)
Pre-warm so the first tool call is not spent waiting	index then serve — serve reuses the result
Rebuild a graph you suspect is stale or wrong	serve --force-index

⚠️ The stale check compares file content hashes, so it cannot tell that an existing graph was built by an older parser. After upgrading, use --force-index (or delete /falkordb.rdb) — otherwise the previous graph is trusted.

1. One-shot Indexing (knowcode index)

Index a codebase and its documentation into the embedded FalkorDB database. Not required if you are going to serve — that indexes on its own:

### Configuration options

| Option | Default | Description |
|---|---|---|
| `daemonPort` | `48123` | Preferred port for the workspace daemon. If it is taken, the daemon binds the next free port and records it in `/daemon.json`, so several workspaces can each run their own daemon. |
| `dataDir` | `.knowcode` | Directory holding the embedded database and `daemon.json`. |
| `falkordbUrl` | *(empty)* | Connect to an external FalkorDB (e.g. `redis://127.0.0.1:6379`) instead of the embedded engine. |
| `blastRadiusMaxDepth` | `3` | Default traversal depth for impact analysis (clamped to 1–10). |
| `maxFileSize` | `1048576` | Largest file read and indexed, in bytes. Enforced from the file's size **before** it is read, in both the indexer and the file watcher. Set it with `knowcode serve . --max-file-size ` when running the CLI by hand. |
| `autoStartDaemon` | `true` | Start a daemon automatically when a tool runs in a workspace that has none, instead of replying with a "run `knowcode serve .`" notice. The daemon is spawned detached from this package's own CLI and its output is appended to `/serve.log`. Concurrent calls share one start attempt; the first call may wait a few hundred milliseconds. |
| `idleTimeoutMinutes` | `0` | Stop a daemon after this many minutes without activity. `0` disables it. Any client contact — a tool call, a watcher event — resets the budget. Restarting later is cheap: the database persists and the stale check skips unchanged files. Set it per run with `knowcode serve . --idle-timeout `. |
| `stopDaemonOnExit` | `true` | Stop the daemons **this process** spawned when the harness exits. Detached daemons outlive a tool call, so without this, quitting DSH would leave one running per project — each holding an embedded FalkorDB process, an HTTP server, a file watcher and a database file. Cleanup runs from the plugin's disposal effect, which DSH triggers on `SIGINT` (Ctrl+C) and `SIGTERM`; `SIGKILL` bypasses disposal and is the one case that still orphans a daemon. Daemons you started yourself with `knowcode serve .` are never touched. |