Feature request: read-only repo-local project_state for cross-session continuity

Resolved 💬 6 comments Opened May 31, 2026 by genforAI Closed Jun 5, 2026

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

Codex app-server / CLI extension layer. This proposal is not Desktop-specific and does not depend on private Desktop UI code.

Problem

Long-running Codex work often spans multiple sessions, subagents, or resumed threads. A repository may contain durable coordination artifacts such as contracts, handoff notes, integration blockers, review state, merge proposals, or ledgers, but Codex currently treats those as ordinary files unless the user repeatedly points the agent at them.

This creates avoidable drift: one session changes an API while another session keeps an old assumption; a review note blocks integration but a later turn does not notice; a resumed agent relies on chat history instead of repo-local state.

What feature would you like to see?

Add a small optional Codex-native project_state capability for read-only repo-local project state:

detect .codex/project-state/ by default when present;
allow existing layouts such as pgsa/ only through explicit project config, not automatic brand-specific detection;
add a short prompt fragment only when that state root exists;
expose scoped read-only tools: project_state.status, project_state.list, project_state.read, and project_state.search;
keep all project-state artifacts in the repository and avoid hidden databases, daemons, or background services;
add no write/update tools, no cross-root access, no Codex-owned persistence, and no Desktop UI dependency in the MVP.

Why this is different from normal file/read/grep tools

The value is not just another way to read files. The feature would give Codex a conditional signal that repo-local project notes are available as user/project-provided continuity context, expose that state through a stable read-only namespace, and keep all access scoped to one detected root. These artifacts do not override system, developer, or user instructions. Generic file tools can inspect files, but they do not provide the same prompt steering, read-only guarantee, or future extension point for safer project coordination.

Suggested Phase 1 implementation

The closest fit appears to be a new extension crate under codex-rs/ext/, similar in shape to the memories extension:

thread lifecycle: discover the project-state root from the current config/cwd;
context contributor: inject a short conditional prompt fragment;
tool contributor: expose read-only scoped tools;
app-server registration: add the extension to the app-server extension registry.

MCP support should wait unless the extension registry is wired into the MCP server surface too.

Non-goals

Do not vendor or copy a pgsa-harness folder into Codex.
Do not add a database, service, daemon, or hidden state.
Do not claim CI, security, sandbox, merge, review, or interpretability enforcement.
Do not add write tools in the MVP.
Do not add cross-root Project registry behavior in the MVP.
Do not make this a branded external protocol feature; existing layouts can be compatible through config while the Codex feature remains generic.

Safety requirements

Scope every tool path to the detected project-state root.
Reject absolute paths, .., hidden traversal below the state root, and symlink traversal.
Reject symlinked state roots.
Treat unreadable, binary, or non-UTF-8 files as unavailable rather than fatal where possible.
Enforce deterministic file-size and search traversal budgets.
Keep the prompt fragment short and conditional.
Do not make runtime enforcement claims; this feature reads repo-local state, it does not enforce sandbox, CI, review, security, or merge policy.

Tests

Unit tests for path scoping, absolute-path rejection, symlink root rejection, symlink traversal rejection, hidden path behavior, non-UTF-8 handling, oversized reads, bounded search traversal, and truncation.
Extension tests confirming no prompt/tools are contributed when no state root exists.
Extension tests confirming prompt/tools appear when .codex/project-state/ exists.
Config tests confirming an explicit compatibility root such as pgsa/ is detected only through project config.
Model-facing tool-spec tests confirming the project_state tools appear under one namespace.
App-server wiring tests or checks if registered there.

Additional information

For reference, there is a repo-local project-state protocol and proof bundle here:

https://github.com/genforAI/pgsa-harness

That repository is not proposed as a Codex dependency. It is only evidence for the artifact model and coordination workflow. The upstream Codex slice should remain generic and narrow: read-only app-server extension, default .codex/project-state/, optional configured compatibility root, no writes, no persistence, no cross-root access, and no external harness dependency.

Request

Would the Codex maintainers be open to this feature direction? If the problem and extension shape align with the roadmap, I can prepare a focused Phase 1 PR only if explicitly invited under the current contribution policy.

View original on GitHub ↗

6 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#24810
#25210

Powered by Codex Action

genforAI · 1 month ago

Thanks for the duplicate check. I reviewed #24810 and #25210. This proposal is adjacent to both, but I do not think it is a strict duplicate.

The distinction I intended:

#24810 Session Bridge focuses on write-time preservation/routing before compaction or session end. It is primarily about where extracted session knowledge should be stored.
#25210 OpenTTT focuses on an external MCP / cryptographic event DAG for workflow history recovery.
This issue proposes a smaller Codex-native, read-only project_state surface: discover existing repo-local coordination artifacts and expose scoped status/list/read/search tools so future Codex sessions can inspect that state safely.

Non-overlap in the MVP: no write hooks, no database/daemon, no external MCP dependency, no event DAG, no cryptographic ordering, and no vendored harness. The feature would only make already-present repo-local project state easier for Codex to discover and read.

If maintainers prefer consolidating this under #24810 or #25210, I am happy to close this issue and move the focused read-only project_state variant there.

genforAI · 1 month ago

Follow-up after reviewing the scope: I think the safest framing is to keep this issue as a narrow Phase 1, not expand it into a larger coordination feature.

Phase 1 remains exactly the read-only repo-local project_state surface described above:

detect an existing project-state root such as pgsa/;
add a short conditional prompt fragment only when state exists;
expose scoped read-only tools for status, list, read, and search;
add no database, daemon, Desktop UI dependency, write tools, or cross-root project registry;
preserve existing cwd, sandbox, and workspace-root boundaries.

The broader product direction this could start is Project Coordination: logical Projects, active linked sessions, handoffs, scope claims, and conflict/review records. I would treat that as future roadmap work rather than part of this MVP, because it needs separate design around persistence, permissions, Desktop UI surface, and write/conflict semantics.

So the concrete request for this issue stays small: would maintainers be open to a read-only extension/app-server slice for repo-local project state inspection?

genforAI · 1 month ago

For reference, we published a small repo-local project-state protocol and proof bundle here:

https://github.com/genforAI/pgsa-harness

I am not proposing that Codex vendor or depend on this repository. The Codex-side proposal remains a generic, read-only project_state extension that detects a repo-local state root such as .codex/project-state/, contributes a short conditional prompt, and exposes scoped read-only tools.

The reference repository is useful only as evidence for the artifact model and coordination workflow:

session registration and handoff edges;
contract/state/review/integration artifacts;
merge proposals for semantic conflicts;
append-only ledger events, including pending events for parallel sessions;
optional validation and drift-report tooling.

The intended upstream slice is still intentionally narrow: no Codex-owned persistence, no writes, no cross-root access, no Desktop UI requirement, and no dependency on PGSA branding or Python tooling.

genforAI · 1 month ago

I re-read the current contribution policy in docs/contributing.md and the PR template. My understanding is that external code contributions are invitation-only and that uninvited PRs are closed without review.

I have a local Phase 1 implementation prepared for this proposal, but I will not open a PR unless a maintainer explicitly invites it. The local slice stays narrow and matches the scope above:

app-server extension only;
default root .codex/project-state;
optional configured alias for existing layouts such as pgsa/;
read-only status/list/read/search tools;
no writes, persistence, cross-root access, Desktop UI dependency, or external harness dependency;
path safety tests for absolute paths, .., hidden paths, symlinks, non-UTF-8 files, oversized reads, and bounded search traversal.

Local validation on origin/main currently includes:

cargo test -p codex-project-state-extension -> 24 passed;
cargo test -p codex-config -> 148 passed;
targeted app-server extension registration test -> passed;
cargo fmt -- --check and git diff --check -> passed.

Would the Codex team be open to inviting a focused PR for this read-only Phase 1, or would you prefer that this remain only as an issue-level design/reference discussion for now?

genforAI · 1 month ago

Small scope/evidence update after tightening the local Phase 1 prototype:

the proposed default root is now .codex/project-state/;
existing layouts such as pgsa/ are compatibility roots only through explicit project config, not automatic detection;
the local Phase 1 implementation remains app-server only and read-only: status, list, read, search;
local validation now includes project-state extension tests, config tests, app-server check, formatting check, and a model-facing namespace test;
a Phase 2 dashboard/readout prototype exists locally as product evidence, but I would keep it out of any first PR unless maintainers ask for it.

I will not open a PR unless a maintainer explicitly invites one. The intended first PR would be the narrow Phase 1 only: no writes, no persistence, no cross-root Project registry, no Desktop UI dependency, and no external harness dependency.