agentleFS
rebornixrebornix/Agmente/Agents.md

Agmente

AGENTS.md545 starsChanged 9 months agoMITView on GitHub

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
  1. Distinctive:

    Update Agents.md and CLAUDE.md in the same PR when adding:

    line 16
  2. Distinctive:

    Update the closest nested AGENTS.md in the same PR when changing:

    line 20
  3. Distinctive:

    test contracts or required test env variables.

    line 24
  4. Very specific:

    If a code change does not require doc updates, note Docs: N/A in the PR description.

    line 25
  5. Very specific:

    Create <component>/AGENTS.md when introducing a new component that has runtime logic or tests.

    line 28
  6. Distinctive:

    Add the new component doc to both root files (Agents.md and CLAUDE.md).

    line 29
  7. Very specific:

    Create .agmente.paths from .agmente.paths.example only if it does not already exist.

    line 37
  8. Very specific:

    Use .agmente.paths as the single local path registry for ACP/Codex upstream checkouts.

    line 39
  9. Distinctive:

    Keep ACP session flow and Codex thread/turn flow separate in app state and UI.

    line 48
  10. Very specific:

    Detection: if initialize returns a Codex userAgent (for example codex/…), Agmente switches to Codex mode for that server.

    line 53
  11. Distinctive:

    Create a new session to begin chatting.

    line 60
  12. Very specific:

    If session/load is available, opening a persisted session restores full conversation history from the server.

    line 66
  13. Very specific:

    If session/list is available, the app refreshes server-side session summaries.

    line 67
  14. Very specific:

    Persistence with @rebornix/stdio-to-ws: when using --persist, the server keeps the child process alive during disconnections and buffers …

    line 72
  15. Distinctive:

    Add a server with:

    line 93
  16. Very specific:

    Add a server with endpoint: ws://localhost:8765

    line 125
  17. Very specific:

    Start with e2e/README.md, then read:

    line 157
  18. Very specific:

    When a user asks to run an E2E scenario, resolve the request from e2e/scenarios/ first.

    line 164
  19. Distinctive:

    If an execute-only run is blocked by missing hooks or incomplete automation affordances, report the blocker and stop.

    line 167
  20. Distinctive:

    Only edit code, tests, skills, or docs when the user explicitly asks to fix, stabilize, or make the scenario executable.

    line 168
  21. Very specific:

    If the in-session MCP tool subset does not expose required UI automation actions (tap, swipe, gesture, type-text, long-press), use the …

    line 175
  22. Distinctive:

    Start the local agent: - Run one of the agent commands above in a terminal

    line 182
  23. Very specific:

    Verify UI: - Use describe_ui + screenshot to check UI state

    line 184
  24. Distinctive:

    Iterate: - Stop app, rebuild if code changes needed

    line 187
  25. Distinctive:

    Use these rules for every simulator automation run to avoid wrong taps and wrong mode selection:

    line 194
  26. Very specific:

    Check MCP UI tool availability first: If the in-session mcp_xcodebuildmcp_* subset is missing required interaction tools (tap, swipe, …

    line 196
  27. Very specific:

    Never tap from screenshots alone: Always run describe_ui immediately before any tap/long-press/swipe that depends on coordinates.

    line 197
  28. Very specific:

    Prefer semantic targeting first: Use tap(id: ...) or tap(label: ...) before raw x,y coordinates.

    line 198
  29. Very specific:

    Treat coordinates as single-use: After any navigation, modal, keyboard show/hide, or form validation state change, run describe_ui again …

    line 199
  30. Distinctive:

    Use post-action assertions: After critical actions (for example ACP vs Codex selection), confirm expected text is visible:

    line 201
  31. Distinctive:

    Do not continue after ambiguous state: If UI elements overlap (e.g.

    line 204
  32. Distinctive:

    Start/stop the agent: Always start a local agent before testing, and kill it when done.

    line 237
  33. Very specific:

    Use describe_ui for coordinates: Don't guess tap coordinates from screenshots.

    line 238
  34. Distinctive:

    Rebuild after changes: Stop the app, then rebuild to ensure fresh code is deployed.

    line 240
  35. Distinctive:

    Fix: Leave working directory empty, or set a valid path on the agent's host.

    line 256
  36. Distinctive:

    If you previously saved a server with incorrect settings (wrong scheme, bad working directory), you may need to delete and re-add it after …

    line 260
  37. Distinctive:

    After testing, always stop the local agent server:

    line 263
  38. Distinctive:

    Always: remove the app from the simulator when done testing:

    line 269
  39. Very specific:

    If you extend the client, keep new RPC methods consistent with ACP JSON-RPC envelopes and add handlers to ACPViewModel.

    line 295

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
Agents.md

Agmente Agents Guide

Documentation Topology

  • Agents.md (this file) is the root index for all coding agents.
  • CLAUDE.md is the Cloud/Claude agent entrypoint and should reference the same component docs.
  • Component-specific guidance lives next to code in nested files:
    • Agmente/AGENTS.md
    • ACPClient/AGENTS.md
    • AppServerClient/AGENTS.md
    • AgmenteTests/AGENTS.md
    • AgmenteUITests/AGENTS.md
    • e2e/AGENTS.md
  • Root files should stay concise and link to nested docs instead of duplicating implementation detail.

Documentation Update Policy

  • Update Agents.md and CLAUDE.md in 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.md in 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/A in the PR description.

Adding New Components or Protocols

  • Create <component>/AGENTS.md when introducing a new component that has runtime logic or tests.
  • Add the new component doc to both root files (Agents.md and CLAUDE.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.paths from .agmente.paths.example only if it does not already exist; otherwise keep your existing file and update keys as needed.
  • .agmente.paths is local-only and gitignored.
  • Use .agmente.paths as the single local path registry for ACP/Codex upstream checkouts.
  • Required variables:
    • AGMENTE_ACP_REPO: local agent-client-protocol checkout.
    • AGMENTE_CODEX_REPO: local codex checkout (must contain codex-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 initialize and 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, optional session/list and session/load).
  • Codex mode uses app-server v2 methods (thread/start, thread/resume, thread/list, turn/start, turn/interrupt, model/list, skills/list).
  • Detection: if initialize returns a Codex userAgent (for example codex/…), 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/list support (like Gemini), sessions are persisted to local storage (Core Data) so they remain visible after app restart.
    • If session/load is available, opening a persisted session restores full conversation history from the server.
    • If session/list is available, the app refreshes server-side session summaries.
  • Codex threads
    • The app uses thread/list for summaries and thread/resume for full history.
    • cwd/timestamp metadata comes from thread/list when 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.
  • Persistence with @rebornix/stdio-to-ws: when using --persist, the server keeps the child process alive during disconnections and buffers messages. Agmente sends a persistent X-Client-Id header 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:8788

Stop 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 && or ;). 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 8765

Stop 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 8765

Add a server with endpoint: ws://localhost:8765

Tip: Always use --persist flag with stdio-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 persistent X-Client-Id header to enable this feature. Use --grace-period to keep the process alive for a set time (seconds) after disconnect.


Running Tests

ACPClient (SwiftPM)

swift test --package-path /path/to/Agmente-oss/ACPClient

App Tests (Xcode)

List destinations and pick a simulator UDID:

xcodebuild -project /path/to/Agmente-oss/Agmente.xcodeproj -scheme Agmente -showdestinations

Run tests:

xcodebuild -project /path/to/Agmente-oss/Agmente.xcodeproj \
  -scheme Agmente \
  -destination "platform=iOS Simulator,id=<SIMULATOR_UDID>" \
  test

E2E Scenarios

  • Repository-owned E2E specs live under e2e/.
  • Start with e2e/README.md, then read:
    • e2e/AGENTS.md
    • e2e/schema/scenario-frontmatter.md
    • e2e/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, and reproduce scenario 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 the xcodebuildmcp CLI instead of workarounds:
npx -y xcodebuildmcp@latest tools

Testing Workflow

  1. Start the local agent - Run one of the agent commands above in a terminal
  2. Build & run - Discover project, list simulators, build and run on simulator
  3. Verify UI - Use describe_ui + screenshot to check UI state
  4. Interact - Tap, type, gesture to test features (always use describe_ui for coordinates)
  5. Validate - Screenshot + describe_ui to confirm results
  6. Iterate - Stop app, rebuild if code changes needed
  7. 🧹 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:

  1. 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 to xcodebuildmcp CLI.
  2. Never tap from screenshots alone. Always run describe_ui immediately before any tap/long-press/swipe that depends on coordinates.
  3. Prefer semantic targeting first. Use tap(id: ...) or tap(label: ...) before raw x,y coordinates.
  4. Treat coordinates as single-use. After any navigation, modal, keyboard show/hide, or form validation state change, run describe_ui again before the next coordinate tap.
  5. Verify segmented control state explicitly. For ServerTypePicker and ProtocolPicker, do not assume selection from a prior run; verify selected mode from nearby text or resulting UI state after tapping.
  6. 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.
  7. 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.
  8. 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

TestStepsExpected Result
Add ACP serverAdd Server → select ACP → Enter ws://localhost:8765/message → SaveServer saved, can connect
Add Codex serverAdd Server → select Codex → Enter ws://127.0.0.1:8788 → SaveServer saved, can connect
Connect to serverTap Connect on serverStatus shows "Connected"
Initialize clientConnect → InitializeStatus shows "Initialized"
Handle connection errorEnter invalid endpointError message displayed

✅ Session Tests

TestStepsExpected Result
Create new sessionTap "+" or "New Session"New session appears in sidebar
Select sessionTap on sessionChat view opens
Send messageType message → SendMessage appears, response received
Cancel requestSend message → Tap cancelRequest cancelled, UI responsive

✅ UI/UX Tests

TestStepsExpected Result
Keyboard dismissTap outside text fieldKeyboard dismisses
Scroll chatSwipe up/down in chatSmooth scrolling
Tool calls displaySend message triggering toolsTool 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_ui for coordinates: Don't guess tap coordinates from screenshots.
  • Wait for responses: Agent processing takes time; use postDelay/preDelay parameters on tap commands instead of running separate sleep commands (which can kill the agent server).
  • Rebuild after changes: Stop the app, then rebuild to ensure fresh code is deployed.
  • Never run sleep in the same terminal as the agent: Running sleep or 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.Agmente

You 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:

StepCommandWhy
1. Stop agent serverpkill -9 -f "stdio-to-ws.*8765"Frees port 8765 for future tests
2. Uninstall appxcrun simctl uninstall <UUID> com.example.AgmenteRemoves 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 ACPClient Swift package (Agmente/ACPClient) to speak ACP over WebSocket.
  • ACP protocol/spec upstream reference checkout: AGMENTE_ACP_REPO/docs (especially AGMENTE_ACP_REPO/docs/protocol and AGMENTE_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 optional session/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, version 0.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
  • 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
  • Schema generation (from installed Codex CLI):
    • codex app-server generate-ts --out DIR
    • codex app-server generate-json-schema --out DIR

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.