seanb4tseanb4t/codegraph-go/.claude/CLAUDE.md

codegraph-go

CLAUDE.md0 starsChanged 25 days agoMITView on GitHub

codegraph-go gives coding agents (Claude Code, Codex, Cursor, Gemini and others) a pre-indexed code knowledge graph: fast symbol, call-path and impact queries from one static Go binary with a CLI, an MCP server, a local graph UI and auto-sync. There is no bundled runtime to install or manage. The constraints that bind every change are in openspec/config.yaml under context. The short version: one static binary per platform, CGo only for tree-sitter, signed and reproducible releases, macOS and Linux (Windows only…

In this repository14 other files it gives its agents.
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill
- codegraphSkill
- gh-issue-draftSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Issue first: Every change starts from a GitHub issue.
line 11
Very specific:
Run mise trust && mise install once.
line 34
Distinctive:
Tests cover only code this repo owns: Never test third-party behavior (git, GitHub, changie, GoReleaser, cobra and so on).
line 38

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

Project

codegraph-go gives coding agents (Claude Code, Codex, Cursor, Gemini and others) a pre-indexed code knowledge graph: fast symbol, call-path and impact queries from one static Go binary with a CLI, an MCP server, a local graph UI and auto-sync. There is no bundled runtime to install or manage.

The constraints that bind every change are in openspec/config.yaml under context. The short version: one static binary per platform, CGo only for tree-sitter, signed and reproducible releases, macOS and Linux (Windows only through WSL2), and CLI and MCP output shapes are a compatibility surface.

Workflow

Planning runs on OpenSpec. The backlog lives in GitHub issues.

Issue first. Every change starts from a GitHub issue. A feature or enhancement needs approved-feature or approved-enhancement before a PR. spec-needed means a merged OpenSpec proposal comes before code.
Behavior changes go through an OpenSpec change: /opsx:propose, then /opsx:apply, then /opsx:archive. The line after the title of proposal.md is Issue: #<n>. Specs live in openspec/specs/, active changes in openspec/changes/.
Fixes and chores that change no specified behavior go straight to a PR.
Pull requests. A proposal-only PR says Refs #<n>. The implementation PR says Closes #<n> and carries the code, the changelog fragment and the openspec archive result.
Generated files. openspec update owns the /opsx:* commands (.claude/commands/opsx/) and the openspec-* skills (.claude/skills/, .agents/skills/). Customize OpenSpec through openspec/config.yaml, never by editing those files.
History. The planning record from before OpenSpec is archived at the planning-archive-v0.15.0 tag; read a file with git show planning-archive-v0.15.0:.planning/<path>. Requirement and decision IDs in comments (SYNC-02, D-06R) resolve there, and docs/2026-10-17-gsd-era-decisions.md holds the old decision log.

Technology stack

Area	Choice
Language	Go (version in `go.mod`), one static binary per platform
Parsing	`tree-sitter/go-tree-sitter` plus per-language grammar modules, the one CGo dependency (`PARSER-DECISION.md`)
Storage	`cockroachdb/pebble/v2`
MCP	`modelcontextprotocol/go-sdk`, stdio transport
CLI and terminal UI	`spf13/cobra`; `charm.land` bubbletea and lipgloss v2
File watching	`fsnotify/fsnotify`
Graph UI	SvelteKit 2 and Svelte 5 in `web/` (pnpm), embedded by `web/embed.go`, talking Connect RPC (protobuf via buf)
Release	GoReleaser v2, cosign keyless signing, SLSA provenance, SBOMs, Apple notarization, Homebrew tap, changie for the changelog and versions
Tooling	`Taskfile.yml`; the build, lint and release tools, Go included, are pinned in `mise.toml`, with checksums for prebuilt downloads in `mise.lock`. `mise install` installs them locally; `.github/actions/setup-tools` installs them in CI

Working here

Run mise trust && mise install once. In a shell without mise activate, run every target as mise exec -- task <target>: the Taskfile refuses to run when a pinned tool on PATH is not the mise install. task test runs the suite, task lint the linters, and task --list shows the rest.
Changelog fragments. A PR that changes cmd/** or internal/** with a user-visible effect adds task changie -- new --interactive=false -k <Kind> -b "<one sentence>" (kinds: Breaking, Features, Fixes, Performance, Dependencies). Otherwise the PR body carries . The required fragment-required check enforces this. Keep --interactive=false: without it changie prompts for the optional PR field, and an agent with no TTY hangs.
Embedded sources. .claude/hooks/{hooks.json,session-nudge.sh,pretooluse-nudge.sh}, .claude/skills/codegraph/SKILL.md and .codex/hooks/* are //go:embed sources that ship in the binary. Edit them as product code.
Required checks are pinned by job name in the protect-main ruleset. Renaming a CI job blocks every PR until the ruleset changes too.
Tests cover only code this repo owns. Never test third-party behavior (git, GitHub, changie, GoReleaser, cobra and so on).
LICENSE stays verbatim MIT text. Upstream attribution lives only in NOTICE.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free