Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ codegraph serve --mcp --path /path/to/project # optional: pin to a specific pro
```

Auto-register it into your agent's config (Claude Code, Cursor, Codex CLI,
opencode, Hermes, Gemini CLI, Antigravity, Kiro, Trae, Qoder, Zed, VS Code,
Copilot CLI, JetBrains):
opencode, Hermes, Gemini CLI, Antigravity, Kiro, Trae, Qoder, Zed, Zuno,
VS Code, Copilot CLI, JetBrains):

```bash
codegraph install --yes # detects installed agents and wires them up
Expand Down Expand Up @@ -204,8 +204,8 @@ directory or `rootUri`/`workspaceFolders`/`roots`. When it can't resolve one,
See [`docs/mcp.md`](docs/mcp.md#project-resolution) for the full three-case breakdown.

Supported agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent,
Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, VS Code (GitHub Copilot),
GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot).
Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, Zuno, VS Code
(GitHub Copilot), GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot).

```bash
codegraph install --yes # auto-detect installed agents
Expand Down Expand Up @@ -238,9 +238,11 @@ codegraph skill uninstall --target=claude --yes # remove from one agent
codegraph skill status # show state for all detected agents
```

Ten of the eleven install targets have a skill directory (Claude Code, Cursor,
Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, Trae,
Qoder; `zed` is MCP-only and has no skill directory).
Eleven of the fifteen install targets have a skill directory (Claude Code,
Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro,
Trae, Qoder, and Zuno). Zuno reuses the standard `~/.agents/skills` /
`.agents/skills` path, so selecting both Codex and Zuno is idempotent. Zed and
the three GitHub Copilot surfaces are MCP-only and have no skill directory.
Default location is `--global`; pass `--local` to write into the project tree.
Hermes supports global only.

Expand All @@ -254,6 +256,13 @@ added/removed line counts. `--diff` adds a deterministic unified diff;
`--dry-run` prints the same preview without changing files. `skill status` also
shows version provenance, for example `outdated (0.40.1 -> 0.47.0)`.

For agents whose installer owns a marker-fenced instructions block, `skill
update` also refreshes that block while preserving all user text outside
`<!-- CODEGRAPH_START -->` / `<!-- CODEGRAPH_END -->`. This includes Zuno's
global `$XDG_CONFIG_HOME/zuno/AGENTS.md` (normally
`~/.config/zuno/AGENTS.md`) and project-root `AGENTS.md`. `--dry-run` previews
the instructions change without writing it.

Full reference including per-agent skill paths: [`docs/cli.md`](docs/cli.md).

---
Expand All @@ -267,7 +276,8 @@ stays live depends on whether the IDE expands `${workspaceFolder}`:
- **Cursor / Trae** — global config uses `--path ${workspaceFolder}`, so one entry auto-follows every project window. Live watch enabled.
- **Kiro / Qoder** — global entry without `--path`; tools work read-only off the existing index. Run `codegraph init --target=kiro` (or `--target=qoder`) inside each project for live watch.
- **Zed** — global `settings.json` entry without `--path`. Run `codegraph init --target=zed` inside each project to write a `.zed/settings.json` with an absolute `--path` — the only way to give Zed a per-project path. The installer also writes `//`-commented HTTP and SSH alternatives for remote-development use.
- **Other agents** (Claude Code, Codex CLI, opencode, Hermes, Gemini CLI, Antigravity) — standard `mcpServers` entry; live watch where the daemon can reach the project.
- **Zuno** — global config is `$XDG_CONFIG_HOME/zuno/zuno.json[c]` (normally `~/.config/zuno/zuno.json[c]`); project config is `.zuno/zuno.json[c]`. The installer writes `mcp.codegraph` and migrates the older `mcp.codegraph-mcp-server` key without disturbing siblings or JSONC comments.
- **Other agents** (Claude Code, Codex CLI, opencode, Hermes, Gemini CLI, Antigravity) — their native MCP entry shape; live watch where the daemon can reach the project.

> **Zed Remote (SSH).** Zed runs MCP `context_servers` on the local client, not on
> the remote host. If codegraph tools return empty in a remote SSH session, use the
Expand Down
138 changes: 120 additions & 18 deletions crates/codegraph-cli/src/installer/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -381,8 +381,10 @@ pub fn run_skill_install(args: SkillArgs) -> Result<()> {
}

/// `codegraph skill update`: preview the version transition + line counts, then
/// refresh safe/outdated content. `--diff` adds a unified diff, `--dry-run`
/// suppresses writes, and `--force` overwrites locally modified content.
/// refresh safe/outdated skill content and each target's marker-managed
/// instructions block. `--diff` adds a unified skill diff, `--dry-run`
/// suppresses every write, and `--force` overwrites locally modified skill
/// content. User text outside the managed instructions markers is untouched.
pub fn run_skill_update(args: SkillArgs) -> Result<()> {
let ctx = context_from_env()?;
let (location, targets) = resolve_skill_targets(&ctx, &args)?;
Expand All @@ -391,7 +393,8 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> {
return Ok(());
}

let mut changed_names: Vec<&str> = Vec::new();
let mut skill_changed_names: Vec<&str> = Vec::new();
let mut instructions_changed_names: Vec<&str> = Vec::new();
for target in &targets {
let Some(skill_dir) = target.resolved_skill_dir(&ctx, location) else {
println!(
Expand All @@ -412,9 +415,22 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> {
print!("{diff}");
}

let instructions_preview = target.preview_managed_instructions(&ctx, location);
if let Some(file) = &instructions_preview {
println!(
"{}",
managed_instructions_preview_line(target.display_name(), &ctx, file, args.dry_run)
);
}

if args.dry_run {
if preview.decision == skill::SkillUpdateDecision::Update {
changed_names.push(target.display_name());
skill_changed_names.push(target.display_name());
}
if instructions_preview.as_ref().is_some_and(|file| {
matches!(file.action, FileAction::Created | FileAction::Updated)
}) {
instructions_changed_names.push(target.display_name());
}
continue;
}
Expand All @@ -425,33 +441,119 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> {
.iter()
.any(|file| matches!(file.action, FileAction::Created | FileAction::Updated))
{
changed_names.push(target.display_name());
skill_changed_names.push(target.display_name());
}
report_write_result(target.display_name(), &ctx, &result);

if let Some(file) = target.refresh_managed_instructions(&ctx, location) {
if matches!(file.action, FileAction::Created | FileAction::Updated) {
instructions_changed_names.push(target.display_name());
}
report_write_result(
target.display_name(),
&ctx,
&WriteResult {
files: vec![file],
notes: Vec::new(),
},
);
}
}

if args.dry_run {
if changed_names.is_empty() {
println!("\nDry run: no skill files would change.");
} else {
if skill_changed_names.is_empty() && instructions_changed_names.is_empty() {
println!("\nDry run: no CodeGraph skill assets would change.");
}
if !skill_changed_names.is_empty() {
println!(
"\nDry run: would update the CodeGraph skill for {} agent{}: {}.",
changed_names.len(),
if changed_names.len() > 1 { "s" } else { "" },
changed_names.join(", ")
skill_changed_names.len(),
if skill_changed_names.len() > 1 {
"s"
} else {
""
},
skill_changed_names.join(", ")
);
}
if !instructions_changed_names.is_empty() {
println!(
"\nDry run: would refresh managed CodeGraph instructions for {} agent{}: {}.",
instructions_changed_names.len(),
if instructions_changed_names.len() > 1 {
"s"
} else {
""
},
instructions_changed_names.join(", ")
);
}
} else {
if !skill_changed_names.is_empty() {
println!(
"\nUpdated the CodeGraph skill for {} agent{}: {}.",
skill_changed_names.len(),
if skill_changed_names.len() > 1 {
"s"
} else {
""
},
skill_changed_names.join(", ")
);
}
if !instructions_changed_names.is_empty() {
println!(
"\nRefreshed managed CodeGraph instructions for {} agent{}: {}.",
instructions_changed_names.len(),
if instructions_changed_names.len() > 1 {
"s"
} else {
""
},
instructions_changed_names.join(", ")
);
}
} else if !changed_names.is_empty() {
println!(
"\nUpdated the CodeGraph skill for {} agent{}: {}.",
changed_names.len(),
if changed_names.len() > 1 { "s" } else { "" },
changed_names.join(", ")
);
}
Ok(())
}

fn managed_instructions_preview_line(
display_name: &str,
ctx: &InstallContext,
file: &types::FileWrite,
dry_run: bool,
) -> String {
let path = tildify(ctx, &file.path);
match (file.action, dry_run) {
(FileAction::Created, true) => {
format!("{display_name}: would create managed instructions {path}")
}
(FileAction::Updated, true) => {
format!("{display_name}: would refresh managed instructions {path}")
}
(FileAction::Unchanged, true) => {
format!("{display_name}: managed instructions up to date {path}")
}
(FileAction::Created, false) => {
format!("{display_name}: creating managed instructions {path}")
}
(FileAction::Updated, false) => {
format!("{display_name}: refreshing managed instructions {path}")
}
(FileAction::Unchanged, false) => {
format!("{display_name}: managed instructions up to date {path}")
}
(action, _) => format!(
"{display_name}: {} managed instructions {path}",
action.verb()
),
}
}

// Keep the summary logic separate for skills and instructions: a target may
// have an up-to-date or locally modified SKILL.md while its marker-managed
// AGENTS/CLAUDE/GEMINI block still needs a safe refresh.

/// `codegraph skill uninstall`. Removes the installed skill from each resolved
/// target; an absent skill is reported as "not configured" (success exit).
pub fn run_skill_uninstall(args: SkillArgs) -> Result<()> {
Expand Down
7 changes: 5 additions & 2 deletions crates/codegraph-cli/src/installer/registry.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
//! Order is load-bearing: it is the order in `--target=all`, in detection, and
//! in `--print-config`'s help listing. Matches `ALL_TARGETS` (registry.ts:20):
//! claude, cursor, codex, opencode, hermes, gemini, antigravity, kiro, trae,
//! qoder, zed, plus the three Copilot surfaces appended by this port: vscode,
//! copilot-cli, jetbrains.
//! qoder, zed, zuno, plus the three Copilot surfaces appended by this port:
//! vscode, copilot-cli, jetbrains.

use anyhow::{Result, bail};

Expand All @@ -22,6 +22,7 @@ use super::targets::{
qoder::QODER_TARGET,
trae::TRAE_TARGET,
zed::ZED_TARGET,
zuno::ZUNO_TARGET,
};
use super::types::{AgentTarget, DetectionResult, InstallContext, Location};

Expand All @@ -38,6 +39,7 @@ pub fn all_targets() -> Vec<&'static dyn AgentTarget> {
&TRAE_TARGET,
&QODER_TARGET,
&ZED_TARGET,
&ZUNO_TARGET,
&VSCODE_TARGET,
&COPILOT_CLI_TARGET,
&JETBRAINS_TARGET,
Expand Down Expand Up @@ -143,6 +145,7 @@ mod tests {
"trae",
"qoder",
"zed",
"zuno",
"vscode",
"copilot-cli",
"jetbrains",
Expand Down
74 changes: 68 additions & 6 deletions crates/codegraph-cli/src/installer/shared.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,30 @@ use super::types::{FileAction, FileWrite};
pub const CODEGRAPH_SECTION_START: &str = "<!-- CODEGRAPH_START -->";
pub const CODEGRAPH_SECTION_END: &str = "<!-- CODEGRAPH_END -->";

/// The marker-fenced agent-instructions block, byte-identical to
/// `instructions-template.ts:42-51` (`CODEGRAPH_INSTRUCTIONS_BLOCK`).
/// The marker-fenced agent-instructions block.
///
/// Kept agent-neutral because the same body is written to Codex/OpenCode
/// `AGENTS.md`, Claude `CLAUDE.md`, Gemini `GEMINI.md`, and Zuno `AGENTS.md`.
pub const CODEGRAPH_INSTRUCTIONS_BLOCK: &str = "<!-- CODEGRAPH_START -->
## CodeGraph

In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
When a repository contains a `.codegraph/` directory, use CodeGraph before grep/find or reading source files when you need to understand or locate code.

Before the first query in a repository, verify that the index is usable:

- **MCP:** `codegraph_status`
- **Shell:** `codegraph status . --json`

Do not infer index readiness from the directory alone. Follow the recovery guidance reported by `status`; do not initialize or rebuild an index unless the user requests it or `status` explicitly requires it.

- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` and `codegraph node <symbol-or-file>` print the same output.
For code research:

If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
- Start with `codegraph_explore` for an area, feature, or call flow.
- Use `codegraph_search` to locate a known symbol.
- Use `codegraph_node` for a symbol's source and caller/callee trail, or for a line-numbered whole file.
- If MCP tools are unavailable, use `codegraph explore`, `codegraph search`, and `codegraph node`.

If there is no `.codegraph/` directory, do not create one unless the user asks.
<!-- CODEGRAPH_END -->";

/// The MCP-server config block codegraph injects. Ports `getMcpServerConfig`
Expand Down Expand Up @@ -561,6 +574,24 @@ pub fn replace_or_append_marked_section(
FileAction::Updated
}

/// Preview what [`upsert_instructions_entry`] would do without writing.
pub fn instructions_entry_action(path: &Path) -> FileAction {
let Ok(content) = fs::read_to_string(path) else {
return FileAction::Created;
};
if let (Some(start_idx), Some(end_idx)) = (
content.find(CODEGRAPH_SECTION_START),
content.find(CODEGRAPH_SECTION_END),
) && end_idx > start_idx
{
let block_end = end_idx + CODEGRAPH_SECTION_END.len();
if &content[start_idx..block_end] == CODEGRAPH_INSTRUCTIONS_BLOCK {
return FileAction::Unchanged;
}
}
FileAction::Updated
}

/// Upsert the CodeGraph instructions block. Ports `upsertInstructionsEntry`
/// (shared.ts:185) — the `appended` action is folded into `Updated` there too.
pub fn upsert_instructions_entry(path: &Path) -> FileWrite {
Expand Down Expand Up @@ -1038,6 +1069,37 @@ mod tests {
let _ = fs::remove_dir_all(p.parent().unwrap());
}

#[test]
fn managed_instructions_are_status_first_and_agent_neutral() {
let text = CODEGRAPH_INSTRUCTIONS_BLOCK;
assert!(text.contains("`codegraph_status`"));
assert!(text.contains("`codegraph status . --json`"));
assert!(text.contains("`codegraph_search`"));
assert!(text.contains("caller/callee trail"));
assert!(text.contains("do not create one unless the user asks"));
assert!(!text.contains("deferred"));
assert!(!text.contains("tool search"));
}

#[test]
fn instructions_entry_action_previews_without_writing() {
let p = tmp_path("AGENTS-preview.md");
assert_eq!(instructions_entry_action(&p), FileAction::Created);
assert!(!p.exists());

fs::write(
&p,
format!("user content\n\n{CODEGRAPH_SECTION_START}\nold\n{CODEGRAPH_SECTION_END}\n"),
)
.unwrap();
assert_eq!(instructions_entry_action(&p), FileAction::Updated);
assert!(fs::read_to_string(&p).unwrap().contains("\nold\n"));

upsert_instructions_entry(&p);
assert_eq!(instructions_entry_action(&p), FileAction::Unchanged);
let _ = fs::remove_dir_all(p.parent().unwrap());
}

#[test]
fn marked_section_appends_to_existing_body() {
let p = tmp_path("doc.md");
Expand Down
4 changes: 4 additions & 0 deletions crates/codegraph-cli/src/installer/targets/claude.rs
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ impl AgentTarget for ClaudeCodeTarget {
format!("# Add to {}\n\n{snippet}\n", target.display())
}

fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option<PathBuf> {
Some(instructions_path(ctx, loc))
}

fn supports_skills(&self, _loc: Location) -> bool {
true
}
Expand Down
4 changes: 4 additions & 0 deletions crates/codegraph-cli/src/installer/targets/codex.rs
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,10 @@ impl AgentTarget for CodexTarget {
)
}

fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option<PathBuf> {
(loc == Location::Global).then(|| instructions_path(ctx))
}

// Skill support is INTENTIONALLY decoupled from `supports_location`: Codex
// MCP config is global-only, yet Codex DOES scan project-local skills, so
// skills are gated on `supports_skills` (true for BOTH locations), never on
Expand Down
Loading
Loading