Codex Agent

English | Korean

Give Codex a memory. Keep the engine.

Codex Agent is an open-source continuity layer that turns Codex into a persistent, project-aware agent without replacing Codex itself.

Codex already knows how to write code, run commands, use skills and plugins, work with connected tools, and—where available—see and operate desktop apps through Computer Use. Codex Agent adds the part that is easy to lose between tasks and computers: a stable operating identity, your preferences, project decisions, hard-won lessons, and a clear record of where the last task stopped.

Every new task still runs in Codex. Continuity is reconstructed from explicit files you can inspect, edit, and remove—not from a hidden agent process or an opaque memory database.

Why this exists

Persistent agents are compelling for more than the quality of a single answer. They learn how you prefer to work. They remember why a decision was made. They carry unfinished work forward. Over time, they feel less like a blank chat and more like a capable collaborator that knows the project.

If what attracts you to projects such as OpenClaw or Hermes Agent is the promise of a persistent assistant that remembers you and acts across everyday tools, Codex Agent brings that idea to Codex.

You should not need to adopt a separate agent stack just to get that continuity if Codex is already the engine you want to use.

Codex Agent keeps the intelligence, tools, and safety model of Codex, then adds a private memory system around it. The result is a Codex workspace that can develop a consistent working style, preserve reviewed knowledge, and resume cleanly on another computer.

Why build on Codex?

• Keep the Codex harness. Continue using the Codex app, CLI, or IDE extension together with its shell, sandbox, approval flow, tools, skills, and plugins. Codex Agent configures Codex; it does not fork or imitate it.
• Use Computer Use directly. In supported Codex environments, Codex can see, click, type, and navigate desktop apps. Codex Agent does not rebuild that capability—it gives Codex durable project context while Codex uses it.
• Put recurring work on a schedule. Codex Scheduled tasks provide a cron-like layer for daily briefs, periodic project checks, long-running follow-ups, and skill-driven routines. Point one at the Codex Agent project and the scheduled run can use the same repository guidance, skills, and memory workflow.
• Let OpenAI improve the engine. Because this project stays a thin layer over Codex, improvements to models, tools, sandboxing, skills, plugins, and product surfaces do not need to be reimplemented here. Compatibility with every future change is not guaranteed, but the architecture is designed to adopt Codex improvements rather than compete with them.
• Own the memory. The agent's operating principles and project memory are ordinary Markdown files in a private Obsidian vault. You can read them, revise them, back them up, or delete them.
• Spend context on the task, not the archive. Codex Agent injects a compact approved startup brief and retrieves detailed memory only when the task needs it. It does not replay the vault by default.
• Continue across computers. Connect another checkout to the same synchronized project vault, and Codex can reconstruct the same reviewed context instead of starting from zero.
• Open the system, not your private mind. The workflow, skill, scripts, and templates can live in a public repository while the real soul, preferences, history, and handoffs stay private.

Computer Use and other Codex capabilities depend on your Codex version, operating system, account, region, installed plugins, and workspace policy.

From code to everyday work

Codex for work expands the reason to build on Codex. OpenAI now positions Codex not only for software development, but also for researching, synthesizing, and automating everyday work with the tools a person or team already uses.

With the appropriate plugins, connected apps, permissions, and source material, Codex can help with work such as:

• preparing a morning brief from calendars, messages, email, notes, and open follow-ups
• turning scattered source material into reports, decision memos, presentations, and spreadsheets
• preparing for meetings and drafting follow-ups in the user's preferred style
• reviewing recurring updates and producing weekly summaries
• using Computer Use when a workflow exists only inside a desktop interface
• running cron-like scheduled tasks for morning briefs, recurring monitors, follow-up loops, and periodic reviews

Codex Agent makes those workflows more personal and more continuous. The same reviewed soul, preferences, project knowledge, and lessons can guide Codex whether the task is changing code, preparing a deck, organizing the day, operating a desktop app, or picking up a long-running project.

Scheduled work is where that continuity becomes especially useful. A task can wake up on a cadence, enter the same project, use its checked-in skills, restore the context it needs, and leave the result for review. It is the familiar utility of a cron job, but with a memory-aware Codex agent doing the work instead of a fixed shell command.

For scheduled tasks that need local project files, keep the computer powered on, the ChatGPT desktop app running, and the project available on disk. Scheduled runs are unattended, so use narrow permissions and avoid overlapping tasks that write to the same private vault.

The aim is not to bolt a second general-purpose agent beside Codex. It is to make Codex itself the agent you can keep using for both technical and everyday work.

What becomes persistent

Layer	What it preserves
Soul	The agent's operating principles, working style, and boundaries
Preferences	How you want work approached, communicated, and verified
Project memory	Important facts, decisions, constraints, and their provenance
Selected originals	User-approved, modest-size source documents whose exact form matters across computers
Device memory	Local paths, tools, OS details, and constraints that apply only to one machine
Reviewed improvement	Reusable observations promoted through candidate → evidence → user approval → approved lesson
Handoff	What was completed, what remains unresolved, and the next concrete actions

Persistent does not mean always loaded. Candidates, sessions, preserved originals, superseded records, archives, and other detailed evidence stay outside automatic startup context.

Temporary delivery outbox

Generated files are not memory. Codex Agent uses the ignored output/ directory only as a temporary outbox for files being handed to the user. artifactctl deliver creates a managed package with a seven-day expiry, and both the trusted SessionStart hook and an hourly device-local scheduler run artifactctl sweep. Expired packages are permanently deleted rather than moved to an archive or recycle bin. If the computer is off when a package expires, cleanup catches up at the next hourly run or trusted session start.

python scripts/artifactctl.py deliver --slug quarterly-report ./tmp/report.pdf
python scripts/artifactctl.py inspect ./output/<package>/report.pdf

The seven-day lifetime is fixed and cannot be extended by the delivery command. The response must include the absolute path and exact expires_at time. There is no keep marker or permanent library inside output/; after the empty outbox has been activated, even files written there without a delivery manifest are enrolled for deletion seven days after first discovery. When only the learning matters, Codex records the smallest justified memory. When the exact file matters, it inspects the file and proposes a specific 40-documents/ destination with size, reason, digest, and privacy review. Nothing is preserved until the user explicitly approves that file and destination, and the delivery copy still expires on schedule.

Activation is deliberately fail-closed for upgrades. If output/ already contains pre-policy files, install-sweeper and sweep refuse to enroll them. Review and move that exact legacy directory outside the repository before installing the scheduler; this prevents an upgrade from silently starting a deletion clock on old artifacts.

How it works

flowchart LR
  G["Public Codex Agent repository<br/>protocol · skill · tools · templates"] --> A["Computer A<br/>Codex + project checkout"]
  G --> B["Computer B<br/>Codex + project checkout"]
  A --> V["Private Google Drive / Obsidian vault<br/>shared memory · selected originals · per-device folders · handoffs"]
  B --> V

Loading

Git carries the public behavior protocol and a reviewed lifecycle hook. Google Drive carries the private memory. At the start of a trusted local task, the hook validates the connection and adds only a compact approved brief to Codex; AGENTS.md remains the safe public fallback. A normal SessionStart brief contains compact Soul, project, and preference sections plus current-device and current-handoff sections when available. SubagentStart uses the smaller project profile plus available current-device/current-handoff sections. The loader validates the full vault index and memory policy locally for size and secret patterns, but their bodies are rendered only when a memory operation needs them.

The design target is about 2,000 tokens or less. The automatic renderer mechanically enforces event-specific byte ceilings of 12 KiB for SessionStart and 8 KiB for SubagentStart; these are safety ceilings, not targets to fill. The operating protocol additionally requires agents to keep total model-visible private memory within 24 KiB for a main task and 16 KiB for each subagent. Its warm-retrieval allowances of 12 KiB and 8 KiB, normally zero to three approved notes, are behavioral limits because task-specific retrieval has no single metered CLI path.

The separate read-only budget command helps keep persistence from turning into unreviewed accumulation. By default it warns from 80% of a 1 MiB/250-file working set, a 100 MiB/1,000-file whole vault, or a 16 KiB individual working-set file. The working set covers 00-system, 10-project, 20-state, 30-memory, and 50-devices; documents and archives are cold but still count toward the whole-vault total. Successful reports contain aggregate metadata, not private filenames or note bodies, and never delete, truncate, rewrite, move, or archive anything.

This does not transfer a running agent, hidden reasoning, credentials, open applications, or unsaved local state. It reconstructs behavioral continuity from reviewable files. Keep source code in Git and private memory in Google Drive; do not place the development checkout itself inside the synchronized vault.

Requirements

• Git
• A local Work or Codex task with access to the cloned folder and its repository skills; the Codex app, CLI, and IDE extension can use this workflow
• A fully local synchronized folder such as Google Drive, Dropbox, OneDrive, iCloud Drive, or Syncthing
• Python 3 for automatic startup injection and the preferred cross-platform lifecycle runner; PowerShell remains a manual Windows-compatible lifecycle fallback
• Obsidian, if you want a human-friendly interface for reviewing and editing the Markdown vault

Google Drive Mirror files is the preferred mode. If you use Stream mode, mark the entire vault Available offline and wait for synchronization to finish before opening it. See Google Drive setup.

The project folder is the agent's home

One project folder. Many chats. One continuous working memory.

Clone Codex Agent, open the cloned folder as a local Work or Codex project, and start your chats beneath codex-agent in the sidebar. That project folder is the agent's stable home.

Every local task started there receives the same checked-in AGENTS.md and can discover $codex-agent-init and $portable-agent-memory. Once init has connected the computer and you have trusted the reviewed project hook, SessionStart injects the compact session brief before Codex begins the task. SubagentStart gives spawned agents the smaller project brief plus available current-device/current-handoff sections instead of repeating the full session profile.

In everyday use, this feels like returning to the same memory-aware agent:

1. Open the codex-agent project.
2. Start a new chat beneath it.
3. Ask for work in ordinary language.
4. The trusted startup hook restores the approved hot context; Codex retrieves additional task-specific memory only when needed.

Initialization and hook trust are normally once-per-computer steps. After both are complete, you do not need a special memory prompt for every local task. Codex asks you to review the hook again if its definition changes.

This is behavioral continuity reconstructed from reviewable files, not one model process running forever. A chat outside this project does not automatically inherit the repository instructions or its private vault, and unrecorded chat details are not durable memory.

Set up in one conversation

OpenAI uses Codex for work for the broader everyday-work offering. For this repository, open the clone in a local Work or Codex task—shown as Work locally in the app—so the agent can read the repository and use its checked-in skills. A generic or cloud-only chat without access to the local folder cannot initialize it.

git clone https://github.com/jugol/codex-agent.git codex-agent
cd codex-agent

Then:

1. Open codex-agent as a local project in Work or Codex.
2. Start a new local task.
3. Enter:

$codex-agent-init Set up Codex Agent for this project.

Choose your onboarding style. Run the skill in Plan mode if you want click-to-choose question cards. In Default mode, the skill asks the same personalization questions as a short free-form conversation. Both paths create the same private vault and memory files; Plan mode is optional.

The repo-scoped init skill will:

• detect the operating system and choose the Python or PowerShell lifecycle tool
• infer a safe project ID and look for common local sync locations
• explain any choice it actually needs from you instead of asking for script parameters
• show the planned public and private paths before writing
• create or reconnect the private project vault without overwriting existing memory
• create or preserve this computer's isolated device profile without adopting another device's local facts
• validate the link, manifest, privacy markers, and bounded startup context
• verify the hash-pinned SessionStart and SubagentStart hook and guide you through Codex's one-time hook review
• install the hourly device-local sweeper for the seven-day temporary delivery outbox
• offer to draft the project profile, soul, and preferences for your approval

The setup creates a stable random agent profile ID in the private manifest. Each computer adopts that shared profile while receiving its own device ID. The linked files remain outside the Git checkout and are not publication candidates.

Day-to-day use

After initialization, open the project and work normally. The trusted SessionStart hook loads the reviewed compact session brief and catches up expired delivery cleanup before work begins. The independent hourly local scheduler enforces expiry without spending a model turn. AGENTS.md supplies a publishable fallback, trust order, temporary-delivery rules, and the rules for task-specific retrieval and safe handoffs. The repo-scoped $portable-agent-memory handles diagnostics, targeted memory, and justified writes.

Start each new task beneath the same project in the Codex sidebar and ask for work normally. You do not need to type $portable-agent-memory or run lifecycle commands yourself. If the hook is unavailable or untrusted, Codex falls back to AGENTS.md and must not pretend that a private Soul was loaded.

Memory writes are signal-based. An ordinary completed task does not automatically create a session, candidate, handoff, or preserved original. Codex writes one only when a later task needs resumable state, a sanitized audit trail is materially useful, a precise reusable memory proposal exists, or the user explicitly approves preserving an original.

Surface	Automatic private-memory restoration
Trusted local checkout	Yes, through SessionStart
Codex linked worktree	Yes; the lifecycle tool reuses one compatible connection from the Git worktree family
Another computer	Yes, after running init and trusting the hook on that computer
Hook disabled, changed, or untrusted	No; public AGENTS.md fallback remains active
Generic chat, cloud-only task, or workspace without the local vault	No

The lease reduces accidental concurrent writes, but it is not a distributed lock or security boundary. Codex cannot reliably discover every active computer from Google Drive state: lock=none means no lease is visible here, not that another writer is definitely inactive. Read-only tasks may overlap, but keep only one writable Codex task active for each project-vault folder.

Soul changes are not permanently blocked. Codex should warn about a possible unsynchronized writer, obtain exact approval for the proposed content, and ask you to confirm that other vault-writing tasks are stopped and Drive is up to date—or explicitly accept the concurrency risk. It may then acquire the advisory lease and make the approved change.

Local documents are never collected or uploaded automatically. When a document is important to long-term continuity, modest in size, and the original itself matters, Codex may propose preserving it in the private vault's 40-documents/ folder. Before copying anything, it must identify the exact file, size, reason, destination, and privacy implications and receive your explicit approval. Preserved originals remain cold context: Codex opens them only when a task needs them.

Shared memory and device memory are kept separate. Project-wide facts, decisions, preferences, lessons, originals, and handoffs remain in the common vault areas. Setup gives each computer an opaque device ID and its own 50-devices/<device-id>/ folder for safe local paths, operating-system details, installed tools, local applications, and hardware constraints. Only a safely projectable compact section from the current device's DEVICE.md may enter startup context; other device folders remain synchronized but are never applied automatically.

Device scoping is about applicability, not confidentiality. Every computer or person with access to the Drive vault can still read those folders. Credentials, cookies, login state, secret values, caches, and other native runtime state must stay outside the vault.

Continue on another computer

1. Finish the task on computer A and wait until the synchronized vault reports Up to date.
2. On computer B, clone the same repository and wait until the private vault is fully available locally.
3. Open the clone as a local Codex project.
4. Run $codex-agent-init again. It scans the immediate project manifests in the selected private vault and helps you reconnect the right one instead of replacing it.

The absolute sync path and device ID may differ between computers. The project ID, agent profile ID, and shared memory remain the same, while each computer restores only its own device-scoped profile.

Advanced: run lifecycle commands manually

Choose one runner and use it consistently in the current task:

# macOS / Linux
python3 scripts/agent-memory.py <command>

# Windows
./scripts/agent-memory.ps1 <command>

When Python is available but the lifecycle hook did not inject memory, render the same bounded session profile without invoking the hook:

python scripts/agent-startup-context.py --render --event SessionStart

Command	Purpose
setup	Initialize missing vault files and create the machine-local connection
doctor	Validate configuration, link target, manifest, markers, required structure, and working-set budget metadata
context	Print the eligible canonical source-path manifest and newest valid status: current handoff; it does not print note bodies or inventory the whole vault
budget	Report aggregate working-set and whole-vault byte/file usage without private filenames or note bodies
begin	Acquire a project-scoped advisory lease and return its lease ID
new-session	Create a structured private session note
new-handoff	Create a private handoff draft
new-candidate	Create a proposed durable-memory note
end	Archive and release the exact advisory lease

Use --help with the Python command or -Help with the PowerShell command for details. Python uses --lease-id; PowerShell uses -LeaseId.

budget is advisory by default. Python supports --json, --strict, --working-set-max-bytes, --working-set-max-files, --total-max-bytes, --total-max-files, and --single-working-file-max-bytes. PowerShell provides the matching -Json, -Strict, -WorkingSetMaxBytes, -WorkingSetMaxFiles, -TotalMaxBytes, -TotalMaxFiles, and -SingleWorkingFileMaxBytes. Overrides are useful for diagnostics and tests; they do not redefine the repository's durable defaults. Strict mode returns a nonzero status for a warning, exceeded limit, or incomplete scan. doctor checks only working-set metadata, stops at a review threshold or hard traversal cap, and warns without failing; explicit budget remains the exhaustive report for cold and whole-vault storage.

Public and private boundaries

Public Git repository	Private synchronized vault
AGENTS.md protocol	SOUL.md and durable preferences
Reviewed startup hook and hash-pinned loader	Approved hot-context contents
Repo-scoped skill	Project-specific facts and decisions
Setup and diagnostic tools	Approved lessons and memory candidates
Generic placeholder templates	Session notes and completed handoffs
Preserved-document policy	Explicitly approved original documents
Device-memory protocol and generic template	One private folder per configured device ID
Security and synchronization documentation	Sanitized project history and provenance

Every rendered private record carries a machine-detectable publication marker. The publication check rejects that marker even if a private note is renamed or copied elsewhere in the checkout.

Never store credentials, tokens, private keys, cookies, or raw secret values in either memory layer. Store secret values in an OS credential manager or approved secret manager; memory should contain only the variable or secret name needed to retrieve them.

Checks before publication

python ./tests/smoke.py
pwsh -NoProfile -File ./tests/smoke.ps1
pwsh -NoProfile -File ./tests/interop.ps1
pwsh -NoProfile -File ./tests/prepublish-smoke.ps1
pwsh -NoProfile -File ./scripts/prepublish-check.ps1

These publication-maintainer checks currently require PowerShell 7 (pwsh) in addition to Python. End-user initialization and normal memory operation do not require PowerShell when Python 3 is available.

Run the publication check again after the final git add and immediately before a public commit or push. Once the repository has an index or HEAD, the check fails closed if a boundary-critical file is staged for deletion.

The check inspects the current Git index and working tree without traversing .agent-vault. It detects private-record markers, protected paths, unsafe links, weakened ignore rules, selected credential formats, and removal of the bootstrap and safety files.

This is a guardrail, not a complete data-loss-prevention system. It does not inspect every historical commit or recognize every possible secret format. Before the first public push, review the full reachable history with an approved, history-aware secret scanner. Rotate any credential that has ever entered Git or Drive history; deleting the current file is not sufficient.

How Codex Agent integrates with Codex

Codex Agent is not a fork, wrapper, or separate background agent runtime. It is a checked-in configuration, lifecycle hook, and memory protocol for Codex. Codex reads project guidance from AGENTS.md, discovers repository skills under .agents/skills, and—after review and trust—can add context from project SessionStart and SubagentStart hooks. Codex's native local memory is generated state under the Codex home directory, so this project treats it as optional recall rather than durable project memory.

• Codex by OpenAI
• Codex for work
• OpenAI Academy: everyday work with Codex
• Codex: Scheduled tasks
• Codex: Computer Use
• Codex: custom instructions with AGENTS.md
• Codex: lifecycle hooks
• Codex: build and locate skills
• Codex: build plugins
• Codex: local memories

The Google Drive connector/plugin is optional. It can help Codex search Drive content, but it does not replace a locally mirrored or offline folder for Obsidian and filesystem-based project memory.

Guarantees and limitations

This design carries reviewed operating principles, project context, decisions, lessons, and handoffs between computers. It cannot transfer a running process, hidden reasoning, open tabs, unsaved files, local authentication, connector authorization, or native Codex state. Automatic restoration requires a trusted local project hook, Python 3, and an available local vault. It also cannot guarantee identical outputs across models, tool versions, or environments.

Do not synchronize CODEX_HOME or ~/.codex. Each computer should maintain its own Codex installation, authentication, and native state.

Documentation

• Design
• Google Drive setup
• Security and trust boundaries

License

MIT

Codex Agent is an independent open-source project built for Codex. It is not an official OpenAI product and is not affiliated with or endorsed by OpenAI.