Your outcome
A working home base
By the end, you will have a scoped WorkspaceOS, one useful workstation, a verification result, and a clear maintenance habit.
A self-guided setup for durable instructions, scoped context, your voice, and reusable workflows — in about 25 minutes.
By the end, you will have a scoped WorkspaceOS, one useful workstation, a verification result, and a clear maintenance habit.
Use Overview to jump anywhere, Read for a scrollable guide, and Fullscreen when presenting.
The same WorkspaceOS idea can travel across Chat, Work and Codex — the setup path changes.
Codex can still help, but it does not automatically know your role, your folders, your writing preferences, or where you want outputs saved. You spend the first few minutes re-explaining the same setup.
Generic tone. No durable file memory. No routing. Repeat yourself constantly.
Codex automatically discovers applicable AGENTS.md guidance. That guidance tells it when to read scoped context, which workstation should handle the task, and where outputs belong.
Your voice. Your context. Outputs in the right place. Faster start every time.
WorkspaceOS is just a folder on your computer. Plain files, no lock-in, easy to inspect.
Think of each workstation as a focused task lane. Workspace-root guidance applies across the project; nested instructions and context are read only when the task routes there.
The workspace operating agreement. It tells Codex your rules, folder structure, routing map, safety boundaries, and what to read before doing work.
Curated, inspectable context. It stores current decisions and facts you deliberately want future tasks to read. It is separate from native Memories.
Your writing voice. Tone, sentence style, words to avoid, signature phrases. Codex reads this before writing any content on your behalf.
.agents/skills/, resources, workstations and outputs.In about 25 minutes, you will create the smallest useful system, verify it, and finish one real task.
In Codex, open the empty WorkspaceOS folder. In ChatGPT Work, create a local project and make that folder primary. Paste this prompt and review the proposed structure.
I'm setting up WorkspaceOS for the first time. Please
create the following in my WorkspaceOS root folder:
1. AGENTS.md — with these sections:
Context System, Context Routing, Preferences, Data Boundary,
Rules, Folder Structure, Routing Map, Creating Workstations,
Verification and Maintenance
2. CONTEXT.md — with these sections:
About Me, Active Projects, Key Contacts,
Key Decisions, Useful Context, Review Date
3. 00_Resources/voice-principles.md — with these
sections: Tone, Sentence Style, Words and Phrases to Avoid,
Words and Phrases I Use, Formatting Defaults
4. .agents/skills/ (repo-scoped discoverable skills)
5. schedule-specs/ (task specifications only; this folder
does not create a real schedule)
6. governance/ (data-boundaries.md and permissions.md)
7. evals/ (acceptance-tests.md)
8. workstations/ (focused task lanes)
9. outputs/ (finished artefacts)
Context routing requirement:
- Root CONTEXT.md is only for workspace-wide preferences,
routing, or project-wide context.
- Workstation-specific lessons, contacts, decisions, examples,
output preferences, and recurring quirks go only in that
workstation's CONTEXT.md.
- Write to both only when the context genuinely has both global
and workstation-specific value. Do not duplicate the same note.
- Do not store secrets, credentials, regulated data, or restricted
company information in context files.
Use starter templates with [bracketed placeholders]
where I need to customise. Before writing, show me the proposed
tree and ask me to confirm the trust domain. After creating it,
ask 3 questions to personalise AGENTS.md and CONTEXT.md.
That prompt created the smallest useful WorkspaceOS skeleton: instructions, curated context, reusable workflow locations, governance, verification and outputs.
The next slides explain what is native to Codex, what is your file convention, and how to verify both. Customise the bits in [brackets].
This file is Codex's operating agreement for the workspace. It governs tone, behaviour, folder structure, routing, and maintenance habits.
# AGENTS.md # WorkspaceOS WorkspaceOS is a clean local workspace for OpenAI-stack agents. It gives ChatGPT Work and Codex a durable project home, a small context system, focused workstations, and helper scripts. ## Context System Read root CONTEXT.md when the task needs workspace-wide context. If a task routes to a workstation, also read that workstation's CONTEXT.md before working. When I say "save this context", use the narrowest useful context file and confirm where it was saved. Never save secrets or restricted data. ## Context Routing Use this routing rule whenever saving context: 1. Root CONTEXT.md is only for workspace-wide preferences, cross-workspace decisions, routing changes, project-wide status, and context that should apply regardless of workstation. 2. Workstation CONTEXT.md is for domain-specific context: contacts, decisions, examples, recurring quirks, output preferences, and lessons that only matter inside that workstation. 3. Write to both only when the context genuinely has both global and workstation-specific value. Use different wording for each file; do not duplicate the same note. 4. If unsure, state which context file you think fits best and ask for confirmation before saving. ## Preferences - Use [Australian English / your preferred English]. - Keep responses concise by default. - Give one strong recommendation unless I ask for alternatives. - Default to async communication. - Before producing written content on my behalf, read 00_Resources/voice-principles.md. ## OpenAI Stack - Support both ChatGPT Work and Codex; use the surface appropriate to the task. - Use AGENTS.md files for agent instructions. - Prefer OpenAI Responses API or Agents SDK concepts when building agentic workflows. - Keep API-backed code optional and environment-driven. - Never hard-code API keys. ## Rules - Read local context before making broad changes. - If a task routes to a workstation, read that workstation's AGENTS.md and CONTEXT.md before working. - Never drop deliverables directly into the root unless they are system files. - Preserve unrelated user edits. - For external or current OpenAI behaviour, verify against official OpenAI docs. ## Routing Map | Workstation | Route here when I... | | :-- | :-- | | Bob the Builder | need to build something that runs. | | Presso-BRG | need to create, update, critique, or polish a deck. |
Keep only current facts and decisions that materially improve future work. This file convention is separate from optional native Memories.
# WorkspaceOS Context Last updated: [YYYY-MM-DD] ## About Me - User: [Your name] - Location context: [City, country, timezone] - Primary work context: [Role / team / projects] - Working style: [Concise, async-first, pragmatic, etc.] ## Active Projects | Project | Status | Notes | | :-- | :-- | :-- | | [Project] | [Active / Paused] | [Useful context] | ## Key Contacts | Name | Role | Why they matter | | :-- | :-- | :-- | | [Name] | [Role] | [Context] | ## Key Decisions - [YYYY-MM-DD] Decision: [what changed and why]. ## Useful Context - [Anything future tasks should know. Include source and date.] ## Review Date - Review this file on: [YYYY-MM-DD]
When a task routes to a workstation, context should not automatically go to the root. Save it where future work will actually need it.
Use root context only for information that should apply across this workspace.
Use workstation context for information that only matters inside that task lane.
Paste 5–8 of your own emails or Slack messages and ask Codex to extract patterns from them. It'll fill in the signature phrases and tone sections automatically.
# Voice Principles ## Tone - [Warm, direct, casual, formal, technical, etc.] - [How much personality or humour is appropriate.] - [How direct or soft asks should be.] ## Sentence Style - [Short paragraphs, mixed sentence lengths, direct asks.] - [Preferred punctuation and formatting habits.] - [Australian English / US English / other.] ## Words and Phrases to Avoid - [Phrases you dislike.] - [Jargon, corporate filler, or terms that sound unlike you.] ## Words and Phrases I Use - [Signature phrases.] - [Preferred sign-offs, asks, transitions, and shorthand.] ## Formatting Defaults - Short paragraphs (1–2 sentences max) - Bold sparingly — key terms and names only - [Other formatting preferences]
A workstation is one focused task lane with its own rules, context, resources and outputs. Start with the recurring task that costs you the most time.
Pick one recurring job with a visible finish line. Your first workstation should be narrow enough to test today.
You make the same kind of output every week and already know what “good” looks like.
You repeatedly gather similar sources, compare evidence and produce a recommendation.
“Help with marketing,” “do my admin,” or “anything for this client” is too broad for a first test.
A workstation is just a folder with four things. The sections inside its AGENTS.md define how Codex behaves when work routes there.
One paragraph. What this workstation handles, what does not belong here, and what good output looks like.
A table mapping reference files to "read when" conditions. Codex only loads these files when the trigger is met, keeping context efficient.
Numbered steps for the primary task in this workstation. Keep it simple — 5–7 steps. Refine it as you see what Codex gets right and wrong.
Start with "Follow voice-principles.md in 00_Resources." Then add domain-specific rules, formats, naming conventions, and output expectations.
Pick one recurring task type — emails, slide decks, Jira tickets, whatever takes up your time. Fill in the two brackets, paste, and Codex scaffolds the whole workstation.
Create a new workstation called "[Workstation Name]".
Route here when I: [describe the task type clearly]
Create these four items inside the workstation folder:
1. [Name]/AGENTS.md with sections:
- Identity (one paragraph: what routes here,
what doesn't)
- Resources (empty table: Resource | Read when...)
- Workflow (numbered steps for the main task)
- Editorial Rules (start with voice-principles.md
reference, then add domain-specific rules)
Include this context rule in the workstation AGENTS.md:
When saved context is specific to this workstation's
domain, save it in [Name]/CONTEXT.md, not root CONTEXT.md.
2. [Name]/CONTEXT.md with:
- Contacts section
- Key Decisions section
- Useful Context section
- Review Date section
3. [Name]/[Name] Resources/ (empty folder)
4. [Name]/Outputs/ (empty folder)
After creating the files, add a new row to the
Routing Map in root AGENTS.md.Run the prompt with a harmless example. The agent should name the workstation, identify the instruction and context files it used, and save the artefact in that workstation’s outputs folder.
Test my WorkspaceOS routing with a harmless example. Task: [one realistic request for this workstation] Before working: 1. State which workstation should handle the task and why. 2. List the instruction and context files you will use. 3. State the exact output path. Then create the smallest useful draft. Do not publish, send, or connect to an external service. Afterward, report: - the files you read; - the file you created; - any assumption that still needs my confirmation; - whether this test passed the routing rules.
Confirm the file is named exactly AGENTS.md, saved inside the active project tree, and that you opened the intended root folder.
Rewrite the routing trigger as an observable request: “create, edit or critique a slide deck,” not “presentation things.”
Move the note to the narrowest CONTEXT.md, add a review date, and remove duplicates from the root.
Add an explicit output-path rule to the workstation AGENTS.md, then rerun the acceptance test.
Use the desktop app, create a local project, and make the WorkspaceOS folder primary. Workspace policy may limit features.
Availability can vary by account and workspace policy. Continue with the available default or ask your administrator.
Workspace-level guidance applies across the project. Workstation instructions and context are loaded only when the task routes to that lane.
The system only gets smarter if you save what you learn. One 30-second prompt at the end of each session — that's all it takes to turn WorkspaceOS from a config file into something that actually grows with you.
Ask the agent to extract only reusable decisions, preferences and lessons, then route them to the narrowest useful scope.
Workspace context applies broadly. Workstation context applies only inside that lane.
Scan this conversation for any unsaved preferences, decisions, or useful context. Use context routing: - Write personal, global, cross-workspace, routing, or project-wide context to root CONTEXT.md. - Write workstation-specific contacts, decisions, examples, output preferences, recurring quirks, and lessons to the active workstation's CONTEXT.md. - Write to both only when the context genuinely has both scopes. Do not duplicate the same note in both places. - Never save secrets, credentials, regulated information, or restricted company data. Add new notes to existing sections where relevant and create new sections only when needed. Focus only on what is genuinely new from this session.
Pick one task you repeat every week. That's your first workstation.
WorkspaceOS compounds when instructions and context improve through real use. Start small — one root, one workstation, one verified output — and add complexity only when it earns its place.
Tip: keep the base setup local and inspectable before adding APIs or automations.
Stores a human-readable task definition: purpose, prompt, cadence, inputs, owner and expected output.
Stores repo-scoped skills that ChatGPT and Codex can discover when the skill description matches the task.
Create and manage the actual recurring task in ChatGPT Work. Confirm owner, cadence, permissions and delivery location.
Keep your master AGENTS.md focused. Point to resource files rather than stuffing everything into one place — this keeps baseline context lean every session.
Never repeat global rules inside local workstations. If the root already says "use Australian English," a workstation should only add stricter local rules.
The base setup should work with plain files. Use Responses API, Agents SDK, MCP, plugins, or automations only when a real workflow needs them.
Local first. Inspectable first. Extend later.
Start with the default model and reasoning effort. Move only when the task earns it.
Efficient volume. Use it once the task has a clear quality bar.
Start here. It is the practical balance for most new workflows.
Use deliberately. Step up when Terra’s quality is not enough for the job.
Reserve for the hard jobs. Use Ultra effort only when multiple independent tasks benefit from parallel work.
How Work uses files, apps, tools and local projects to produce reviewable outputs.
Review project instructions, local folders, and shared ChatGPT/Codex skill conventions.
Use the models shown in your account. Check the official reference before teaching or standardising a model choice.
Choose any page. Press Esc to return.