Improve CLI workflows for coding agents

[joesobo]

What changes in practice

• The Core CLI is JSON-first for workspace setup, live/source-aware Search, task-personalized File maps, exact File or Symbol overviews, relationship queries, safe settings changes, actionable Indexing limits, and structured Plugin state.
• Exact targeted queries use the complete cached Relationship Graph unless --node-type, --edge-type, or --filter explicitly narrows the request. JavaScript and TypeScript reexports remain structural, so calls and paths can resolve through barrels to implementation Symbols.
• codegraphy watch is an optional foreground process for long terminal sessions. It batches edits, keeps cached Symbols and Relationships current, coordinates writers through a separate SQLite transaction, emits bounded JSON Lines events, and drains pending work on shutdown.
• The Agent Skill explains capabilities, freshness, bounds, and machine contracts while leaving navigation strategy to the agent.
• VS Code remains explicitly user-controlled: the Extension never starts the CLI watcher and changes cached source facts only after Index Workspace or Re-index Workspace.

The experimental public batch command was removed. Other benchmark candidates that did not improve successful agent work were reverted instead of retained as alternate paths.

Contract hardening

• Persisted and one-off Filters, Node Type projections, and Edge Type projections now constrain graph Nodes, cached Symbols, source evidence, and Relationships consistently.
• Exact File Path stops after a direct route. Target Query includes contains by default and removes it only when an explicit Edge Type projection excludes it.
• Missing indexed source marks cached Symbols stale; unchanged indexed binary or oversized files remain fresh while their source text stays excluded.
• Workspace settings accept supported versions 1–4, reject unsupported versions, preserve unknown valid fields, include respectGitignore in freshness, and report Indexing impact directionally when Filters broaden discovery.
• Watch preserves buffered startup events and shuts down safely. Full and incremental updates recheck discovery and source inputs under writer ownership before persistence, so older analyses cannot replace newer facts. Incremental corruption recovery rebuilds the complete Graph Cache under that same ownership rather than replaying a partial patch.
• Oversized Search source is never loaded as one string: extraction remains capped at 1 MiB while a streamed hash verifies cached-fact freshness.
• Task Map chooses each File's bounded declarations by task relevance before deterministic alphabetical fallback.
• Workspace Graph Query input is a discriminated union derived from the single internal request/report contract, so report-invalid selectors cannot bypass saved Graph Scope. One CLI registry owns public parser, runner, and help registration.

Measured results

All agent comparisons used fresh isolated workspaces and unchanged hidden validation. Indexing cost was measured separately.

Comparison	Correctness	Model tokens	Calls	Elapsed	Output
Shipped skill vs raw, two clean-install regression tasks	6/6 vs 6/6	43.2% lower pooled median	—	task-dependent	—
Graph-focused CLI vs raw, final hard-task pairs	equal	43.5% lower median	18.8% fewer	12.7% faster	35.3% lower
Task Map vs previous CLI on the adopted relationship task	3/3 vs 3/3	34.7% lower mean	34.4% fewer	30.5% faster	38.1% lower

These are small controlled samples, not a universal performance claim. The watcher reliability probe covered rapid edits, create/rename/delete/settings changes, 30 concurrent readers, and two simultaneous watchers with 0.53–0.61 s update latency. The agent watcher screen did not query after editing, so this PR makes no watcher-specific retrieval-benefit claim.

Merge cleanup

• Removed 3,427 lines of obsolete Extension watcher work that conflicted with explicit user-controlled Indexing.
• Removed the separate decision archive and its contributor-policy language, keeping current behavior and constraints in the closest product, package, and Agent Skill references.
• Consolidated the Core release notes into one readable changeset.
• Grouped CLI parsers and new Graph Query features into stable feature-first folders; split the oversized workspace-query integration suite by behavior; removed brittle documentation-order assertions and experiment-specific test naming.
• Reduced Core functions above the CRAP threshold from 74 to 57; newly organized CLI and Graph Query seams are stable under the repository organization tool.

Validation

• Forced uncached sequential workspace unit tests: 16/16 tasks.
• Workspace build, lint, and typecheck: 43/43 tasks.
• Core quality run: 347 files / 1,489 tests, with 57 functions above CRAP 8 (down from 74).
• Release contracts: 42/42 tests.
• Changesets status, Markdown relative links, acceptance-spec guard, and diff checks pass.
• Mutation testing was intentionally skipped for this pass. The full Playwright suite was not run locally; exact-head GitHub Actions run 30494760239 passed 36/36 jobs, including every Playwright group and installed-VSIX target.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
codegraphy	Skipped		Jul 29, 2026 10:04pm

[changeset-bot]

🦋 Changeset detected

Latest commit: b7db786

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@codegraphy-dev/core	Major
@codegraphy-dev/plugin-api	Minor
@codegraphy-dev/extension	Patch
@codegraphy-dev/tldraw	Patch
@codegraphy-dev/extension-plugin-api	Patch
@codegraphy-dev/plugin-godot	Patch
@codegraphy-dev/plugin-markdown	Patch
@codegraphy-dev/plugin-svelte	Patch
@codegraphy-dev/plugin-typescript	Patch
@codegraphy-dev/plugin-unity	Patch
@codegraphy-dev/plugin-vue	Patch
@codegraphy-dev/plugin-particles	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR