Agmente / Agmente
AGENTS.md545 starsChanged 9 months agoMITView on GitHub
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository13 other files it gives its agents.
- ACPClient/AGENTS.mdAGENTS.md
- Agents.mdAGENTS.md
- AgmenteTests/AGENTS.mdAGENTS.md
- AgmenteUITests/AGENTS.mdAGENTS.md
- AppServerClient/AGENTS.mdAGENTS.md
- e2e/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- acp-local-runnerSkill
- codex-local-cli-e2eSkill
- repeat-with-delaySkill
- upstream-protocol-drift-watchSkill
- run-agmente-codex-e2eSkill
- run-agmente-e2eSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Use AGMENTE_ACP_REPO and AGMENTE_CODEX_REPO entries instead of machine-specific absolute paths.
- Very specific: line 33
Use persistExtendedHistory: true on thread/start and thread/resume so cold app relaunch can recover richer tool-call history from …
- Distinctive: line 47
Add-server form or summary dialog changes must keep ACP and Codex messaging clearly separated.
- Distinctive: line 50
If changing initialization/protocol detection, validate ACP and Codex paths.
- Distinctive: line 51
If changing session/thread metadata parsing, verify list + open-session behavior.
- Very specific: line 52
If changing Codex thread hydration or reconciliation behavior, update Agmente/specs/codex-load-resume-merge.md and the corresponding …
- Distinctive: line 53
If changing add-server UX, verify both protocol summaries and warnings are accurate.
- Distinctive: line 54
If adding capability toggles/settings, persist and restore via existing model/storage patterns.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.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.
Files
Agmente App Layer Guide
Scope
SwiftUI app layer and protocol routing logic:
- Server management UI
- Session/thread UI state
- ACP vs Codex view model selection
External Repo Paths
- For upstream ACP/Codex source checks, read
.agmente.pathsfrom repo root. - Use
AGMENTE_ACP_REPOandAGMENTE_CODEX_REPOentries instead of machine-specific absolute paths.
Architecture Model
- The app has a single coordinator that owns per-server runtime state.
- Each server runtime follows one protocol mode at a time (ACP or Codex).
- Protocol-specific behavior stays isolated behind a shared server view-model contract.
- UI should rely on shared abstractions first, and branch only for protocol-specific screens/controls.
Architecture Invariants
AppViewModelowns one server view model per server ID.- ACP and Codex paths must remain protocol-isolated.
- UI should consume unified protocol (
ServerViewModelProtocol) where possible. - Detailed Codex load, resume, and merge behavior is specified in
Agmente/specs/codex-load-resume-merge.md. - Selecting a different server must not persist the previously selected server's endpoint/token/cwd into the new server while rebinding published connection fields; apply stored config non-destructively, then reconnect.
- Session/thread summaries should preserve server metadata (
cwd, timestamps) when available. - ACP placeholder-session resolution must be non-destructive: when
session/newreturns a real session ID, preserve the in-memory user/assistant transcript, treat the new session as already materialized for the current connection, and avoid issuing a follow-upsession/loadif richer local state already exists or the fresh session is still empty. - ACP session persistence must never save unresolved placeholder IDs as durable sessions. When a placeholder resolves, migrate any locally cached or persisted transcript state onto the real session ID so Copilot-style reloads can reopen the same conversation instead of duplicate or blank rows.
- ACP placeholder-session failures must be terminal for that draft: if
session/newfails, clear the placeholder session selection before any prompt path can fall through tosession/promptwith the placeholder ID. - Codex reconnect/resume must be non-destructive for active sessions: prefer richer in-memory chat/tool-call state when
thread/resumeis incomplete, and restore streaming/stop state from active turn status. - On reconnect (and open when possible), prefer non-destructive reattachment to loaded in-memory threads via
addConversationListener+thread/read; only fall back tothread/resumewhen the thread is not loaded or listener attach is unavailable. - Codex turns inferred only from
thread/resumeare resume-derived state, not confirmed live turns: keep them locally resettable in the composer, and only restore realturn/interruptbehavior after a successful loaded-thread attach/read or a live turn notification (turn/started,item/started,item/completed). - For resume-based hydration paths, issue at least one follow-up
thread/resumeto converge eventual-consistency gaps where streaming deltas are not replayed. - Use
persistExtendedHistory: trueonthread/startandthread/resumeso cold app relaunch can recover richer tool-call history from rollout-backed reads. - During Codex
thread/readmerge, preserve local rich assistant rows (tool calls/thoughts) while suppressing duplicate markdown-only assistant inserts already represented by those rows; per-turn ordering must remain user-first before assistant output. - Plan mode output must map to
.planassistant segments from Codex notifications (item/plan/delta,turn/plan/updated) and from completed assistant message payloads containing<proposed_plan>...</proposed_plan>. - For plan streaming, prefer typed app-server notifications (for example
item/plan/delta) over mirrored rawcodex/event/*notifications to avoid duplicate rendering. - Codex permissions selector maps to
turn/startoverrides on every turn:Default permissions=>approvalPolicy: "on-request"+sandboxPolicy.type: "workspaceWrite"Full access=>approvalPolicy: "never"+sandboxPolicy.type: "dangerFullAccess"(dangerous/high-risk mode)
Change Impact Rules
- Protocol detection changes must validate both first-connect and reconnect behavior.
- Session/thread list parsing changes must preserve ordering and metadata consistency.
- Open-session behavior must not regress summary metadata or current working directory display.
- Reconnect/background-resume changes must verify active-thread resubscription, streaming indicator state, and stop/send button behavior.
- For Codex, stop/send availability must follow active turn state, not only the presence of a streaming assistant row.
- Add-server form or summary dialog changes must keep ACP and Codex messaging clearly separated.
Contribution Checklist
- If changing initialization/protocol detection, validate ACP and Codex paths.
- If changing session/thread metadata parsing, verify list + open-session behavior.
- If changing Codex thread hydration or reconciliation behavior, update
Agmente/specs/codex-load-resume-merge.mdand the corresponding fixtures underAgmenteTests/Fixtures/CodexThreadReadMerge/. - If changing add-server UX, verify both protocol summaries and warnings are accurate.
- If adding capability toggles/settings, persist and restore via existing model/storage patterns.
Required Tests
CodexServerViewModelTestsViewModelSyncTestsACPSessionViewModelTests(when chat/session behavior changes)- Relevant
AgmenteUITestscoverage (when UI flow or accessibility IDs change) - Manual scenario:
copilot-smoke.mdwhen changing ACP protocol adoption, ACP/Codex mode routing, add-server ACP defaults,session/listcwd fanout, fresh-session lifecycle, or reconnect/load behavior
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
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.

