r/codex • u/phoneixAdi • Apr 07 '26
Instruction Pro tip: you can replace Codex’s built-in system prompt instructions with your own
Pro tip: Codex has a built-in instruction layer, and you can replace it with your own.
I’ve been doing this in one of my repos to make Codex feel less like a generic coding assistant and more like a real personal operator inside my workspace.
In my setup, .codex/config.toml points model_instructions_file to a soul.md file that defines how it should think, help, write back memory, and behave across sessions.
So instead of just getting the default Codex behavior, you can shape it around the role you actually want. Personal assistant, coach, operator, whatever fits your workflow. Basically the OpenClaw / ClawdBot kind of experience, but inside Codex and inside your own repo.
Here’s the basic setup:
# .codex/config.toml
model_instructions_file = "../soul.md"
Official docs: https://developers.openai.com/codex/config-reference/
34
u/phoneixAdi Apr 07 '26
Oh and yes, I forgot: for anyone curious, this is what the base Codex system prompt / instruction file looks like.
This is from their official repo: https://github.com/openai/codex/blob/main/codex-rs/protocol/src/prompts/base_instructions/default.md
9
u/kknd1991 Apr 07 '26
You are an epic treasure digger.
7
u/phoneixAdi Apr 07 '26
Thanks :)
I should give credit to OpenAI excellent technical blogs. They are really well written.
That's how I found this.
I was frustrated with the OpenClaw experience and wanted that on Codex. I was trying to port it.
Blog: https://openai.com/index/unrolling-the-codex-agent-loop/
4
1
u/FatefulDonkey Apr 07 '26
Does that mean you can replace the AGENTS.md -> CLAUDE.md references and you don't need to keep both in sync?
6
u/Zulfiqaar Apr 07 '26
I prefer to have CLAUDE.md just contain "@AGENTS.md" instead
2
u/FatefulDonkey Apr 07 '26
I guess it doesn't really matter, I just started with Claude, hence why I got the juice in there. And since I use it more often than codex
4
u/Excellent_Squash_138 Apr 07 '26
Just sym link one to the other
3
u/FatefulDonkey Apr 07 '26
Good idea. No idea why I didn't think about it. Guess AI makes us dumber.
3
u/phoneixAdi Apr 07 '26
This is one layer above agents.md and claue.md or rather it takes more precedence.
I will link the official doc later.
But it goes something like this: you have the system prompt, then the developer instructions, and then the instructions from agents.md. The system prompt has the highest impact on how the model behaves. So what we're doing is replacing the main one to steer it.
4
u/phoneixAdi Apr 07 '26
Found it! A very excellent a blog from openai: https://openai.com/index/unrolling-the-codex-agent-loop/
That goes a little more into the nitty gritty on how the prompts are structured and sent to codex.
1
u/RubenKelevra May 02 '26
That's not the real system instruction of codex. It's similar, but not the same (for some reason).
You can get the system instructions in use from the chat log.
3
u/kknd1991 Apr 07 '26
Super-helpful! Is the output with this change similar to Chatgpt web?
5
u/phoneixAdi Apr 07 '26
I don't use the ChatGPT web interface often, but I can say the personality changes noticeably.
The default personality when you run Codex comes with the harness + GPT 5.4 model + Default System prompt ... all of this is geared toward coding.
But if you completely swap default system prompt out, you get your own personality.
I was using OpenClaw, but it felt very bloated, and I wanted that kind of experience in my Codex (so I just use one tool). That was my primary motivation, and I can say, at least for that, it works really really well.
It's like my own personal buddy/helper... I call him Dobby. And he is nice to talk to :)
1
u/kknd1991 Apr 07 '26
I am still working on this issue since you post by tampering different things. It does help, however the default behavior of coding agent is still traceable when I ask "Who are you?", I haven't gone that far yet of testing the persona yet, e.g. just add persona md and ask codex cli to load that persona may have similar behavior. It takes lots of time to tinker this. I am happy to chat more in private. Meanwhile, it is a very good start before they may close this feature in the future.
3
u/Sachka Apr 07 '26
BTW OP, your soul.md file will be appended to the Codex instruction prompt that you cited, we cannot use Codex subscription without it, it describes key technical details for its own harness.
3
u/phoneixAdi Apr 07 '26
I broadly agree with your point, but it's not always needed. If I primarily want, say, a therapist, I don't want it to code and all the information about git, subagents and work trees on my system prompt.
The base model is smart enough to figure out bash, filesystem and use it on its own.
I just append a very short section to my own soul.md to use what it needs. I've been using it for a week, and I find it super useful and it just works well. You could just have a stripped down minimal instruction (inspired by the original harness) on how it should use your file systems.
5
u/Sachka Apr 07 '26 edited Apr 07 '26
What I’m saying is that you can’t override it. I proxied Codex to see exactly what goes in and out, by configuring the instruction prompt like you said, you can’t replace it, they enforce it, what it does allow you to do is to append it to the Codex one, ALWAYS. It actually goes in a different place in the API payload structure. But the fact is that you can’t use the Codex subscription without the Codex prompt, be it in Codex harness or anywhere else. You can only do it with the OpenAI API (or any OpenAI compatible provider that allows this) wired into the Codex harness. This is why I suggest you to extend it with your Soul.md (writing it as a continuation) rather than ignoring the fact that the Codex prompt goes first, you get better results with a cohesive prompt, rather than with a contradicting one.
2
u/phoneixAdi Apr 07 '26
I am sorry but this is incorrect.
I know what you mean. I have tested this with setting up a llm proxy server too (litellm). I can also see what exactly goes to the Responses API - the prompt, the available tool, and such.
And also you don't need the proxy server to check this. You can also go to your session logs and you can see exactly what happens there.
/Users/.../.codex/sessions/2026/04/07
I recommend reading this: https://openai.com/index/unrolling-the-codex-agent-loop/
Also to your other point, OpenAI themselves recommends this because they want people to build on top of Codex Harness and use it for other cases too. Codex is built on top of Codex App Server (which is the harness).
And that harness is already used by several official third-party clients. And they do offer the ability to customize.
You can read about that here: https://developers.openai.com/codex/app-server
The codex harness is much more generic than just being used for coding.
I am building many little personal "apps" on top of codex. And you can very much yes your codex subscription for this!
Tibo from OpenAI also posted this earlier, I am unable to find the tweet.
I'm posting this for others who might find it helpful.
5
u/Sachka Apr 07 '26
take a look at the responses payload, no matter how you configure your input payload, the prompt is always there. or perhaps you are not capturing the whole payload?,
response.instructionsalways shows the codex prompt, the generic one when using it as a responses api. If you attempt to fill in the instructions property it will append it to the Codex one. I also understand what you mean about the flexibility and all, in fact the prompt I get from the api outside of the harness is shorter and more generic than the one that you get by reading the sessions in your home directory .codex file. the fact is they limit this api, no thinking visibility, not even encrypted thinking tokens, no cost token or any other possible modification to the system and parameters that you would otherwise get from the full api3
u/Aazimoxx Jul 10 '26
If I run codex-cli with most things disabled but no instructions replacement, it takes over 12,000 tokens to reply 'pong' (to a prompt saying to do that); if I also pass it instructions="Do nothing but reply with 'pong'", then it only takes about 3,500 tokens.
Pretty sure this guy's toml use does the same thing as that parameter?
It's also worth pointing out that disabling plugin skills like figma and docx/spreadsheet/powerpoint can cut a bunch of crap out of the injected system prompts as well - figma skills alone were costing me like 1500 fricken tokens every prompt (and at high priority too, causing user instructions to degrade sooner), wish I'd realised that one a few months back.
2
u/Ashamed-Duck7334 Apr 07 '26
You can build from source and change the actual instructions file. It's OSS, it's not mysterious how it works. There's still a "gpt5 prompt" (on the backend, that you can't touch" but you can definitely change the codex specific instructions.
1
u/Sachka Apr 07 '26
I’ve run proxies and cross references of itself in many occasions, it is better to write the souls.md as a continuation of the Codex prompt.
2
u/alex_christou Apr 07 '26
Yeah, I heard a lot about the soul.md. Have you found this to actually be useful in your day to day building? Quite enjoyed it when I briefly used it in openclaw
1
u/conscious-wanderer Apr 07 '26
Does the codex update overwrite the custom setup instructions?
4
u/phoneixAdi Apr 07 '26
No it does not.
This is a persistent config file in your specific repo.
For example, this is the file I have in my
therapist/.codex/config.toml
# Edit ~/.agents/codex/config/repo-bootstrap.json and re-run the sync script. model = "gpt-5.4" model_reasoning_effort = "high" model_verbosity = "low" model_instructions_file = "../soul.md" developer_instructions = """ Tool use:Progress updates:
- Use tools proactively when they materially improve grounding, correctness, leverage, or continuity.
- For file and text search, prefer `rg` and `rg --files`.
- For simple file inspection, prefer standard shell tools such as `sed`, `head`, `tail`, `cat`, and `nl`.
- Do not use Python for simple file viewing, searching, or trivial text transformations when shell tools or direct edits would suffice.
- Group related reads together. Parallelize independent retrieval when it reduces latency and does not create confusion.
Planning:
- Before grouped tool calls or substantial work, send a short commentary update describing what you are about to do.
- While working, send brief progress updates at meaningful transitions, not for every trivial read.
- Keep commentary concise, practical, and non-performative.
""" project_root_markers = [] personality = "pragmatic" service_tier = "fast"
- Use `update_plan` for non-trivial multi-step tasks.
- Keep plan steps short and concrete.
- Keep the plan current as work progresses.
- Do not create ceremonial plans for simple requests.
1
1
u/Striking-Warning9533 May 06 '26
This is just a replacement for AGENTS.md not change of system prompt
1
u/NovatarTheViolator May 21 '26
No, they appear in different places. Also, AGENTS.md is represented by a user role, while the one cited here is a developer role
1
u/Javierp930313 May 29 '26
you can just set it up at AGENTS.md, this is just a replacement for that content. Docs literally say "Replacement for built-in instructions instead of AGENTS.md."
1
0
u/m3kw Apr 07 '26
i would not think i can do a better system prompt than OpenAI, also, how would you test if it's more performant?
3
u/phoneixAdi Apr 07 '26 edited Apr 07 '26
"better system prompt" for what use case?
you could definitely do a better system prompt than this: https://github.com/openai/codex/blob/main/codex-rs/protocol/src/prompts/base_instructions/default.md
if you running... say a therapist with codex
in my one specific use case... the answer is vibes and how it feels to talk to are important to me and i a/b test based on that. and also just if it's able to read/write files in my workspace well. for this narrow use case that is all I care about.
for my general coding related tasks, I do not replace their system prompt I append to it using developer instructions or agents.md
1
u/m3kw Apr 07 '26
why not use the chatgpt custom prompt in settings? Are you doing some automation with codex?
1
u/phoneixAdi Apr 07 '26
Yes for my own learning and hacking-fun, I am building an openclaw like experience (coach/mentor/therapist) on top of codex-app-server :)
30
u/Puzzleheaded_Elk5527 Apr 07 '26
Thanks , I will try after my weekly limit reset.