Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

codegraph upgrade replaces the entire global AGENTS.md with just the CODEGRAPH block, wiping user content outside the markers

Open
  • Is something wrong?
#2,506 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
56/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
nodejs, typescript
Domain
tooling

Research direction

The issue identifies codegraph upgrade and the OpenCode global AGENTS.md target, but names no implementation files or tests. Start by tracing the upgrade refresh path added in #1238/#1239 and find where it writes the file. Done when an existing marked block is replaced while surrounding content is preserved, and a file without markers is not truncated.

Written by the indexing model from the issue text.

Description

Problem

codegraph upgrade rewrites the global ~/.config/opencode/AGENTS.md (OpenCode target) with only the <!-- CODEGRAPH_START --> … <!-- CODEGRAPH_END --> block, replacing the entire file and wiping all user content outside the markers.

Our global AGENTS.md is a maintained ~47-line guidance file (toolset inventory, model config, tool-preference policy, runtime notes, conventions, commit policy) with the CodeGraph block appended at the end. After codegraph upgrade it became:

<!-- CODEGRAPH_START -->
## CodeGraph
… (10-line block only)
<!-- CODEGRAPH_END -->

Everything outside the markers was destroyed — no backup, no merge.

Reproduction

  1. Have a global ~/.config/opencode/AGENTS.md with user content plus an existing <!-- CODEGRAPH_START -->…<!-- CODEGRAPH_END --> block (as written by a prior codegraph install).
  2. Run codegraph upgrade.
  3. cat ~/.config/opencode/AGENTS.md → only the CodeGraph block remains.

Observed on CodeGraph 1.6.1 (reproduces with the current release line), Ubuntu linux-x64, installed via npm (@colbymchenry/codegraph).

Expected behavior

The refresh (added in #1238/#1239 so that upgrade updates installer-written instructions) should inject/replace only within its markers:

  • If <!-- CODEGRAPH_START --> / <!-- CODEGRAPH_END --> exist → replace just that span, preserving surrounding content.
  • If markers are absent → append the block (or prepend, matching install behavior) instead of truncating the file.
  • Ideally take a backup before modifying (e.g. AGENTS.md.bak-<timestamp>), consistent with safe-config-change expectations raised in #486.

Workaround (our side)

We added a self-heal to our toolset: verify-toolset.sh detects the clobber (canonical sections missing) and scripts/repair-agents-md.sh restores the canonical content while re-appending any existing CodeGraph block (pfz-smg/opencode-setup#103, PR #145). A marker-scoped replace upstream would make that workaround unnecessary.

Related

  • #1238 — upgrade did not refresh installer-written files (the fix for this appears to be what introduced the whole-file replace).
  • #800 — size/globality of the injected block (distinct issue).
  • #486 — no backup when modifying agent config files (closed, but the backup suggestion is still relevant here).
Dominant language
C
Stars
73.2k
Forks
4.7k
Avg merge
2h 16m
Merged PRs (30d)
423

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from colbymchenry/codegraph

All issues in colbymchenry/codegraph

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.