For developers managing project documentation and communication in osFoundry, the default behavior of AI agents like Codex CLI can be inefficient. Without state management, an agent asked "What changed yesterday?" must re-read every note and channel to detect differences. A new workflow solves this by using sequence cursors. By storing the last seen event ID in a local file, Codex can query osFoundry for only the events that occurred after that specific point, drastically reducing token usage and latency.

The Three-Step Tool Chain

The integration relies on three specific MCP tools provided by osFoundry: list_granted_resources, list_project_resources, and poll_resource_events. The process begins by listing granted resources to establish the scope of access. Next, the agent lists resources within a specific project. Finally, it calls poll_resource_events for each resource, passing the after_sequence number retrieved from the local cursor file. This ensures that the server only returns new data, rather than forcing the client to diff entire datasets.

Implementing State with Cursors

State persistence is handled by a simple JSON file, typically located at .osfoundry/cursors.json within the repository. The file structure maps resource IDs to their last processed sequence number. The workflow instructs the agent to read this file before polling, use the values to filter server responses, and then write the new highest sequence numbers back to the file after processing. This write-after-read pattern ensures that if a session crashes mid-poll, no events are lost; the next run will simply re-fetch the same events from the last known safe point.

Security and Scope Management

Access control is strictly managed on the osFoundry side. Owners must explicitly grant Codex access to specific projects and message channels via the "Connected" tab. The list_granted_resources call returns only what the owner has authorized, preventing the agent from seeing unshared data. Furthermore, the Codex configuration in ~/.codex/config.toml should be limited to read-only scopes, such as osfoundry:read, to prevent accidental write operations during monitoring tasks. This separation of concerns ensures that the agent can observe changes without altering the underlying project data.

Key Takeaways

  • Use poll_resource_events with after_sequence to fetch only new data, avoiding full re-reads of notes and channels.
  • Persist state in a local .osfoundry/cursors.json file to maintain continuity across separate Codex sessions.
  • Restrict agent permissions to specific projects and channels via osFoundry's owner-controlled access grants.
  • Configure Codex with read-only scopes to ensure safe monitoring of project activity.

The Bottom Line

This cursor-based approach transforms Codex CLI from a brute-force reader into an efficient change detector. By leveraging osFoundry’s sequence logs and local state files, developers can achieve near-real-time project awareness with minimal token overhead.