codex-cli-shared/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

Keep source under src/ with entrypoints in src/cli/ and shared helpers in src/lib/. Purpose-built agents belong in src/agents/ so they can import shared utilities without cyclic dependencies. Use tests/ for automated coverage and mirror package names (for example, tests/agents/test_sync.py for src/agents/sync.py). Configuration, schema stubs, and reusable scripts should live in config/ and scripts/. If you introduce assets for demos, drop them into examples/ and document any generated files in docs/.

Build, Test, and Development Commands

Create a virtual environment before contributing:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Run the CLI locally with python -m codex_cli --help to confirm new commands register correctly. Use make fmt to apply formatters, make lint for static analysis (wrapping ruff check and mypy), and make test to execute the full automated suite (pytest -q). Keep the Makefile in sync if you add tooling so every contributor has a single entry point.

Coding Style & Naming Conventions

Follow Black’s default 88-character line width and prefer explicit imports. Module, package, and directory names stay lowercase with underscores (data_loader.py), while classes use CapWords. Functions and variables use snake_case, and constants are UPPER_CASE. Run ruff format before committing; it enforces import ordering and docstring rules. Add type hints everywhere new public APIs are exposed and fail the build if mypy reports violations.

Testing Guidelines

Write pytest tests alongside the feature in the mirrored path and name test modules test_<feature>.py. Each scenario should assert both success and failure modes, and regression cases belong in tests/regression/. Target ≥90 % coverage for touched packages and add pytest.mark.slow to long-running cases so they can be skipped via pytest -m "not slow". When introducing asynchronous agents, include an integration test that exercises the command through the CLI entrypoint.

Commit & Pull Request Guidelines

Use Conventional Commits (feat:, fix:, docs:, chore:) so changelog generation stays deterministic. Commits should be scoped to a single concern; reorganize noisy diffs before opening a PR. Every pull request needs: a short summary, linked issue or task ID, test results (paste the command output), and screenshots or terminal captures if you change interactive flows. Request reviews from another agent maintainer and wait for CI to pass before merging via squash.

Local Codex Rules (Do Not Commit)

• Any Codex-only instructions, handover notes, context files, or local operational scratch docs are local artifacts and must never be committed or pushed to git.
• Keep Codex-only materials under local folders (for example ci-observer-handover/) outside project repos whenever possible.
• Before any commit in a project repo, verify Codex-only files are not staged.

Workspace Organization Rules

• ~/codex-cli is a workspace root. New topics must always start in a new project folder under ~/codex-cli/projects/<topic-name>/.
• Avoid loose files in workspace root. Files must be organized by project/theme folders.
• Every project folder must contain its own AGENTS.md.
• Project-level directives from conversation should be added to that project AGENTS.md (automatically when clear, or directly when user requests).
• If Codex detects a potentially useful new general rule, Codex must ask user for confirmation before adding it to this global AGENTS.md.
• At the end of each task, Codex must ask whether temporary screenshots/files can be deleted, then clean up unneeded artifacts to keep workspace tidy.

Command Formatting Rule (Global)

• When providing shell commands, always format them as a numbered list.
• Each command must be a single standalone line with no leading spaces/tabs before the command text.
• Prefer one command per list item so users can execute step-by-step safely.

Fast-Fix Triage Rule (Global)

• Scope: this rule applies to troubleshooting, incident response, and stabilization of existing systems/workflows.
• For existing systems, default to the fastest viable fix path first.
• Before proposing complex fixes, always do a strict 1:1 mismatch check between:
• workflow variables/commands
• compose or runtime service configuration
• currently running container/image/runtime state
• If a direct mismatch exists (for example credentials, DB name, host, port, container name), propose and prioritize the minimal alignment fix first.
• Do not propose plugin, network, or platform-level workarounds before the mismatch check is explicitly completed or ruled out.
• When the user asks for speed, return one primary fix path (not multiple alternatives), with minimal change scope.
• For greenfield/from-scratch work, this rule is not mandatory; prioritize design clarity, architecture fit, and implementation flow.

Session Management

• Session logs live in .codex/sessions/ as JSON files (one per session).
• Session naming: <YYYY-MM-DD>_<HHMMSS>_<project-name>.json.
• Search sessions: python3 .codex/save-session.py list <project> or .codex/search.py find <query>.
• Show latest state for a project: python3 .codex/save-session.py --latest <project>.
• Save current session: python3 .codex/save-session.py save --project <name> --model <m> --status <s> --summary "..." --decisions "a|b|c" --pending "x|y|z" --files "f1,f2".
• Generate HANDOFF.md: python3 .codex/save-session.py --handoff <project>.
• Per-project state: projects/<name>/.sessions/latest.json and projects/<name>/HANDOFF.md.
• Re-index from JSON files: python3 .codex/search.py reindex.

Cross-Model Session Continuity (CRITICAL)

THIS RULE APPLIES TO ALL MODELS (codex, deepseek, opencode).

When starting a session in any project:

1. READ projects/<project>/HANDOFF.md first — this tells you where the last session ended.
2. If HANDOFF.md exists, you MUST read it and continue from the state described.
3. Understand: what was built, key decisions made, pending tasks, files touched, Docker state.
4. If the previous session was from a different model, adapt to that model's decisions — do NOT restart or redesign.

When ending a session:

1. AUTO-SAVE the session state:

   python3 .codex/save-session.py save \
     --project <project-name> \
     --model <current-model> \
     --status complete|in-progress \
     --summary "<2-3 sentences on what was done>" \
     --decisions "decision1|decision2|..." \
     --pending "pending1|pending2|..." \
     --files "src/main.py,frontend/index.html,..." \
     --tags "tag1,tag2"
   

2. This automatically generates HANDOFF.md for the next session.
3. If you cannot run the script, at minimum update the HANDOFF.md manually.
4. AFTER saving the session, sync HANDOFF.md and updated files to the shared git repo.
5. If the shared repo is available, include the sync commands in the save-session flow.

Git Sync Policy (Every Session)

Central repo: https://git.dzonicasa.xyz/dzoni/codex-cli-shared.git

On session START (before any work):

cd ~/codex-cli-shared && git pull --ff-only 2>/dev/null || git clone https://git.dzonicasa.xyz/dzoni/codex-cli-shared.git ~/codex-cli-shared

Then read AGENTS.md, network-topology.md, and relevant HANDOFF*.md from the repo.

On session END (after saving session):

cd ~/codex-cli-shared
cp ~/codex-cli/projects/*/HANDOFF.md HANDOFF_*.md 2>/dev/null
cp ~/codex-cli/_shared/contexts/network-topology.md _shared_contexts_network-topology.md 2>/dev/null
git add -A && git commit -m "session: $(date +%Y-%m-%d_%H%M%S) — <project>" && git push

No cron, no daemons — just two git commands per session. Zero overhead when idle.

Handoff protocol (when switching models mid-project):

• Example: codex started building an API, then crashed. User opens deepseek.
• Deepseek reads HANDOFF.md → sees: "FastAPI app, 4 endpoints, SQLite, pending: add auth".
• Deepseek continues: adds auth to the same FastAPI app, preserves existing code.
• Deepseek saves new session → HANDOFF.md updated for next time.
• No "let me rewrite this differently" — respect the previous model's architectural decisions.

Per-project structure:

projects/<name>/
├── AGENTS.md              # Project rules
├── HANDOFF.md             # AUTO-GENERATED — read on session start
├── .sessions/
│   ├── latest.json        # Most recent session snapshot
│   └── <timestamp>.json   # Historical snapshots
├── src/                   # Source code
└── ...                    # Other project files

VPN & Critical Infrastructure Safety Rule (Global)

Applies to ALL models (deepseek, codex, opencode) across ALL sessions.

Critical infrastructure that MUST NOT be broken:

• Oracle VPS (130.162.209.80, hostname vpn-server): WireGuard (wg-easy), nginx-proxy, Authelia SSO
• Mini PC (192.168.0.240, hostname home-core-dev): Home Assistant, Pi-hole, WireGuard client
• WireGuard tunnel between Oracle VPS (10.8.0.1) and Mini PC (10.8.0.6)
• SSH access to both machines

Rules:

1. Any action that could disrupt WireGuard, iptables, nginx, Docker networking, SSH config, or routing MUST be presented to the user for explicit approval BEFORE execution.
2. Before making any such change, propose a specific fallback/revert plan.
3. Never wg-quick down without confirming the user has an alternative access path.
4. Never change AllowedIPs, iptables rules, SSH authorized_keys, or Docker network configs without user approval.
5. After any VPS reboot, verify and restore: WireGuard 192.168.0.0/24 AllowedIPs on wg-easy mini-pc peer, host route, nginx container route, and wg-easy MASQUERADE rule.
6. Always read _shared/contexts/network-topology.md before making network-related changes.
7. Always read projects/mini-pc-openclaw/HANDOFF.md before touching mini-pc or Oracle VPS infrastructure.

Quick-post-reboot fix checklist:

# On Oracle VPS:
WG_IP=$(docker inspect wg-easy --format '{{.NetworkSettings.Networks.vpn_default.IPAddress}}')
docker exec wg-easy wg set wg0 peer xekIYyq18hcW9vP3LoRbMG/w0q4UcxX1c0cK96NJFQA= allowed-ips 10.8.0.6/32,192.168.0.0/24
docker exec wg-easy ip route add 192.168.0.0/24 dev wg0 2>/dev/null || true
docker exec wg-easy iptables -t nat -C POSTROUTING -o wg0 -j MASQUERADE 2>/dev/null || docker exec wg-easy iptables -t nat -A POSTROUTING -o wg0 -j MASQUERADE
ip route replace 192.168.0.0/24 via $WG_IP
docker exec nginx-proxy ip route replace 192.168.0.0/24 via $WG_IP

Model-Specific Rules

deepseek-v4-pro (DeepSeek)

• Full read access to ~/codex-cli workspace.
• Cannot view images — user must save screenshot to file and describe, or use OCR.
• Preferred stack: Python/FastAPI, Vanilla JS, Docker Compose, SQLite.
• Config: .codex/models/deepseek.yml.

codex (Default / OpenAI / Anthropic)

• Full read-write access to ~/codex-cli workspace.
• Can view images if model supports vision.
• Preferred stack: Python, React/NextJS, Docker, PostgreSQL.
• Config: .codex/models/codex.yml.

Shared Context

• Reusable context (hardware specs, network config, credentials schema) should go in _shared/contexts/.
• Example: _shared/contexts/home-core-dev-specs.md for the mini PC hardware.