hip-agent is a minimal coding agent harness. The idea, harness in prompt, is explained
in the blog post.
agent is the core and the specification: it uses the current Codex login,
gives the model sh and view_image tools, takes a prompt, and runs the tool loop until
the model returns a final reply. The prompt tells the model where the source is, so it can
read what the harness does and change it. Everything Codex-specific is in
codex.py: the Responses API over HTTP, and the session file in Codex CLI's
rollout format.
Warning
Commands run without a sandbox or approval check. Use this at your own risk.
Note
The OAuth-backed Codex endpoint is a private ChatGPT backend. It has no public stability guarantee and can change without notice.
Requirements are uv and a current Codex login.
codex login
./agent "inspect this repository and explain it"The conversation is a Codex CLI rollout under $CODEX_HOME/sessions; its path goes to
standard error and only the final reply to standard output. codex resume <id> opens it,
and AGENT_RESUME continues it, including one Codex CLI wrote:
AGENT_RESUME=0199b3e2-... ./agent "continue"The configuration is the AGENT_* environment variables, set where you set any other
variable. agent reads nothing else, and a subagent inherits them like any child process.
# ~/.zshrc or ~/.bashrc
export AGENT_MODEL=gpt-5.6-sol
export AGENT_PLUGINS=~/github/hip-agent/plugins/environment:~/github/hip-agent/plugins/cwd| Variable | Default |
|---|---|
AGENT_MODEL |
gpt-5.6-sol |
AGENT_REASONING_EFFORT |
unset; Codex CLI's model_reasoning_effort, none to max |
AGENT_SERVICE_TIER |
unset; priority or flex |
AGENT_INSTRUCTIONS_FILE |
unset; a built-in line |
AGENT_PLUGINS |
empty; colon-separated plugin directories |
AGENT_RESUME |
unset; a new rollout |
AGENT_COMPACT_TOKENS |
244800 |
AGENT_OUTPUT_LIMIT |
40000 |
CODEX_HOME |
~/.codex |
SHELL |
the shell that runs commands |
OPENAI_BASE_URL |
unset; a proxy that holds the login, used with OPENAI_API_KEY |
A plugin follows the Agent Plugins protocol. Skills in plugins,
.agents/skills, and ~/.agents/skills are added to the prompt. Hooks follow Claude Code's
hook format; the core runs SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
and Stop.
plugins/ ships three example plugins:
| Plugin | What it does |
|---|---|
environment |
adds cwd, shell, date, and timezone, as Codex CLI does |
agentsmd |
adds the nearest AGENTS.md on the first turn |
cwd |
cd persists across commands, per conversation |
A subagent is agent run from sh: it gets its own conversation and inherits everything
else, so the parent configures it with variables on the command line.
This repo is designed and tested with the gpt-5.6 series of models in mind. No other providers or models are planned. An agent should be able to adapt the idea in this repo to support them.