Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `ai-memory install-instructions` — drop the proactive-use snippet
//! into a project's `CLAUDE.md` / `AGENTS.md` / other rules file.
//!
//! ## Why this exists
//!
//! Lifecycle hooks handle *capture* and *handoff surfacing*
//! automatically. What they can't do is make the agent *proactively
//! call* `memory_query` / `memory_recent` when it should — that
//! decision lives in the model's system prompt, fed turn-by-turn by
//! the project's CLAUDE.md / AGENTS.md.
//!
//! This subcommand drops a small, opinionated snippet into that
//! file. Idempotent via HTML-comment markers so re-running picks up
//! whatever the snippet evolves into without duplicating the block.
use std::io::Read as _;
use std::path::{Component, Path, PathBuf};
use anyhow::{Context, Result};
use crate::cli::{
InstallInstructionsArgs, InstallSkillsAgent, InstallSkillsArgs, InstallSkillsScope,
};
use crate::commands::apply_shared::{ApplyOutcome, apply_atomic};
use crate::commands::install_skills;
use crate::config::Config;
// Markers + the snippet body live in `ai_memory_core::routing_snippet`
// so the `memory_install_self_routing` MCP tool can return the same
// block this subcommand writes. Single source of truth.
use ai_memory_core::{MARKER_END, MARKER_START, compact_block, find_marker_line, full_block};
const LEGACY_ORPHAN_TAIL_LF: &str =
"` markers without\ndisturbing the rest of the file.\n<!-- ai-memory:end -->\n";
const LEGACY_ORPHAN_TAIL_CRLF: &str =
"` markers without\r\ndisturbing the rest of the file.\r\n<!-- ai-memory:end -->\r\n";
/// Run the `install-instructions` subcommand.
///
/// # Errors
/// Returns an error if the target path can't be written or if the
/// existing file isn't valid UTF-8.
pub fn run(config: &Config, args: InstallInstructionsArgs) -> Result<()> {
run_inner(args, &config.runtime_env, true)
}
pub(super) fn run_quiet(
args: InstallInstructionsArgs,
env: &crate::config::RuntimeEnv,
) -> Result<()> {
run_inner(args, env, false)
}
fn run_inner(
args: InstallInstructionsArgs,
env: &crate::config::RuntimeEnv,
report: bool,
) -> Result<()> {
let block = if args.compact {
compact_block()
} else {
full_block()
};
let targets = resolve_targets(args.target.as_ref())?;
if report {
let home = env
.var_os("HOME")
.or_else(|| env.var_os("USERPROFILE"))
.map(PathBuf::from);
if let Ok(cwd) = std::env::current_dir()
&& let Some(note) = claude_code_skips_agents_md(&targets, &cwd, home.as_deref())
{
eprintln!("{note}");
}
}
let skill_args = if args.no_skills {
None
} else {
Some(skill_args_from_instruction_args(&args, &targets))
};
let prepared_skills = if !args.print {
skill_args
.as_ref()
.map(|args| install_skills::prepare_install(args, env))
.transpose()?
} else {
None
};
if args.print {
for t in &targets {
println!("# Would write into: {}\n", t.display());
println!("{block}");
}
} else {
for target in &targets {
let outcome = apply_atomic(target, |existing| {
Ok(merge_instructions_block(existing, &block))
})?;
if report {
println!(
"✓ {} {} ({})",
outcome.verb(),
target.display(),
match outcome {
ApplyOutcome::Created => "new file",
ApplyOutcome::Updated => "backup written next to it",
ApplyOutcome::NoOp => "already up to date",
}
);
}
}
}
if let Some(prepared_skills) = prepared_skills {
if report {
install_skills::run_prepared(prepared_skills)?;
} else {
install_skills::run_prepared_quiet(prepared_skills)?;
}
}
Ok(())
}
/// Decide which file(s) the snippet should land in.
///
/// Precedence:
/// 1. `--target` passed explicitly → use exactly that path (one file).
/// 2. Both `CLAUDE.md` and `AGENTS.md` exist in `$PWD` → write to both
/// (a project that's set up for multiple agent CLIs deserves the
/// snippet in each convention).
/// 3. Only `CLAUDE.md` exists → write to it.
/// 4. Only `AGENTS.md` exists → write to it.
/// 5. Neither exists → default to `CLAUDE.md` AND print a hint about
/// `--target AGENTS.md` for Codex / OpenCode / Cursor / Gemini /
/// Kimi Code.
///
/// The auto-pick exists because Claude Code uses CLAUDE.md while
/// every other supported agent (Codex, OpenCode, Cursor, Gemini CLI,
/// Kimi Code) converged on AGENTS.md. The heuristic "extend whatever's
/// already there" matches the user's intent better than a hard-coded
/// default.
fn resolve_targets(explicit: Option<&std::path::PathBuf>) -> Result<Vec<std::path::PathBuf>> {
if let Some(p) = explicit {
return Ok(vec![p.clone()]);
}
let cwd = std::env::current_dir().context("getting CWD for install-instructions target")?;
let claude_md = cwd.join("CLAUDE.md");
let agents_md = cwd.join("AGENTS.md");
let has_claude = claude_md.exists();
let has_agents = agents_md.exists();
match (has_claude, has_agents) {
(true, true) => Ok(vec![claude_md, agents_md]),
(true, false) => Ok(vec![claude_md]),
(false, true) => Ok(vec![agents_md]),
(false, false) => {
eprintln!(
"note: neither CLAUDE.md nor AGENTS.md exists in {}; \
creating CLAUDE.md. If you use Codex / OpenCode / \
Cursor / Gemini CLI / Antigravity CLI / Kimi Code / \
Kiro CLI, re-run with `--target AGENTS.md`.",
cwd.display()
);
Ok(vec![claude_md])
}
}
}
/// A note for when the block goes only into `AGENTS.md` but Claude Code will
/// not read that file (#1297, #1298). Claude Code 2.1.277 and later reads
/// `AGENTS.md` only when no `CLAUDE.md`, `.claude/CLAUDE.md` or
/// `CLAUDE.local.md` exists in the working directory or above it; when one
/// does, it reads those instead. The block still reaches Claude Code when one
/// of those files imports the `AGENTS.md` being written. `@path` resolves from
/// the importing file (`~/` from the home directory), including mid-sentence;
/// code spans and fenced blocks are not imports. The user file
/// `~/.claude/CLAUDE.md` does not count.
fn claude_code_skips_agents_md(
targets: &[PathBuf],
cwd: &Path,
home: Option<&Path>,
) -> Option<String> {
let named = |name: &str| {
targets
.iter()
.any(|target| target.file_name().and_then(|n| n.to_str()) == Some(name))
};
if !named("AGENTS.md") || named("CLAUDE.md") {
return None;
}
let agents = written_agents_files(targets, cwd);
let first_agents = agents.first()?;
let mut found = Vec::new();
for dir in cwd.ancestors() {
for name in ["CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md"] {
if name == ".claude/CLAUDE.md" && home.is_some_and(|h| paths_match(h, dir)) {
continue;
}
let candidate = dir.join(name);
if candidate.is_file() {
found.push(candidate);
}
}
}
let first = found.first()?;
if found
.iter()
.any(|path| file_imports_written_agents(path, &agents, home))
{
return None;
}
let import = suggested_agents_import(first, first_agents);
Some(format!(
"note: {} exists, so Claude Code reads it instead of AGENTS.md and will not see \
this block. Add `{import}` to that file, or set Claude \
Code's Project instructions to `claude-md-and-agents-md`.",
first.display(),
))
}
fn written_agents_files(targets: &[PathBuf], cwd: &Path) -> Vec<PathBuf> {
targets
.iter()
.filter(|target| target.file_name().and_then(|name| name.to_str()) == Some("AGENTS.md"))
.map(|target| {
if target.is_absolute() {
target.clone()
} else {
cwd.join(target)
}
})
.collect()
}
/// How many import hops Claude Code follows from a memory file: an imported
/// file may import others, up to this depth.
const MAX_IMPORT_HOPS: usize = 4;
/// One imported instruction file can be user-controlled. Detection only needs
/// enough text to find ordinary `@path` directives, so do not allocate an
/// arbitrarily large file merely to decide whether Claude reads AGENTS.md.
const MAX_IMPORT_FILE_BYTES: usize = 256 * 1024;
/// Bound a broad import graph as well as each individual file.
const MAX_IMPORT_TOTAL_BYTES: usize = 1024 * 1024;
fn file_imports_written_agents(path: &Path, agents: &[PathBuf], home: Option<&Path>) -> bool {
let mut remaining = MAX_IMPORT_TOTAL_BYTES;
imports_within(
path,
agents,
home,
MAX_IMPORT_HOPS,
&mut std::collections::HashSet::new(),
&mut remaining,
)
}
/// Whether `path`, or a file it imports within `hops` hops, imports one of
/// `agents`. A file already visited is not read again, so an import cycle
/// ends.
fn imports_within(
path: &Path,
agents: &[PathBuf],
home: Option<&Path>,
hops: usize,
seen: &mut std::collections::HashSet<PathBuf>,
remaining: &mut usize,
) -> bool {
if hops == 0 || !seen.insert(path.to_path_buf()) {
return false;
}
let Some(text) = read_bounded_import(path, remaining) else {
return false;
};
claude_import_paths(&text).into_iter().any(|raw| {
let resolved = resolve_claude_import(&raw, path, home);
agents.iter().any(|target| paths_match(&resolved, target))
|| (resolved.is_file()
&& imports_within(&resolved, agents, home, hops - 1, seen, remaining))
})
}
fn read_bounded_import(path: &Path, remaining: &mut usize) -> Option<String> {
let allowance = (*remaining).min(MAX_IMPORT_FILE_BYTES);
if allowance == 0 {
return None;
}
let file = std::fs::File::open(path).ok()?;
let mut bytes = Vec::with_capacity(allowance.min(8 * 1024));
file.take((allowance + 1) as u64)
.read_to_end(&mut bytes)
.ok()?;
let consumed = bytes.len().min(allowance);
*remaining = remaining.saturating_sub(consumed);
if bytes.len() > allowance {
return None;
}
String::from_utf8(bytes).ok()
}
/// `@path` relative to the importing file, so `.claude/CLAUDE.md` needs
/// `@../AGENTS.md` and a parent file needs `@app/AGENTS.md`.
fn suggested_agents_import(importer: &Path, agents: &Path) -> String {
let from = importer.parent().unwrap_or(importer);
format!("@{}", slash_relative(from, agents))
}
fn resolve_claude_import(raw: &str, importer: &Path, home: Option<&Path>) -> PathBuf {
let base = importer.parent().unwrap_or(importer);
if let Some(rest) = home_relative(raw)
&& let Some(home) = home
{
return if rest.is_empty() {
home.to_path_buf()
} else {
home.join(rest)
};
}
let path = Path::new(raw);
if path.is_absolute() {
path.to_path_buf()
} else {
base.join(path)
}
}
fn home_relative(raw: &str) -> Option<&str> {
if raw == "~" {
Some("")
} else {
raw.strip_prefix("~/").or_else(|| raw.strip_prefix("~\\"))
}
}
fn paths_match(left: &Path, right: &Path) -> bool {
match (std::fs::canonicalize(left), std::fs::canonicalize(right)) {
(Ok(left), Ok(right)) => left == right,
// One side may not exist yet (`.claude/AGENTS.md` when only the
// project file does). Fold `.` and `..` without requiring either file.
_ => lexical_normalize(left) == lexical_normalize(right),
}
}
/// Fold `.` and `..` without touching the filesystem. A `..` that would climb
/// past the root stays at the root; import paths are absolute by the time
/// they reach here, so this does not consult the process cwd.
fn lexical_normalize(path: &Path) -> PathBuf {
let mut stack: Vec<Component<'_>> = Vec::new();
for component in path.components() {
match component {
Component::CurDir => {}
Component::ParentDir => match stack.last() {
Some(Component::Normal(_)) => {
stack.pop();
}
Some(Component::RootDir | Component::Prefix(_)) => {}
_ => stack.push(component),
},
other => stack.push(other),
}
}
stack.into_iter().collect()
}
fn slash_relative(from_dir: &Path, target: &Path) -> String {
let from = lexical_normalize(from_dir);
let to = lexical_normalize(target);
let from_comps: Vec<Component<'_>> = from.components().collect();
let to_comps: Vec<Component<'_>> = to.components().collect();
let mut shared = 0;
while shared < from_comps.len()
&& shared < to_comps.len()
&& from_comps[shared] == to_comps[shared]
{
shared += 1;
}
let root_left =
|component: &Component<'_>| matches!(component, Component::Prefix(_) | Component::RootDir);
if from_comps.iter().skip(shared).any(root_left) || to_comps.iter().skip(shared).any(root_left)
{
return forward_slashes(&to);
}
let mut parts = Vec::new();
for _ in from_comps.iter().skip(shared) {
parts.push("..".to_string());
}
for component in to_comps.iter().skip(shared) {
if let Component::Normal(part) = component {
parts.push(part.to_string_lossy().into_owned());
}
}
if parts.is_empty() {
forward_slashes(&to)
} else {
parts.join("/")
}
}
fn forward_slashes(path: &Path) -> String {
let mut out = String::new();
for component in path.components() {
match component {
Component::Prefix(prefix) => out.push_str(&prefix.as_os_str().to_string_lossy()),
Component::RootDir => {
if !out.ends_with('/') {
out.push('/');
}
}
Component::CurDir => push_slash_part(&mut out, "."),
Component::ParentDir => push_slash_part(&mut out, ".."),
Component::Normal(part) => push_slash_part(&mut out, &part.to_string_lossy()),
}
}
out
}
fn push_slash_part(out: &mut String, part: &str) {
if !out.is_empty() && !out.ends_with(['/', ':']) {
out.push('/');
}
out.push_str(part);
}
/// `@path` tokens Claude Code would import. Relative paths are not resolved
/// here; the caller joins them onto the importing file. Fenced blocks and
/// code spans are skipped, and a path ends at the first unescaped space. A
/// backtick run with no closer is literal text, matching CommonMark.
fn claude_import_paths(text: &str) -> Vec<String> {
let mut paths = Vec::new();
let mut prose = String::new();
let mut fence: Option<(u8, usize)> = None;
for line in text.split_inclusive('\n') {
let body = line.trim_end_matches(['\n', '\r']);
if let Some((tick, len)) = fence {
if fence_close(body, tick, len) {
fence = None;
}
continue;
}
if let Some(opened) = fence_open(body) {
scan_import_prose(&prose, &mut paths);
prose.clear();
fence = Some(opened);
continue;
}
prose.push_str(line);
}
scan_import_prose(&prose, &mut paths);
paths
}
fn fence_open(line: &str) -> Option<(u8, usize)> {
let bytes = line.as_bytes();
let mut i = 0;
while i < bytes.len() && i < 3 && bytes[i] == b' ' {
i += 1;
}
if i >= bytes.len() {
return None;
}
let tick = bytes[i];
if tick != b'`' && tick != b'~' {
return None;
}
let start = i;
while i < bytes.len() && bytes[i] == tick {
i += 1;
}
let len = i - start;
if len < 3 || (tick == b'`' && line[i..].contains('`')) {
return None;
}
Some((tick, len))
}
fn fence_close(line: &str, tick: u8, min_len: usize) -> bool {
let bytes = line.as_bytes();
let mut i = 0;
while i < bytes.len() && i < 3 && bytes[i] == b' ' {
i += 1;
}
let start = i;
while i < bytes.len() && bytes[i] == tick {
i += 1;
}
i - start >= min_len && line[i..].trim().is_empty()
}
fn scan_import_prose(text: &str, paths: &mut Vec<String>) {
let bytes = text.as_bytes();
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'`' && (i == 0 || bytes[i - 1] != b'`') {
let len = byte_run_len(bytes, i, b'`');
if let Some(end) = find_exact_run(bytes, i + len, b'`', len) {
i = end;
continue;
}
i += len;
continue;
}
if bytes[i] == b'@' && import_boundary(bytes, i) {
let (path, next) = read_import_path(text, i + 1);
if import_path_ok(&path) {
paths.push(path);
}
i = next.max(i + 1);
continue;
}
i += 1;
}
}
fn import_boundary(bytes: &[u8], at: usize) -> bool {
if at == 0 {
return true;
}
let prev = bytes[at - 1];
if prev == b'"' || prev == b'\'' {
return false;
}
!prev.is_ascii_alphanumeric()
&& !matches!(prev, b'_' | b'-' | b'.' | b'/' | b'\\' | b'@' | b'~')
}
fn import_path_ok(path: &str) -> bool {
!path.is_empty() && !path.starts_with(['"', '\''])
}
fn read_import_path(line: &str, start: usize) -> (String, usize) {
let bytes = line.as_bytes();
let mut i = start;
let mut out = String::new();
while i < bytes.len() {
if bytes[i] == b'\\'
&& let Some(next) = bytes.get(i + 1).copied()
&& (next == b' ' || next == b'\\')
{
out.push(next as char);
i += 2;
continue;
}
if bytes[i].is_ascii_whitespace() {
break;
}
let Some(ch) = line[i..].chars().next() else {
break;
};
out.push(ch);
i += ch.len_utf8();
}
(out, i)
}
fn byte_run_len(bytes: &[u8], start: usize, tick: u8) -> usize {
let mut i = start;
while i < bytes.len() && bytes[i] == tick {
i += 1;
}
i - start
}
/// Index just past a run of exactly `len` `tick` bytes that is not part of a
/// longer run. A longer run must not close a shorter span.
fn find_exact_run(bytes: &[u8], mut from: usize, tick: u8, len: usize) -> Option<usize> {
while from < bytes.len() {
let run_start = bytes[from] == tick && (from == 0 || bytes[from - 1] != tick);
if run_start && byte_run_len(bytes, from, tick) == len {
return Some(from + len);
}
from += 1;
}
None
}
fn skill_args_from_instruction_args(
args: &InstallInstructionsArgs,
targets: &[PathBuf],
) -> InstallSkillsArgs {
InstallSkillsArgs {
scope: args.skills_scope.unwrap_or(InstallSkillsScope::Project),
agent: args
.skills_agent
.unwrap_or_else(|| infer_skills_agent_from_instruction_targets(targets)),
target_dir: args.skills_target_dir.clone(),
print: args.print,
force: args.skills_force,
}
}
fn infer_skills_agent_from_instruction_targets(targets: &[PathBuf]) -> InstallSkillsAgent {
let mut has_claude_target = false;
let mut has_agents_target = false;
for target in targets {
match target.file_name().and_then(|name| name.to_str()) {
Some("CLAUDE.md") => has_claude_target = true,
Some("AGENTS.md") => has_agents_target = true,
_ => {}
}
}
match (has_claude_target, has_agents_target) {
(true, true) => InstallSkillsAgent::Both,
(false, true) => InstallSkillsAgent::Agents,
_ => InstallSkillsAgent::ClaudeCode,
}
}
/// Idempotent merge: when the markers exist, replace everything
/// between them (inclusive) with `block`. When they don't, append
/// `block` to the end of the file with a single blank-line
/// separator. The user's other content is never touched.
fn merge_instructions_block(existing: &str, block: &str) -> String {
// Anchor on markers that occupy their own line so an inline mention of
// the marker strings (e.g. this block's own prose describing them)
// cannot be mistaken for the real end delimiter — which would truncate
// the block and leave an orphan tail on every refresh.
if let Some(start_idx) = find_marker_line(existing, MARKER_START, 0)
&& let Some(end_pos) = find_marker_line(existing, MARKER_END, start_idx)
{
let end_idx = end_pos + MARKER_END.len();
// Consume a trailing newline after the end marker if present
// so we don't accumulate blank lines on every re-run.
let after_end = if existing.as_bytes().get(end_idx..end_idx + 2) == Some(b"\r\n") {
end_idx + 2
} else if existing.as_bytes().get(end_idx).copied() == Some(b'\n') {
end_idx + 1
} else {
end_idx
};
let tail = strip_legacy_orphan_tail(block, &existing[after_end..]);
let mut out = String::with_capacity(existing.len() + block.len());
out.push_str(&existing[..start_idx]);
out.push_str(block);
out.push_str(tail);
return out;
}
// No prior block — append. If the file already ends with a
// newline, separate with one blank line; otherwise add the
// newline + a blank line.
let mut out = existing.to_string();
if !out.is_empty() && !out.ends_with('\n') {
out.push('\n');
}
if !out.is_empty() {
out.push('\n');
}
out.push_str(block);
out
}
fn strip_legacy_orphan_tail<'a>(block: &str, tail: &'a str) -> &'a str {
let dynamic_orphan = legacy_orphan_tail(block);
let mut rest = tail;
loop {
if let Some(stripped) = rest.strip_prefix(LEGACY_ORPHAN_TAIL_LF) {
rest = stripped;
} else if let Some(stripped) = rest.strip_prefix(LEGACY_ORPHAN_TAIL_CRLF) {
rest = stripped;
} else if let Some(orphan) = dynamic_orphan
&& !orphan.is_empty()
&& let Some(stripped) = rest.strip_prefix(orphan)
{
rest = stripped;
} else {
return rest;
}
}
}
fn legacy_orphan_tail(block: &str) -> Option<&str> {
let real_start = find_marker_line(block, MARKER_START, 0)?;
let real_end = find_marker_line(block, MARKER_END, real_start + MARKER_START.len())?;
let mut search_from = real_start + MARKER_START.len();
while let Some(rel) = block[search_from..real_end].find(MARKER_END) {
let inline = search_from + rel;
if find_marker_line(block, MARKER_END, inline) != Some(inline) {
let orphan_start = inline + MARKER_END.len();
let orphan_end = consume_line_ending(block, real_end + MARKER_END.len());
return Some(&block[orphan_start..orphan_end]);
}
search_from = inline + MARKER_END.len();
}
None
}
fn consume_line_ending(s: &str, idx: usize) -> usize {
if s.as_bytes().get(idx..idx + 2) == Some(b"\r\n") {
idx + 2
} else if s.as_bytes().get(idx).copied() == Some(b'\n') {
idx + 1
} else {
idx
}
}
#[cfg(test)]
mod tests {
use super::*;
/// #1298, measured against Claude Code 2.1.300. `@path` resolves from the
/// importing file, including mid-sentence, and a fenced `@AGENTS.md` is
/// not an import. Two of these are silent misses on the exact-line check
/// and two are false notes; the parent-directory row is the third miss.
/// Claude Code follows imports through other imported files, up to four
/// hops, so an `AGENTS.md` reached through an intermediate file needs no
/// note; one five hops away, or only reachable through a cycle, does.
#[test]
fn agents_md_reached_through_nested_imports_counts_up_to_four_hops() {
let root = tempfile::tempdir().unwrap();
let dir = root.path();
std::fs::create_dir_all(dir.join("docs")).unwrap();
std::fs::write(dir.join("AGENTS.md"), "# rules\n").unwrap();
let agents = [dir.join("AGENTS.md")];
std::fs::write(dir.join("CLAUDE.md"), "@docs/a.md\n").unwrap();
std::fs::write(dir.join("docs/a.md"), "@../AGENTS.md\n").unwrap();
assert!(file_imports_written_agents(
&dir.join("CLAUDE.md"),
&agents,
None
));
// CLAUDE.md -> h1 -> h2 -> h3 -> h4 -> AGENTS.md is five hops.
for (from, to) in [
("CLAUDE.md", "@docs/h1.md"),
("docs/h1.md", "@h2.md"),
("docs/h2.md", "@h3.md"),
("docs/h3.md", "@h4.md"),
("docs/h4.md", "@../AGENTS.md"),
] {
std::fs::write(dir.join(from), format!("{to}\n")).unwrap();
}
assert!(!file_imports_written_agents(
&dir.join("CLAUDE.md"),
&agents,
None
));
// A cycle that never reaches AGENTS.md ends.
std::fs::write(dir.join("CLAUDE.md"), "@docs/c1.md\n").unwrap();
std::fs::write(dir.join("docs/c1.md"), "@c2.md\n").unwrap();
std::fs::write(dir.join("docs/c2.md"), "@c1.md\n").unwrap();
assert!(!file_imports_written_agents(
&dir.join("CLAUDE.md"),
&agents,
None
));
}
#[test]
fn claude_import_detection_refuses_oversized_and_non_utf8_files() {
let root = tempfile::tempdir().unwrap();
let agents = root.path().join("AGENTS.md");
std::fs::write(&agents, "# rules\n").unwrap();
let mut oversized = b"@AGENTS.md\n".to_vec();
oversized.resize(MAX_IMPORT_FILE_BYTES + 1, b'x');
let claude = root.path().join("CLAUDE.md");
std::fs::write(&claude, oversized).unwrap();
assert!(!file_imports_written_agents(
&claude,
std::slice::from_ref(&agents),
None
));
std::fs::write(&claude, [b'@', 0xff, b'\n']).unwrap();
assert!(!file_imports_written_agents(
&claude,
std::slice::from_ref(&agents),
None
));
}
#[test]
fn claude_import_detection_bounds_the_whole_import_graph() {
let root = tempfile::tempdir().unwrap();
let agents = root.path().join("AGENTS.md");
std::fs::write(&agents, "# rules\n").unwrap();
std::fs::write(
root.path().join("CLAUDE.md"),
"@one.md\n@two.md\n@three.md\n@four.md\n@leaf.md\n",
)
.unwrap();
for name in ["one.md", "two.md", "three.md", "four.md"] {
std::fs::write(root.path().join(name), vec![b'x'; MAX_IMPORT_FILE_BYTES]).unwrap();
}
std::fs::write(root.path().join("leaf.md"), "@AGENTS.md\n").unwrap();
assert!(!file_imports_written_agents(
&root.path().join("CLAUDE.md"),
std::slice::from_ref(&agents),
None
));
}
#[test]
fn claude_code_agents_import_matches_five_measured_cases() {
struct Case<'a> {
label: &'a str,
/// Working directory, relative to the temp root. `.` is the root.
cwd: &'a str,
agents: &'a str,
files: &'a [(&'a str, &'a str)],
expect_note: bool,
/// Import the note should tell the user to add, when it warns.
import_hint: Option<&'a str>,
}
const FENCED: &str = "```\n@AGENTS.md\n```\n";
let beside = [(".claude/CLAUDE.md", "@AGENTS.md\n")];
let parent_import = [(".claude/CLAUDE.md", "@../AGENTS.md\n")];
let mid_sentence = [("CLAUDE.local.md", "See @AGENTS.md for the team rules.\n")];
let fenced = [("CLAUDE.local.md", FENCED)];
let parent_dir = [("CLAUDE.local.md", "@AGENTS.md\n")];
let cases = [
Case {
label: ".claude/CLAUDE.md @AGENTS.md resolves beside the importer",
cwd: ".",
agents: "AGENTS.md",
files: &beside,
expect_note: true,
import_hint: Some("`@../AGENTS.md`"),
},
Case {
label: ".claude/CLAUDE.md @../AGENTS.md loads the project file",
cwd: ".",
agents: "AGENTS.md",
files: &parent_import,
expect_note: false,
import_hint: None,
},
Case {
label: "mid-sentence @AGENTS.md is an import",
cwd: ".",
agents: "AGENTS.md",
files: &mid_sentence,
expect_note: false,
import_hint: None,
},
Case {
label: "fenced @AGENTS.md is not an import",
cwd: ".",
agents: "AGENTS.md",
files: &fenced,
expect_note: true,
import_hint: Some("`@AGENTS.md`"),
},
Case {
label: "parent @AGENTS.md resolves to the parent file, not app/AGENTS.md",
cwd: "app",
agents: "app/AGENTS.md",
files: &parent_dir,
expect_note: true,
import_hint: Some("`@app/AGENTS.md`"),
},
];
let home = tempfile::tempdir().unwrap();
for case in cases {
let root = tempfile::tempdir().unwrap();
for (rel, body) in case.files {
let path = root.path().join(rel);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, body).unwrap();
}
let cwd = root.path().join(case.cwd);
let agents = root.path().join(case.agents);
std::fs::create_dir_all(agents.parent().unwrap()).unwrap();
if !agents.is_file() {
std::fs::write(&agents, "# agents\n").unwrap();
}
let note =
claude_code_skips_agents_md(std::slice::from_ref(&agents), &cwd, Some(home.path()));
if case.expect_note {
let note = note.unwrap_or_else(|| panic!("{}: expected a note", case.label));
assert!(
note.contains("so Claude Code reads it instead of AGENTS.md"),
"{}: {note}",
case.label
);
if let Some(hint) = case.import_hint {
let shown = hint.replace('/', std::path::MAIN_SEPARATOR_STR);
assert!(
note.contains(hint) || note.contains(&shown),
"{}: note {note} does not name {hint}",
case.label
);
}
} else {
assert!(
note.is_none(),
"{}: unexpected note: {}",
case.label,
note.unwrap_or_default()
);
}
}
}
/// Code spans are not imports, and `~/` resolves from the home directory
/// rather than from the importing file (#1298).
#[test]
fn claude_code_import_skips_code_spans_and_expands_home() {
let root = tempfile::tempdir().unwrap();
let agents = root.path().join("AGENTS.md");
std::fs::write(&agents, "# agents\n").unwrap();
std::fs::write(
root.path().join("CLAUDE.local.md"),
"See `@AGENTS.md` for the syntax.\n",
)
.unwrap();
let unrelated_home = tempfile::tempdir().unwrap();
let note = claude_code_skips_agents_md(
std::slice::from_ref(&agents),
root.path(),
Some(unrelated_home.path()),
);
assert!(
note.as_deref()
.is_some_and(|text| text.contains("`@AGENTS.md`")),
"a code span is not an import: {}",
note.unwrap_or_default()
);
let home = tempfile::tempdir().unwrap();
let project = home.path().join("proj");
std::fs::create_dir_all(&project).unwrap();
let agents = project.join("AGENTS.md");
std::fs::write(&agents, "# agents\n").unwrap();
std::fs::write(project.join("CLAUDE.local.md"), "@~/proj/AGENTS.md\n").unwrap();
let note =
claude_code_skips_agents_md(std::slice::from_ref(&agents), &project, Some(home.path()));
assert!(
note.is_none(),
"home import of the written file should suppress the note: {}",
note.unwrap_or_default()
);
std::fs::write(project.join("CLAUDE.local.md"), "@~/other/AGENTS.md\n").unwrap();
let note =
claude_code_skips_agents_md(std::slice::from_ref(&agents), &project, Some(home.path()));
assert!(
note.is_some(),
"a home import of a different file still leaves AGENTS.md unloaded"
);
}
#[test]
fn merge_appends_to_empty_file() {
let out = merge_instructions_block("", "BLOCK\n");
assert_eq!(out, "BLOCK\n");
}
#[test]
fn merge_appends_when_no_markers_present() {
let original = "# My project\n\nSome notes.\n";
let out = merge_instructions_block(original, "BLOCK\n");
assert!(out.starts_with("# My project"));
assert!(out.ends_with("BLOCK\n"));
// One blank line between user content and our block.
assert!(out.contains("Some notes.\n\nBLOCK\n"));
}
/// Real-world contract: the caller passes a marker-wrapped
/// block (that's what `run()` builds). The merge replaces the
/// prior bracketed section in place.
#[test]
fn merge_replaces_existing_block() {
let original =
format!("# My project\n\n{MARKER_START}\nOLD\n{MARKER_END}\n\nMore notes.\n");
let new_block = format!("{MARKER_START}\nNEW BLOCK\n{MARKER_END}\n");
let out = merge_instructions_block(&original, &new_block);
assert!(out.contains("# My project"));
assert!(out.contains("NEW BLOCK"));
// Old content gone.
assert!(!out.contains("OLD"));
// User content after the block is preserved.
assert!(out.contains("More notes."));
// No duplicate markers.
assert_eq!(out.matches(MARKER_START).count(), 1);
assert_eq!(out.matches(MARKER_END).count(), 1);
}
#[test]
fn merge_idempotent_double_run() {
let block = format!("{MARKER_START}\nBLOCK\n{MARKER_END}\n");
let first = merge_instructions_block("# Title\n", &block);
let second = merge_instructions_block(&first, &block);
assert_eq!(first, second, "second merge must be a no-op");
}
/// Regression: a block whose body *mentions* the end marker inline
/// (mid-line, as older snippets did between backticks) must not be
/// truncated at that mention. The naive `find` matched the inline
/// marker, cut early, and re-injected the tail on every refresh; the
/// line-anchored matcher must keep the double-run a true no-op.
#[test]
fn merge_ignores_inline_marker_mention_in_block() {
let block = format!(
"{MARKER_START}\nsee the `{MARKER_END}` marker inline\nreal body\n{MARKER_END}\n"
);
let first = merge_instructions_block("# Title\n", &block);
let second = merge_instructions_block(&first, &block);
assert_eq!(first, second, "double-run must be a no-op");
// One inline mention + one real delimiter — nothing accumulated.
assert_eq!(second.matches(MARKER_START).count(), 1);
assert_eq!(second.matches(MARKER_END).count(), 2);
}
#[test]
fn merge_repairs_exact_legacy_orphan_tail() {
let block = full_block();
let legacy_corrupt = format!("# Title\n\n{block}{LEGACY_ORPHAN_TAIL_LF}More notes.\n");
let out = merge_instructions_block(&legacy_corrupt, &block);
assert_eq!(out, format!("# Title\n\n{block}More notes.\n"));
}
#[test]
fn merge_repairs_repeated_legacy_orphan_tails() {
let block = full_block();
let legacy_corrupt = format!(
"# Title\n\n{block}{LEGACY_ORPHAN_TAIL_LF}{LEGACY_ORPHAN_TAIL_CRLF}More notes.\n"
);
let out = merge_instructions_block(&legacy_corrupt, &block);
assert_eq!(out, format!("# Title\n\n{block}More notes.\n"));
}
#[test]
fn merge_repairs_exact_legacy_orphan_tail_crlf_variant() {
let block = full_block();
let legacy_corrupt = format!("# Title\r\n\r\n{block}{LEGACY_ORPHAN_TAIL_CRLF}More\r\n");
let out = merge_instructions_block(&legacy_corrupt, &block);
assert_eq!(out, format!("# Title\r\n\r\n{block}More\r\n"));
}
#[test]
fn merge_consumes_crlf_after_end_marker() {
let original = format!("# Title\r\n\r\n{MARKER_START}\r\nOLD\r\n{MARKER_END}\r\nMore\r\n");
let block = format!("{MARKER_START}\nNEW\n{MARKER_END}\n");
let out = merge_instructions_block(&original, &block);
assert_eq!(out, format!("# Title\r\n\r\n{block}More\r\n"));
}
/// The real shipped block round-trips cleanly through a refresh.
#[test]
fn merge_idempotent_with_real_block() {
let block = full_block();
let first = merge_instructions_block("# Title\n", &block);
let second = merge_instructions_block(&first, &block);
assert_eq!(first, second, "refresh of the real block must be a no-op");
assert_eq!(
second.matches(MARKER_END).count(),
block.matches(MARKER_END).count(),
"no orphaned end marker accumulated"
);
}
/// Defensive: existing file ends without trailing newline. We
/// should still produce well-formed output.
#[test]
fn merge_tolerates_missing_trailing_newline() {
let out = merge_instructions_block("# Title", "BLOCK\n");
assert!(out.starts_with("# Title\n"));
assert!(out.ends_with("BLOCK\n"));
}
}