Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""The user's instruction files in Vibey's system prompt (C-7 ``agent-core-contracts/tools.md`` section 9).
Discovery runs on real temporary directories. The walk reaches the filesystem root, so each test keeps only the files
under its own temporary directory.
"""
from __future__ import annotations
import os
import re
from pathlib import Path
import pytest
from modules.agents.vibey.instructions import InstructionFile, load_instruction_files, project_context
# The model-facing text, stated here rather than read from the constants it checks (C-7 tools.md section 9).
SUBTREE = (
"A directory below the working directory may hold its own instruction file with more specific rules for that "
"subtree: the first readable one of AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD in that "
"directory, and only that one. Read it before working with files there."
)
HEADER = (
"Project-specific instructions and guidelines:\n"
f"More general files come first; where two conflict, the later, more specific one wins.\n{SUBTREE}"
)
def _write(path: Path, text: str) -> Path:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding="utf-8")
return path
def _found(cwd: Path, global_path: Path, root: Path) -> list[tuple[str, str]]:
"""What the walk loads from ``cwd``, as paths relative to ``root`` (the global file by name), with contents."""
loaded = []
for file in load_instruction_files(str(cwd), global_path):
if file.is_global:
loaded.append(("<global>", file.content))
elif Path(file.path).is_relative_to(root):
loaded.append((Path(file.path).relative_to(root).as_posix(), file.content))
return loaded
def test_the_global_file_comes_first_then_each_directory_from_the_root_down_to_the_cwd(tmp_path) -> None:
global_path = _write(tmp_path / "home/.avibe/AGENTS.md", "global")
_write(tmp_path / "work/AGENTS.md", "workspace")
_write(tmp_path / "work/app/CLAUDE.md", "app")
cwd = tmp_path / "work/app/src"
cwd.mkdir(parents=True)
assert _found(cwd, global_path, tmp_path) == [
("<global>", "global"),
("work/AGENTS.md", "workspace"),
("work/app/CLAUDE.md", "app"),
]
# No global file: the walk alone.
assert _found(cwd, tmp_path / "missing/AGENTS.md", tmp_path) == [
("work/AGENTS.md", "workspace"),
("work/app/CLAUDE.md", "app"),
]
def test_each_directory_contributes_its_first_candidate_and_the_override_wins(tmp_path) -> None:
for name in ("AGENTS.override.md", "AGENTS.md", "CLAUDE.md"):
_write(tmp_path / "a" / name, f"a {name}")
for name in ("AGENTS.md", "CLAUDE.md"):
_write(tmp_path / "a/b" / name, f"b {name}")
_write(tmp_path / "a/b/c/CLAUDE.md", "c CLAUDE.md")
assert _found(tmp_path / "a/b/c", tmp_path / "none", tmp_path) == [
("a/AGENTS.override.md", "a AGENTS.override.md"),
("a/b/AGENTS.md", "b AGENTS.md"),
("a/b/c/CLAUDE.md", "c CLAUDE.md"),
]
@pytest.mark.skipif(os.name != "posix" or os.geteuid() == 0, reason="needs POSIX permissions that bind the user")
def test_an_unreadable_candidate_is_skipped_silently_and_the_next_one_read(tmp_path) -> None:
locked = _write(tmp_path / "repo/AGENTS.md", "locked")
_write(tmp_path / "repo/CLAUDE.md", "readable")
(tmp_path / "other/AGENTS.md").mkdir(parents=True) # not a file
_write(tmp_path / "other/CLAUDE.md", "after a directory")
locked.chmod(0)
try:
assert _found(tmp_path / "repo", tmp_path / "none", tmp_path) == [("repo/CLAUDE.md", "readable")]
assert _found(tmp_path / "other", tmp_path / "none", tmp_path) == [("other/CLAUDE.md", "after a directory")]
finally:
locked.chmod(0o644)
def test_symlinks_are_followed_and_a_file_is_loaded_once(tmp_path) -> None:
shared = _write(tmp_path / "elsewhere/principles.md", "principles")
global_path = tmp_path / "home/.avibe/AGENTS.md"
global_path.parent.mkdir(parents=True)
global_path.symlink_to(shared)
# The repository links its file to the same one, and keeps CLAUDE.md as a link to AGENTS.md.
(tmp_path / "repo").mkdir()
(tmp_path / "repo/AGENTS.md").symlink_to(shared)
(tmp_path / "repo/CLAUDE.md").symlink_to(tmp_path / "repo/AGENTS.md")
# A file outside the chain, reached through a link in it, is read.
(tmp_path / "repo/app").mkdir()
(tmp_path / "repo/app/AGENTS.md").symlink_to(_write(tmp_path / "elsewhere/app.md", "app rules"))
assert _found(tmp_path / "repo/app", global_path, tmp_path) == [
("<global>", "principles"),
("repo/app/AGENTS.md", "app rules"),
]
def test_blank_files_are_left_out(tmp_path) -> None:
_write(tmp_path / "repo/AGENTS.md", " \n\n")
_write(tmp_path / "repo/CLAUDE.md", "not reached: the blank AGENTS.md is this directory's file")
_write(tmp_path / "repo/app/AGENTS.md", "\ufeffapp")
assert _found(tmp_path / "repo/app", tmp_path / "none", tmp_path) == [("repo/app/AGENTS.md", "app")]
def _git_repo(root: Path) -> None:
_write(root / ".git/HEAD", "ref: refs/heads/master\n")
def _linked_worktree(main: Path, worktree: Path, name: str) -> None:
_write(main / ".git/worktrees" / name / "HEAD", "ref: refs/heads/feature\n")
_write(main / ".git/worktrees" / name / "commondir", "../..\n")
_write(worktree / ".git", f"gitdir: {main / '.git/worktrees' / name}\n")
@pytest.mark.parametrize("links", ("none", "main", "both"), ids=("files", "main file is a link", "both link one file"))
def test_a_nested_linked_worktree_does_not_load_its_main_repository_file_twice(tmp_path, links) -> None:
main = tmp_path / "repo"
_git_repo(main)
nested = main / ".worktrees/feature"
_linked_worktree(main, nested, "feature")
if links == "both":
# Both checkouts link the same shared file: it is still the worktree's that loads.
shared = _write(tmp_path / "elsewhere/rules.md", "shared rules")
(main / "AGENTS.md").symlink_to(shared)
(nested / "AGENTS.md").symlink_to(shared)
assert _found(nested / "src", tmp_path / "none", tmp_path) == [
("repo/.worktrees/feature/AGENTS.md", "shared rules")
]
return
if links == "main":
(main / "AGENTS.md").symlink_to(_write(tmp_path / "elsewhere/main-rules.md", "main copy"))
else:
_write(main / "AGENTS.md", "main copy")
_write(nested / "AGENTS.md", "worktree copy")
sibling = tmp_path / "feature-sibling"
_linked_worktree(main, sibling, "sibling")
_write(sibling / "AGENTS.md", "sibling copy")
# Both copies are the repository's: only the worktree's own is loaded.
assert _found(nested / "src", tmp_path / "none", tmp_path) == [("repo/.worktrees/feature/AGENTS.md", "worktree copy")]
# A sibling worktree has no main repository above it, and an ordinary checkout is its own repository.
assert _found(sibling, tmp_path / "none", tmp_path) == [("feature-sibling/AGENTS.md", "sibling copy")]
assert _found(main / "src", tmp_path / "none", tmp_path) == [("repo/AGENTS.md", "main copy")]
def test_the_section_holds_each_file_by_path_in_order() -> None:
files = [
InstructionFile("/home/me/.avibe/AGENTS.md", "global rules", is_global=True),
InstructionFile('/src/<a "b" & c>/AGENTS.md', "project rules"),
]
# A path is escaped for its quoted attribute: it cannot close the attribute or the tag.
assert project_context(files) == (
f"<project_context>\n{HEADER}\n\n"
'<project_instructions path="/home/me/.avibe/AGENTS.md">\nglobal rules\n</project_instructions>\n\n'
'<project_instructions path="/src/\\u003ca \\u0022b\\u0022 \\u0026 c\\u003e/AGENTS.md">\nproject rules\n'
"</project_instructions>\n</project_context>"
)
# Files below the cwd are never loaded, so the rule to look for them stands even when no file loaded.
assert project_context([]) == f"<project_context>\n{SUBTREE}\n</project_context>"
_NOTICE = re.compile(
r"\n\[Truncated: the first (\d+) of (\d+) bytes\. The instruction files share a 65,536-byte limit; read the file "
r"for the rest\.\]\n</project_instructions>"
)
def _blocks(section: str) -> dict[str, str]:
"""Each file's block text by path."""
return dict(re.findall(r'<project_instructions path="([^"]*)">\n(.*?)\n</project_instructions>', section, re.S))
def test_the_section_carries_at_most_64_kib_given_first_to_the_global_file_then_from_the_cwd_upward() -> None:
global_file = InstructionFile("/g/AGENTS.md", "g" * 10, is_global=True)
root_file = InstructionFile("/AGENTS.md", "r" * 40_000)
# The root file is cut: the global file and the cwd's come first.
section = project_context([global_file, root_file, InstructionFile("/repo/AGENTS.md", "p" * 40_000)])
blocks = _blocks(section)
assert len(section.encode("utf-8")) <= 65_536
assert blocks["/g/AGENTS.md"] == "g" * 10 and blocks["/repo/AGENTS.md"] == "p" * 40_000
((shown, size),) = _NOTICE.findall(section)
assert size == "40000" and blocks["/AGENTS.md"].startswith("r" * int(shown) + "\n[Truncated")
assert section.index("/g/AGENTS.md") < section.index('"/AGENTS.md"') < section.index("/repo/AGENTS.md")
# Less room: the cwd's file is cut, and the root file is named as not loaded.
section = project_context([global_file, root_file, InstructionFile("/repo/AGENTS.md", "p" * 70_000)])
assert len(section.encode("utf-8")) <= 65_536 and '"/AGENTS.md"' not in section
((shown, size),) = _NOTICE.findall(section)
assert size == "70000" and _blocks(section)["/repo/AGENTS.md"].startswith("p" * int(shown) + "\n[Truncated")
assert section.endswith(
"[Not loaded, over the 65,536-byte limit for instruction files: /AGENTS.md (40000 bytes). Read them if the "
"task needs them.]\n</project_context>"
)
def test_paths_and_markup_count_toward_the_limit() -> None:
# A deep tree with a file at every level: each block repeats a long path, and the notice names what it can.
files = [InstructionFile("/" + "d/" * 100 + f"{index}/AGENTS.md", "x") for index in range(1_000)]
section = project_context(files)
assert len(section.encode("utf-8")) <= 65_536
assert re.search(r"; and \d+ more\. Read them if the task needs them\.\]\n</project_context>$", section)
def test_a_cut_falls_on_a_character_boundary() -> None:
section = project_context([InstructionFile("/AGENTS.md", "é" * 40_000)])
((shown, size),) = _NOTICE.findall(section)
assert size == "80000" and _blocks(section)["/AGENTS.md"].startswith("é" * (int(shown) // 2) + "\n[Truncated")
assert int(shown) % 2 == 0
def test_a_huge_file_is_read_only_as_far_as_the_section_can_hold(tmp_path) -> None:
# Every Turn reads the files: a mistaken multi-megabyte one must cost no more than a full section.
_write(tmp_path / "repo/AGENTS.md", "x" * (16 * 65_536))
(file,) = [found for found in load_instruction_files(str(tmp_path / "repo"), tmp_path / "none") if
Path(found.path).is_relative_to(tmp_path)]
assert len(file.content.encode("utf-8")) <= 65_536 + 4
((_, size),) = _NOTICE.findall(project_context([file]))
assert size == str(16 * 65_536)
def test_undecodable_bytes_count_toward_the_limit_as_read(tmp_path) -> None:
# Each invalid byte reads as a three-byte replacement character: the limit holds for what the prompt carries.
(tmp_path / "repo").mkdir()
(tmp_path / "repo/AGENTS.md").write_bytes(b"\xff" * 65_536)
(file,) = [found for found in load_instruction_files(str(tmp_path / "repo"), tmp_path / "none") if
Path(found.path).is_relative_to(tmp_path)]
section = project_context([file])
assert len(section.encode("utf-8")) <= 65_536
((_, size),) = _NOTICE.findall(section)
assert size == str(3 * 65_536)