Improve agent-oriented Codegraph outputs by lzehrung · Pull Request #133 · lzehrung/codegraph

lzehrung · 2026-06-18T19:47:47Z

Summary

make orient pretty/MCP output handle-free and action-focused
let packet retrieval use file-path targets while preserving stable handle targets
update docs, skill guidance, CLI/MCP schemas, and regression coverage

Verification

npm run check
npx vitest run tests/agent-orient.test.ts tests/agent-packet.test.ts tests/cli-regressions.test.ts tests/mcp-server.test.ts tests/cli-command-modules.test.ts tests/package-metadata.test.ts
repeated reviewer passes until no findings

kilo-code-bot · 2026-06-18T19:53:15Z

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Resolved in This Update (2 suggestions)

src/agent/orient.ts line 454 — Fixed: removed redundant Review prefix from review focus label in buildReviewFocus, which resolves the duplicate Review Review prefix that labelForFollowUp was producing.
src/mcp/tools.ts — Fixed: updated packet_get description to include symbol name and SQL object name, matching the documented target shapes.

Files Reviewed (4 files)

src/agent/orient.ts — Removed Review prefix from review focus label
src/mcp/tools.ts — Updated packet_get tool description
tests/agent-orient.test.ts — Added assertions for review focus label formatting
tests/mcp-server.test.ts — Added assertions for packet_get description text

Previous Review Summaries (4 snapshots, latest commit eeb5dfe)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit `eeb5dfe`)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (7 files)

codegraph-skill/codegraph/SKILL.md - Updated packet and explain target syntax examples
docs/cli.md - Expanded packet get target description to include symbol names and SQL object names
docs/library-api.md - Updated getCodegraphPacket target description
docs/mcp.md - Updated packet_get target description
src/cli/help.ts - Updated packet get usage and target list
src/cli/options.ts - Updated packet get usage string in schema
tests/cli-command-modules.test.ts - Updated tests to match new help text

Previous review (commit `684cec4`)

Status: No Issues Found | Recommendation: Merge

All 6 previously reported issues have been resolved in the incremental changes:

Pretty orient output duplicate follow-up commands are now deduplicated (src/cli/orient.ts).
Unnecessary conditional spread for buildOptions removed (src/cli/orient.ts).
Git worktree commands are now only recommended inside git repos (src/agent/orient.ts).
file: handles are now documented in packet get help text (src/cli/help.ts).
Review orientation now correctly reserves a focus target slot, keeping file focus targets within budget (src/agent/orient.ts).
Previously-exported agent orientation types (AgentOrientationFocus, AgentModuleSummary, AgentPacketHandle) are now re-exported from the package index (src/index.ts, src/agent.ts).

Files Reviewed (4 files)

src/agent.ts - Re-exports deprecated AgentModuleSummary and AgentPacketHandle types
src/agent/orient.ts - Adds reviewFocusSlots to keep review orientation within the focus target budget; exports deprecated types for backwards compatibility
src/index.ts - Re-exports AgentOrientationFocus and deprecated agent orientation types
tests/agent-orient.test.ts - Adds test for review orientation budget constraints

Previous review (commit `2bdb448`)

Status: No Issues Found | Recommendation: Merge

All 4 previously reported issues have been resolved in the incremental changes:

Duplicate follow-up commands in pretty orient output are now deduplicated (src/cli/orient.ts).
Unnecessary conditional spread for buildOptions removed (src/cli/orient.ts).
Git worktree commands are now only recommended inside git repos (src/agent/orient.ts).
file: handles are now documented in packet get help text (src/cli/help.ts).

Files Reviewed (5 files)

src/agent/orient.ts - Added isGitRepo check; conditionally includes worktree review/impact commands
src/cli/orient.ts - Deduplicates recommended next commands from focus follow-ups; simplifies buildOptions passing
src/cli/help.ts - Documents file: handles in packet help text
tests/agent-orient.test.ts - Adds tests for git repo conditional behavior
tests/cli-regressions.test.ts - Adds assertion for deduplicated packet get output

Previous review (commit `b23550a`)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (20 files)

README.md
codegraph-skill/codegraph/SKILL.md
docs/agent-workflows.md
docs/cli.md
docs/library-api.md
docs/mcp.md
src/agent.ts
src/agent/orient.ts
src/agent/packet.ts
src/cli/help.ts
src/cli/options.ts
src/cli/orient.ts
src/cli/packet.ts
src/index.ts
src/mcp/server.ts
src/mcp/tools.ts
tests/agent-orient.test.ts
tests/agent-packet.test.ts
tests/cli-command-modules.test.ts
tests/cli-regressions.test.ts
tests/mcp-server.test.ts
tests/package-metadata.test.ts

_{Reviewed by kimi-k2.6-20260420 · 195,419 tokens}

Copilot

Pull request overview

This PR updates Codegraph’s agent-oriented “orient” and “packet get” surfaces to be more action-focused by switching from handle-first follow-ups to file-path (and other “target”) follow-ups across the CLI, MCP server, and library API, along with schema bumps and refreshed documentation/tests.

Changes:

Orient output: replaces handles/hotspot module lists with ranked focus targets that include “why” + follow-up commands; schema version bumped to 2.
Packet retrieval: switches from { handle } to { target } (CLI/MCP/library), accepting project file paths while preserving stable handle targets; schema version bumped to 2.
Updates docs, skill guidance, CLI/MCP schemas, and regression tests to match the new output shapes and usage.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/package-metadata.test.ts	Updates doc/example contract checks for orient’s preferred `--pretty` usage.
tests/mcp-server.test.ts	Migrates MCP tests from `handle` to `target` and validates schema v2.
tests/cli-regressions.test.ts	Updates orient/packet regression expectations for `focus`, targets, and schema v2.
tests/cli-command-modules.test.ts	Refreshes help/usage expectations for `packet get <file\|handle>`.
tests/agent-packet.test.ts	Updates agent packet API tests to use `target` (including bare symbols + review targets).
tests/agent-orient.test.ts	Validates new orient `focus` ranking, follow-ups, and schema v2 behavior.
src/mcp/tools.ts	Updates MCP tool schema/description for `packet_get` to accept `target`.
src/mcp/server.ts	Renames MCP handler input from `handle` → `target` and updates validation schema.
src/index.ts	Updates public exports/docs for new orient/packet semantics and types.
src/cli/packet.ts	Switches CLI packet retrieval positional from `handle` → `target`.
src/cli/orient.ts	Updates orient output formatting to display `focus` + follow-ups; silences build logging.
src/cli/options.ts	Updates CLI usage string for packet get to `<file\|handle>`.
src/cli/help.ts	Updates help text to describe `target`-based packet retrieval and new orient output.
src/agent/packet.ts	Implements `target`-based packet retrieval and bumps packet schema to v2.
src/agent/orient.ts	Implements `focus` targets + new recommended-next commands; bumps orient schema to v2.
src/agent.ts	Updates agent API re-exports to match new orient/packet type surface.
README.md	Updates getting-started flow and examples to prefer `orient --pretty` and path targets.
docs/mcp.md	Updates MCP docs to describe `packet_get` targets.
docs/library-api.md	Updates library API examples from handles to focus targets/file paths.
docs/cli.md	Updates CLI docs for new orient/packet output + recommended usage.
docs/agent-workflows.md	Updates workflow guidance to use `--pretty` and file targets.
codegraph-skill/codegraph/SKILL.md	Updates skill guidance/examples for the new target-based workflow.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  lines.push("", "Recommended next");
  for (const next of response.recommendedNext) {
    lines.push(`- ${next.command}`);
  }


    budget: parseAgentOrientBudget(context.getOpt("--budget")),
    ...(healthMode !== undefined ? { health: healthMode } : {}),
-    ...(context.buildOptions ? { buildOptions: context.buildOptions } : {}),
+    ...(buildOptions ? { buildOptions } : {}),
  });


+  commands.push({
+    label: "Map current worktree impact",
+    command: "codegraph impact --base HEAD --head WORKTREE --pretty",
+  });


+Targets:
+  Accepts project file paths plus symbol:, chunk:, sql:, and graph: handles from search or explain output; review packets use quoted 'review:base=<encoded-ref>;head=<encoded-ref>' targets.



Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

+  const packets = buildFilePackets(
+    scopedFiles,
+    modules.map((module) => module.file),
+    limits.maxFocusTargets,
+  );


+/** Agent first-turn orientation packets with file-path follow-up targets. */
 export { orientCodegraph } from "./agent/orient.js";
 export type {
-  AgentModuleSummary,
  AgentOrientBudget,
  AgentOrientHealthMode,
  AgentOrientRequest,
  AgentOrientResponse,
+  AgentOrientationFocus,
  AgentPacketCommand,
-  AgentPacketHandle,
  AgentTreeEntry,
 } from "./agent/orient.js";


Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

-Handles:
-  Accepts file:, symbol:, chunk:, sql:, graph:, and review: handles. CLI orient returns file handles; review handles are produced by library orientation calls that include a review range.
+Targets:
+  Accepts project file paths plus file:, symbol:, chunk:, sql:, and graph: handles from search or explain output; review packets use quoted 'review:base=<encoded-ref>;head=<encoded-ref>' targets.


+- Use `orient --json` when follow-up tools need exact focus reasons, limits, and omitted counts. Orient suppresses index rebuild warnings so stdout stays parseable.
 - Small orientation budgets default to `--health skip`. Medium and large default to `--health summary`, which counts cycles and unresolved imports while omitting duplicate health; use `--health full` when exhaustive duplicate counts matter.
- Use `packet get` with file, symbol, chunk, SQL, graph, or review handles to retrieve bounded evidence plus follow-up commands.
+- Use `packet get` with file paths, symbol handles, chunk handles, SQL handles, graph handles, or review handles to retrieve bounded evidence plus follow-up commands.


Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

+function labelForFollowUp(focus: AgentOrientationFocus, followUp: string): string {
+  const label = focus.file ?? focus.label ?? "focus target";
+  if (followUp.startsWith("codegraph packet get ")) return `Get packet for ${label}`;
+  if (followUp.startsWith("codegraph explain ")) return `Explain ${label}`;
+  if (followUp.startsWith("codegraph review ")) return `Review ${label}`;
+  if (followUp.startsWith("codegraph impact ")) return `Map impact for ${label}`;
+  return label;
+}


Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

lzehrung added 2 commits June 18, 2026 14:57

Improve agent orientation outputs

05e9fe2

Harden packet target contracts

b23550a

lzehrung requested a review from Copilot June 18, 2026 20:12

Copilot started reviewing on behalf of lzehrung June 18, 2026 20:13 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Address orient output review feedback

2bdb448

lzehrung requested a review from Copilot June 18, 2026 22:48

Copilot started reviewing on behalf of lzehrung June 18, 2026 22:48 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Address orientation focus budget feedback

684cec4

lzehrung requested a review from Copilot June 19, 2026 00:44

Copilot started reviewing on behalf of lzehrung June 19, 2026 00:45 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Clarify packet target guidance

eeb5dfe

lzehrung requested a review from Copilot June 19, 2026 01:07

Copilot started reviewing on behalf of lzehrung June 19, 2026 01:07 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Refine packet target metadata

b9c3268

lzehrung requested a review from Copilot June 19, 2026 03:43

Copilot started reviewing on behalf of lzehrung June 19, 2026 03:43 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

lzehrung merged commit 8a46ef5 into main Jun 19, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve agent-oriented Codegraph outputs#133

Improve agent-oriented Codegraph outputs#133
lzehrung merged 6 commits into
mainfrom
agent-orient-output-cleanup

lzehrung commented Jun 18, 2026

Uh oh!

kilo-code-bot Bot commented Jun 18, 2026 •

edited

Loading

Previous review (commit `eeb5dfe`)

Previous review (commit `684cec4`)

Previous review (commit `2bdb448`)

Previous review (commit `b23550a`)

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Targets:
		Accepts project file paths plus symbol:, chunk:, sql:, and graph: handles from search or explain output; review packets use quoted 'review:base=<encoded-ref>;head=<encoded-ref>' targets.

Conversation

lzehrung commented Jun 18, 2026

Summary

Verification

Uh oh!

kilo-code-bot Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Summary

Previous review (commit eeb5dfe)

Previous review (commit 684cec4)

Previous review (commit 2bdb448)

Previous review (commit b23550a)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kilo-code-bot Bot commented Jun 18, 2026 •

edited

Loading

Previous review (commit `eeb5dfe`)

Previous review (commit `684cec4`)

Previous review (commit `2bdb448`)

Previous review (commit `b23550a`)