knosh kdocs¶

Add and update KDoc comments in Kotlin source files using an AI agent.

Synopsis¶

knosh kdocs --agentId <id> [options] FILES...

Description¶

kdocs sends each listed Kotlin source file to the agent with instructions to add missing KDoc comments, update incomplete or outdated ones, and document parameters and return types on public functions. When the agent determines a file needs no changes, it is left untouched.

After all files are processed, kdocs prints a report listing which files were modified, which were unchanged, and which could not be processed.

Files are processed sequentially by default. Pass --parallel to process them concurrently, which is faster for large batches but interleaves log output.

Options¶

--agentId <id> (required)

The agent to use. Must match an agent filename (without .md) in the agents directory.

FILES... (required)

One or more Kotlin source file paths to process. Shell glob expansion is supported, so patterns like src/**/*.kt work as expected.

--parallel

Process files concurrently. By default, files are processed one at a time.

Execution¶

--max-iterations <n>

Maximum number of LLM API calls the agent may make per file. Default: 50.

--temperature <value>

Sampling temperature in [0.0, 1.0]. Overrides the agent's configured value. The default when this option is omitted is 0.2, which is lower than most agent configs — low enough to suppress preamble while still varying phrasing.

Retries¶

--max-retries <n>

Number of times to retry a file after the agent returns an invalid response. Default: 0. When a retry is triggered, the agent is told why the previous response was rejected.

--retry-delay-ms <ms>

Milliseconds to wait before each retry. Default: 0.

--exponential-backoff

Double the retry delay on each attempt.

Logging¶

--log-dir <path>

Directory to write log files. Each run appends to a YYYY-MM-DD.log file.

--log-level <level>

Minimum log severity: TRACE, DEBUG, INFO, WARN, ERROR. Default: WARN.

--log-format <format>

Log line format: compact (default), default, json, pretty.

--log-full-prompts

Log the full prompt and response instead of replacing long text with a character count.

--log-full-tool-calls

Log tool call arguments and results in full.

Output¶

kdocs prints a Markdown-formatted report after processing all files:

## Modified (2)

- `/path/to/Foo.kt`
- `/path/to/Bar.kt`

## Not Modified (1)

- `/path/to/Baz.kt`

## Could Not Process (0)

Files listed under Could Not Process include the reason — for example, File does not exist or No response from agent.

Examples¶

Process a single file:

knosh kdocs --agentId my-agent src/main/kotlin/Foo.kt

Process all Kotlin files in a directory tree:

knosh kdocs --agentId my-agent src/**/*.kt

Process a batch concurrently with retries:

knosh kdocs --agentId my-agent --parallel --max-retries 2 --retry-delay-ms 1000 src/**/*.kt

Log the full prompts and responses for debugging:

knosh kdocs --agentId my-agent --log-dir logs --log-level DEBUG --log-full-prompts Foo.kt