Codex-web AGENTS.md

Repository Guide for Coding Agents

This file is the operational contract for agents working in this repository. Read it before editing. Human-facing build and runtime details live in BUILDING.md and OPERATIONS.md.

Mission

Codex Web Terminal exposes real Codex CLI, Claude Code, and Google Antigravity CLI (agy) PTYs through an authenticated web interface. It must preserve terminal semantics rather than reimplement any agent UI.

The most important properties are:

• raw PTY bytes remain raw;
• terminal input reaches exactly the selected managed session;
• reconnect replays bounded output and then resumes live output without gaps;
• tokens and terminal content never enter structured tracing;
• Windows and Unix command launch remain independently correct;
• a browser disconnect never terminates a managed PTY;
• production changes do not silently replace or restart a live server;
• agent discovery is read-only and never installs or updates host software;
• workspace browsing returns directories only and never reads file content;
• each selected working directory is validated by the server before PTY launch.

Repository map

.
├── AGENTS.md                  Agent workflow and invariants
├── CLAUDE.md                  Claude-specific pointer and no-local-build rule
├── BUILDING.md                Windows/Linux build, test, and package guide
├── OPERATIONS.md              Runtime, UI, Tailscale, service, and upgrade guide
├── TODO.md                    Deliberately unimplemented, security-scoped ideas
├── README.md                  Product overview, architecture, API, and protocol
├── CONTRIBUTING.md            Contribution workflow and validation contract
├── SECURITY.md                Private vulnerability reporting policy
├── CODE_OF_CONDUCT.md         Community behavior and enforcement
├── THIRD_PARTY_NOTICES.md     Dependency licensing and attribution
├── LICENSE
├── .github/
│   ├── workflows/
│   │   ├── ci.yml             Windows/Linux continuous integration
│   │   └── release.yml        Immutable, attested Windows/Linux releases
│   └── ISSUE_TEMPLATE/        Privacy-safe issue forms
├── docs/
│   └── screenshots/           Sanitized, reproducible product screenshots
├── scripts/
│   ├── build.ps1              Windows production package
│   ├── run.ps1                Windows launcher
│   ├── build.sh               Linux production package
│   ├── run.sh                 Linux launcher
│   ├── fixtures/              Deterministic, synthetic demo PTY
│   ├── agent-catalog-regression.py
│   ├── android-ime-input-regression.py
│   ├── desktop-slash-regression.py
│   ├── mobile-codex-smoke.py  Browser/mobile smoke test
│   ├── mobile-resize-regression.py  Chrome wheel/mobile viewport regression
│   ├── peer-review-regression.py  Native PTY/helper peer workflow
│   ├── updater-supervisor-regression.py  Stable-root update/restart/rollback fixture
│   ├── generate-release-package-manifest.py  Updater package identity marker
│   ├── generate-third-party-licenses.py  Release license/NOTICE gate
│   ├── validate-release-archive.py  Bounded archive/layout/binary validation
│   ├── verify-github-release.py  Exact immutable asset/digest verification
│   ├── session-tabs-regression.py
│   └── workspace-picker-regression.py  Auth/CWD/persistence/mobile regression
├── server/
│   ├── Cargo.toml
│   ├── Cargo.lock
│   ├── examples/
│   │   └── updater-supervisor-fixture.rs  Native update/restart/rollback fixture
│   ├── src/
│   │   ├── agents.rs          Agent discovery and install-guidance catalog
│   │   ├── auth.rs            Token validation, throttling, Origin checks
│   │   ├── config.rs          CLI/environment parsing and static asset lookup
│   │   ├── filesystem.rs      Native path IDs and bounded directory browsing
│   │   ├── main.rs            Startup, listener, URLs, graceful Ctrl+C path
│   │   ├── peer.rs            Bounded peer thread/turn state and capabilities
│   │   ├── peer_cli.rs        Hidden loopback helper client
│   │   ├── peer_routes.rs     Public workflow and private bridge routes
│   │   ├── process_tree.rs    Cross-platform child-process containment
│   │   ├── protocol.rs        Browser control-message limits and parsing
│   │   ├── registry.rs        Configurable managed terminal capacity
│   │   ├── routes.rs          Protected HTTP API and static serving
│   │   ├── session.rs         PTY lifecycle, replay buffer, process management
│   │   ├── terminal.rs        Command resolution and platform-specific PTY launch
│   │   ├── update_bootstrap.rs  Stable-root worker activation and recovery
│   │   ├── update_fs.rs       Hardened updater state and filesystem operations
│   │   ├── update_manifest.rs Signed-package identity and target validation
│   │   ├── updater.rs         Release discovery, staging, and activation API
│   │   ├── websocket.rs       Authenticated attach, replay, input, live output
│   │   └── workspaces.rs      Persistent Favorites and Recent workspace state
│   └── tests/
│       ├── server_contract.rs
│       └── workspace_api.rs   Auth, browsing, persistence, and selected-CWD API
└── web/
    ├── package.json
    ├── package-lock.json
    ├── vite.config.ts
    └── src/
        ├── AgentPicker.tsx    Responsive agent discovery/start dialog
        ├── App.tsx            Main UI, sessions, settings, lifecycle actions
        ├── api.ts             Token/session storage and HTTP API client
        ├── api.token.test.ts  Token continuity and explicit-forget regression
        ├── peer/              Peer composer, state, API, and unit tests
        ├── sessions/          Header session tabs and navigation helpers
        ├── updates/           Update UI, API model, state, and unit tests
        ├── workspaces/        Folder picker, model, DTOs, and unit tests
        ├── terminal/
        │   ├── TerminalView.tsx
        │   ├── androidImeGuard.ts
        │   ├── MobileToolbar.tsx
        │   ├── mobileKeys.ts
        │   ├── mobileResize.ts
        │   ├── protocol.ts
        │   ├── reconnect.ts
        │   ├── replay.ts
        │   └── settings.ts
        └── styles/app.css