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
- Agmente/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
Show its rules and text
We split this Agents.md into the rules it gives an agent
39 rules. About 0 are common, 20 are distinctive, and 19 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
19
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Update Agents.md and CLAUDE.md in the same PR when adding:
- Distinctive: line 20
Update the closest nested AGENTS.md in the same PR when changing:
- Distinctive: line 24
test contracts or required test env variables.
- Very specific: line 25
If a code change does not require doc updates, note Docs: N/A in the PR description.
- Very specific: line 28
Create <component>/AGENTS.md when introducing a new component that has runtime logic or tests.
- Distinctive: line 29
Add the new component doc to both root files (Agents.md and CLAUDE.md).
- Very specific: line 37
Create .agmente.paths from .agmente.paths.example only if it does not already exist.
- Very specific: line 39
Use .agmente.paths as the single local path registry for ACP/Codex upstream checkouts.
- Distinctive: line 48
Keep ACP session flow and Codex thread/turn flow separate in app state and UI.
- Very specific: line 53
Detection: if initialize returns a Codex userAgent (for example codex/…), Agmente switches to Codex mode for that server.
- Distinctive: line 60
Create a new session to begin chatting.
- Very specific: line 66
If session/load is available, opening a persisted session restores full conversation history from the server.
- Very specific: line 67
If session/list is available, the app refreshes server-side session summaries.
- Very specific: line 72
Persistence with
@rebornix/stdio-to-ws: when using --persist, the server keeps the child process alive during disconnections and buffers … - Distinctive: line 93
Add a server with:
- Very specific: line 125
Add a server with endpoint: ws://localhost:8765
- Very specific: line 157
Start with e2e/README.md, then read:
- Very specific: line 164
When a user asks to run an E2E scenario, resolve the request from e2e/scenarios/ first.
- Distinctive: line 167
If an execute-only run is blocked by missing hooks or incomplete automation affordances, report the blocker and stop.
- Distinctive: line 168
Only edit code, tests, skills, or docs when the user explicitly asks to fix, stabilize, or make the scenario executable.
- Very specific: line 175
If the in-session MCP tool subset does not expose required UI automation actions (tap, swipe, gesture, type-text, long-press), use the …
- Distinctive: line 182
Start the local agent: - Run one of the agent commands above in a terminal
- Very specific: line 184
Verify UI: - Use describe_ui + screenshot to check UI state
- Distinctive: line 187
Iterate: - Stop app, rebuild if code changes needed
- Distinctive: line 194
Use these rules for every simulator automation run to avoid wrong taps and wrong mode selection:
- Very specific: line 196
Check MCP UI tool availability first: If the in-session mcp_xcodebuildmcp_* subset is missing required interaction tools (tap, swipe, …
- Very specific: line 197
Never tap from screenshots alone: Always run describe_ui immediately before any tap/long-press/swipe that depends on coordinates.
- Very specific: line 198
Prefer semantic targeting first: Use tap(id: ...) or tap(label: ...) before raw x,y coordinates.
- Very specific: line 199
Treat coordinates as single-use: After any navigation, modal, keyboard show/hide, or form validation state change, run describe_ui again …
- Distinctive: line 201
Use post-action assertions: After critical actions (for example ACP vs Codex selection), confirm expected text is visible:
- Distinctive: line 204
Do not continue after ambiguous state: If UI elements overlap (e.g.
- Distinctive: line 237
Start/stop the agent: Always start a local agent before testing, and kill it when done.
- Very specific: line 238
Use
describe_uifor coordinates: Don't guess tap coordinates from screenshots. - Distinctive: line 240
Rebuild after changes: Stop the app, then rebuild to ensure fresh code is deployed.
- Distinctive: line 256
Fix: Leave working directory empty, or set a valid path on the agent's host.
- Distinctive: line 260
If you previously saved a server with incorrect settings (wrong scheme, bad working directory), you may need to delete and re-add it after …
- Distinctive: line 263
After testing, always stop the local agent server:
- Distinctive: line 269
Always: remove the app from the simulator when done testing:
- Very specific: line 295
If you extend the client, keep new RPC methods consistent with ACP JSON-RPC envelopes and add handlers to ACPViewModel.
≈ “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 Agents Guide
Documentation Topology
Agents.md(this file) is the root index for all coding agents.CLAUDE.mdis the Cloud/Claude agent entrypoint and should reference the same component docs.- Component-specific guidance lives next to code in nested files:
Agmente/AGENTS.mdACPClient/AGENTS.mdAppServerClient/AGENTS.mdAgmenteTests/AGENTS.mdAgmenteUITests/AGENTS.mde2e/AGENTS.md
- Root files should stay concise and link to nested docs instead of duplicating implementation detail.
Documentation Update Policy
- Update
Agents.mdandCLAUDE.mdin the same PR when adding:- a new top-level component/folder,
- a new protocol integration (or protocol mode switch logic),
- major architecture changes that affect more than one component.
- Update the closest nested
AGENTS.mdin the same PR when changing:- RPC method mappings,
- protocol parsing/serialization behavior,
- persistence/session/thread lifecycle behavior,
- test contracts or required test env variables.
- If a code change does not require doc updates, note
Docs: N/Ain the PR description.
Adding New Components or Protocols
- Create
<component>/AGENTS.mdwhen introducing a new component that has runtime logic or tests. - Add the new component doc to both root files (
Agents.mdandCLAUDE.md). - Document:
- ownership boundaries,
- key files and extension points,
- required tests,
- compatibility constraints with ACP/Codex and any migration behavior.
Local External Repo Config
- Create
.agmente.pathsfrom.agmente.paths.exampleonly if it does not already exist; otherwise keep your existing file and update keys as needed. .agmente.pathsis local-only and gitignored.- Use
.agmente.pathsas the single local path registry for ACP/Codex upstream checkouts. - Required variables:
AGMENTE_ACP_REPO: localagent-client-protocolcheckout.AGMENTE_CODEX_REPO: localcodexcheckout (must containcodex-rs).
What this app does
- Connect to an Agent Client Protocol (ACP) server over WebSocket.
- Connect to an OpenAI Codex app-server over WebSocket.
- Detect protocol after
initializeand route requests to the matching client/runtime. - Keep ACP session flow and Codex thread/turn flow separate in app state and UI.
Protocol modes in Agmente
- ACP mode uses ACP RPC methods (
session/new,session/prompt,session/cancel, optionalsession/listandsession/load). - Codex mode uses app-server v2 methods (
thread/start,thread/resume,thread/list,turn/start,turn/interrupt,model/list,skills/list). - Detection: if
initializereturns a CodexuserAgent(for examplecodex/…), Agmente switches to Codex mode for that server.
Adding your own agent
- Tap Add Server, then choose ACP or Codex in
ServerTypePicker. - Enter your WebSocket endpoint and optional bearer token.
- Set the working directory if your agent expects one.
- Save, then Connect and Initialize (if not done automatically).
- Create a new session to begin chatting.
Sessions
- Sessions/threads are kept in memory per server during the app lifecycle.
- ACP sessions
- For servers without
session/listsupport (like Gemini), sessions are persisted to local storage (Core Data) so they remain visible after app restart. - If
session/loadis available, opening a persisted session restores full conversation history from the server. - If
session/listis available, the app refreshes server-side session summaries.
- For servers without
- Codex threads
- The app uses
thread/listfor summaries andthread/resumefor full history. cwd/timestamp metadata comes fromthread/listwhen provided; if missing on older servers, cached values are preserved.- New prompts are sent with
turn/start, and streaming updates are rendered from turn/item notifications.
- The app uses
- Persistence with
@rebornix/stdio-to-ws: when using--persist, the server keeps the child process alive during disconnections and buffers messages. Agmente sends a persistentX-Client-Idheader on every connection so reconnecting clients can replay buffered messages. - Each session/thread opens a chat transcript view; tool calls are surfaced as system messages.
Running Local Agents
Codex app-server (direct WebSocket)
# If codex is installed in PATH
codex app-server --listen ws://127.0.0.1:8788
# Or from Codex source checkout (read `AGMENTE_CODEX_REPO` from `.agmente.paths`)
cd <AGMENTE_CODEX_REPO>/codex-rs
cargo run -p codex-cli -- app-server --listen ws://127.0.0.1:8788Stop Codex app-server:
pkill -9 -f "codex.*app-server.*8788"Add a server with:
Server Type:Codex- Endpoint:
ws://127.0.0.1:8788
Note: per Codex upstream docs, WebSocket transport is currently marked experimental.
Standard Commands (for VS Code auto-approve)
Important: Always run stop and start as separate commands (never chained with
&∨). This ensures consistent command strings for VS Code auto-approve.
Start agent server:
npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "npx @google/gemini-cli --experimental-acp" --port 8765Stop agent server:
pkill -9 -f "stdio-to-ws.*8765"Alternative Agents
# Vibe agent (Mistral)
npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "vibe-acp" --port 8765
# Claude Code
npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "npx @zed-industries/claude-code-acp" --port 8765
# Qwen agent (supports session/list)
npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "qwen --experimental-acp" --port 8765Add a server with endpoint: ws://localhost:8765
Tip: Always use
--persistflag withstdio-to-ws. This keeps the child process alive during brief disconnections (e.g., iOS app backgrounding) and buffers messages for replay on reconnect. Agmente automatically sends a persistentX-Client-Idheader to enable this feature. Use--grace-periodto keep the process alive for a set time (seconds) after disconnect.
Running Tests
ACPClient (SwiftPM)
swift test --package-path /path/to/Agmente-oss/ACPClientApp Tests (Xcode)
List destinations and pick a simulator UDID:
xcodebuild -project /path/to/Agmente-oss/Agmente.xcodeproj -scheme Agmente -showdestinationsRun tests:
xcodebuild -project /path/to/Agmente-oss/Agmente.xcodeproj \
-scheme Agmente \
-destination "platform=iOS Simulator,id=<SIMULATOR_UDID>" \
testE2E Scenarios
- Repository-owned E2E specs live under
e2e/. - Start with
e2e/README.md, then read:e2e/AGENTS.mde2e/schema/scenario-frontmatter.mde2e/backends/
e2e/scenarios/- Scenarios define what to test.
- Skills in
.agents/skills/are optional execution helpers and must not be the source of truth for scenario behavior. - When a user asks to run an E2E scenario, resolve the request from
e2e/scenarios/first. run,execute,validate, andreproducescenario requests mean execute-only, no repository edits.- Agentic testing means the agent should actually launch the backend, drive the simulator or protocol tools, capture evidence, evaluate assertions, and clean up.
- If an execute-only run is blocked by missing hooks or incomplete automation affordances, report the blocker and stop.
- Only edit code, tests, skills, or docs when the user explicitly asks to fix, stabilize, or make the scenario executable.
Simulator Automation Guardrails
Prerequisites
- Xcode installed with iOS Simulator
- Xcode Build MCP server running (provides
mcp_xcodebuildmcp_*tools) - If the in-session MCP tool subset does not expose required UI automation actions (
tap,swipe,gesture,type-text,long-press), use thexcodebuildmcpCLI instead of workarounds:
npx -y xcodebuildmcp@latest toolsTesting Workflow
- Start the local agent - Run one of the agent commands above in a terminal
- Build & run - Discover project, list simulators, build and run on simulator
- Verify UI - Use
describe_ui+screenshotto check UI state - Interact - Tap, type, gesture to test features (always use
describe_uifor coordinates) - Validate - Screenshot + describe_ui to confirm results
- Iterate - Stop app, rebuild if code changes needed
- 🧹 Cleanup (REQUIRED) - Kill the agent server and uninstall the app from simulator
⚠️ IMPORTANT: Always complete the cleanup step! Failing to stop the agent server leaves a process running on port 8765, and failing to uninstall the app leaves stale state in the simulator.
UI Automation Guardrails (Required)
Use these rules for every simulator automation run to avoid wrong taps and wrong mode selection:
- Check MCP UI tool availability first. If the in-session
mcp_xcodebuildmcp_*subset is missing required interaction tools (tap,swipe,gesture,type-text,long-press), switch toxcodebuildmcpCLI. - Never tap from screenshots alone. Always run
describe_uiimmediately before any tap/long-press/swipe that depends on coordinates. - Prefer semantic targeting first. Use
tap(id: ...)ortap(label: ...)before rawx,ycoordinates. - Treat coordinates as single-use. After any navigation, modal, keyboard show/hide, or form validation state change, run
describe_uiagain before the next coordinate tap. - Verify segmented control state explicitly. For
ServerTypePickerandProtocolPicker, do not assume selection from a prior run; verify selected mode from nearby text or resulting UI state after tapping. - Use post-action assertions. After critical actions (for example ACP vs Codex selection), confirm expected text is visible:
- ACP mode should show ACP guidance text.
- Codex mode should show
OpenAI Codex app-server protocol.
- Do not continue after ambiguous state. If UI elements overlap (e.g. warning sheet over form) or expected controls are duplicated, stop and re-read hierarchy before proceeding.
- Record key checkpoints in logs. For E2E runs, capture and verify event progression (initialize, thread start/resume, turn start, turn completed) before declaring success.
Generic Coverage Checklist
Scenario-specific behavior now belongs under e2e/scenarios/. The checklist below is only a broad regression sweep.
✅ Server Connection Tests
| Test | Steps | Expected Result |
| Add ACP server | Add Server → select ACP → Enter ws://localhost:8765/message → Save | Server saved, can connect |
| Add Codex server | Add Server → select Codex → Enter ws://127.0.0.1:8788 → Save | Server saved, can connect |
| Connect to server | Tap Connect on server | Status shows "Connected" |
| Initialize client | Connect → Initialize | Status shows "Initialized" |
| Handle connection error | Enter invalid endpoint | Error message displayed |
✅ Session Tests
| Test | Steps | Expected Result |
| Create new session | Tap "+" or "New Session" | New session appears in sidebar |
| Select session | Tap on session | Chat view opens |
| Send message | Type message → Send | Message appears, response received |
| Cancel request | Send message → Tap cancel | Request cancelled, UI responsive |
✅ UI/UX Tests
| Test | Steps | Expected Result |
| Keyboard dismiss | Tap outside text field | Keyboard dismisses |
| Scroll chat | Swipe up/down in chat | Smooth scrolling |
| Tool calls display | Send message triggering tools | Tool calls shown as system messages |
Important Testing Notes
- Start/stop the agent: Always start a local agent before testing, and kill it when done.
- Use
describe_uifor coordinates: Don't guess tap coordinates from screenshots. - Wait for responses: Agent processing takes time; use
postDelay/preDelayparameters on tap commands instead of running separatesleepcommands (which can kill the agent server). - Rebuild after changes: Stop the app, then rebuild to ensure fresh code is deployed.
- Never run
sleepin the same terminal as the agent: Runningsleepor other commands in the agent server's terminal will kill the server. Always use a different terminal or use tap delay parameters.
Known Issues & Workarounds
Add Server form defaults
The Add Server form should have no placeholder values for scheme or host - users must enter these explicitly. Defaults:
- Protocol:
ws(most common for local testing) - Host: empty
- Working Directory: empty
Working directory path
The working directory is sent when creating new sessions. If the path doesn't exist on the agent's host, session creation will fail with:
ENOENT: no such file or directory, realpath '/path/that/does/not/exist'- Fix: Leave working directory empty, or set a valid path on the agent's host.
- For local testing on macOS, the default is
/path/to/your/workspace.
Existing server with bad config
If you previously saved a server with incorrect settings (wrong scheme, bad working directory), you may need to delete and re-add it after fixing the defaults in code. To delete: tap the "..." menu → Delete.
Killing the agent server
After testing, always stop the local agent server:
pkill -9 -f "stdio-to-ws.*8765"Uninstalling the app from simulator
Always remove the app from the simulator when done testing:
xcrun simctl uninstall <SIMULATOR_UUID> com.example.AgmenteYou can get the simulator UUID from xcrun simctl list devices or from the list_sims tool.
🧹 End-of-Test Cleanup Checklist
Both steps are required after every test session:
| Step | Command | Why |
| 1. Stop agent server | pkill -9 -f "stdio-to-ws.*8765" | Frees port 8765 for future tests |
| 2. Uninstall app | xcrun simctl uninstall <UUID> com.example.Agmente | Removes stale app state |
💡 Tip: Run these as the final step of every test, even if the test failed partway through.
ACPClient reference
- The iOS app uses the local
ACPClientSwift package (Agmente/ACPClient) to speak ACP over WebSocket. - ACP protocol/spec upstream reference checkout:
AGMENTE_ACP_REPO/docs(especiallyAGMENTE_ACP_REPO/docs/protocolandAGMENTE_ACP_REPO/docs/schema). - Key types:
ACPClientConfiguration(endpoint, auth token provider, ping),ACPClient(connect/send), and delegate callbacks for state and messages. - RPC entry points used in the app:
initialize,session/new,session/prompt,session/cancel, and optionalsession/list. - If you extend the client, keep new RPC methods consistent with ACP JSON-RPC envelopes and add handlers to
ACPViewModel.
Capabilities sent on initialize
- Filesystem read/write toggles (default on).
- Terminal support toggle (default on).
- Client info defaults: name
Agmente iOS, version0.1.0.
Codex app-server reference (local source)
- App-server implementation:
AGMENTE_CODEX_REPO/codex-rs/app-server- README for protocol flow and examples:
AGMENTE_CODEX_REPO/codex-rs/app-server/README.md
- README for protocol flow and examples:
- Protocol types/schema:
AGMENTE_CODEX_REPO/codex-rs/app-server-protocol- v2 protocol definitions (Thread/Turn/Item):
AGMENTE_CODEX_REPO/codex-rs/app-server-protocol/src/protocol/v2.rs
- v2 protocol definitions (Thread/Turn/Item):
- Schema generation (from installed Codex CLI):
codex app-server generate-ts --out DIRcodex app-server generate-json-schema --out DIR
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.

