From 0b94e0aa1bce458e57c0cfaac17808e633053b98 Mon Sep 17 00:00:00 2001 From: Alan Wizemann Date: Fri, 24 Apr 2026 01:10:26 +0200 Subject: [PATCH] docs: how agents see Scarf projects (v2.3 AGENTS.md injection) --- Project-Templates.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Project-Templates.md b/Project-Templates.md index 319aaf6..538bed4 100644 --- a/Project-Templates.md +++ b/Project-Templates.md @@ -221,6 +221,32 @@ The installer enforces these rules — a bundle that violates any of them is ref - **Bundle size capped:** 50 MB at the install layer, 5 MB at the catalog-submission layer. - **Install preview is load-bearing:** every file the installer will write appears in the sheet. There's no silent write path. +## How the agent sees the project (v2.3+) + +When you click **New Chat** on a project's Sessions tab, Scarf does two things: + +1. Starts `hermes acp` with the project directory as the session's working directory. +2. Writes a Scarf-managed block into `/AGENTS.md` between `` and `` markers, so Hermes's automatic context-file load picks up the project's identity. + +Hermes reads a context file from the session's cwd at startup, picking the first match in this priority order: `.hermes.md` → `HERMES.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. Each is capped at 20 KB. Scarf's managed block contains: + +- Project name + directory +- Dashboard and manifest paths +- Template id + version (for template-installed projects) +- Configuration field *names* (with type hints — `secret` fields marked as such, but **values never appear**) +- Cron jobs attributed to the project via the `[tmpl:] …` prefix +- A reminder to preserve template-author content below the block + +**Safe around hand-edits.** Everything outside the markers is left byte-identical on every refresh. Template-author AGENTS.md content lives safely below the block. + +**Secret-safe.** Config values stored in the Keychain never appear — only field names. The block is safe to drop into any agent's context. + +**Bare projects.** If you add a plain directory to Scarf (via the `+` button) and start a chat in it, Scarf creates a minimal `AGENTS.md` containing only the managed block. The agent still has identity-level project awareness even without a template. + +**Known caveat.** If any parent directory of your project contains a `.hermes.md` or `HERMES.md` file, Hermes's priority order picks *those* up first and the project's AGENTS.md is shadowed. No fix in v2.3 — planned for v2.4 pending input on how to handle authored `.hermes.md` files. + +The service backing all of this is `ProjectAgentContextService` in the main Scarf repo. Template authors: leave the `` region alone in your bundled `AGENTS.md`, put template-specific instructions below it. + ## Troubleshooting **"The install sheet closes as soon as I click Continue on the Configure step."**