08 Agentic Mode

Agentic Mode

In standard mode, the LLM reviews only the diff and context provided in the prompt. In agentic mode, the LLM can actively explore your codebase — reading files, searching for patterns, listing directories, and running custom commands — to verify its findings before reporting them.

---

Enabling Agentic Mode

nitpik review --diff-base main --agent

Or enable it by default in .nitpik.toml:

[review.agentic]
enabled = true

When to Use Agentic Mode

Use agentic mode when:

• Your changes interact with code in other files (e.g., interface changes, API contracts)
• You want the reviewer to verify assumptions before reporting (e.g., "is this error actually handled elsewhere?")
• Your custom profiles define tools (test runners, linters, deployment checks)

Use standard mode when:

• You want faster, cheaper reviews (no extra LLM turns for tool calls)
• The changes are self-contained within the diff
• You're optimizing for API cost

Agentic reviews use more LLM tokens (each tool call is an additional turn) but produce fewer false positives because the LLM can verify its reasoning.

Built-in Tools

Every agentic review has access to six built-in tools:

read_file

Reads the contents of a file from the repository. The LLM uses this to examine functions, types, or modules referenced in the diff.

read_files

Reads several files in a single call (up to 10 files, 64 KB total). The LLM uses this to batch related reads — e.g. fetching a module and its tests at once — and save round trips.

search_text

Searches for a text pattern across the codebase. The LLM uses this to find usages of a changed function, check whether an issue is handled elsewhere, or trace data flow.

glob

Finds files by glob pattern (e.g. **/*.rs, src/**/handler*.rs). Gitignore-aware, capped at 200 results. The LLM uses this to discover files when it doesn't know an exact path.

list_directory

Lists the contents of a directory. The LLM uses this to understand module structure and navigate the codebase.

git_log

Shows a file's recent commit history (followed across renames, newest first, up to 30 commits). The LLM uses this to judge a change against its past — catching when a diff reverts or re-introduces something a prior commit deliberately fixed, a regression the diff alone can't reveal. The diff shows what changed; git_log shows why the code is the way it is.

submit_findings

Terminal tool the LLM calls to submit its final findings as structured JSON. Always available in agentic mode — it's how findings exit the agent loop.

Custom Tools

Profiles can define additional CLI tools. See Custom Profiles — Custom Agentic Tools for the full format.

nitpik review --diff-base main --profile ./test-aware-reviewer.md --agent

Controlling Resource Usage

Max Turns

Limits how many LLM round-trips (tool call → response → next call) are allowed per file×agent task:

nitpik review --diff-base main --agent --max-turns 5

Defaults to 10. Lower values reduce cost and latency. If the LLM reaches the limit, it returns whatever findings it has at that point.

Max Tool Calls

Limits the total number of tool invocations per file×agent task:

nitpik review --diff-base main --agent --max-tool-calls 5

Defaults to 10. This caps the total number of read_file, search_text, etc. calls within a single task, preventing runaway exploration.

Config File

[review.agentic]
enabled = true
max_turns = 10
max_tool_calls = 10

Tool-Call Audit Log

Every tool invocation is recorded and displayed at the end of the review (unless --quiet is set):

  ▸ 5 tool calls
    → read_file src/main.rs (1.2KB, 3ms)
    → search_text "fn process" (3 results, 45ms)
    → run_tests --filter auth (exit 0, 2.1s)

This shows what the LLM explored, helping you understand its reasoning and verify it didn't go off-track.

Agentic Context

In agentic mode, the LLM receives additional context beyond the standard diff and file content — enough to orient itself in your repository and use tools effectively. This includes awareness of the repo structure and other files in the review.

If your custom profile includes an agentic_instructions field in its frontmatter, those instructions are injected in agentic mode to give the profile tailored guidance for tool usage. They're omitted in standard reviews so the LLM isn't confused by references to tools it can't use.

Related Pages

• Custom Profiles — define custom tools and agentic instructions
• Reviewer Profiles — choosing profiles
• How Reviews Work — the full review pipeline
• Configuration — agentic config options