Ekamyth Agent OS docs
Standard OS / Services and devices

How Ekamyth Agent OS connects to Claude Code and Codex

Agent OS works inside the agents you already use. Their model calls pass through the model gateway on your machine, and their hooks call Agent OS at set moments in each session, such as before a tool call.

How does Agent OS connect to your agents?

Agent OS doesn't replace Claude Code or Codex, and you keep your own provider account. It connects to each agent in two places, both on your machine.

The model gateway is where your agent's model calls go. It passes each call to your provider, with your own key or your agent's own sign-in, and returns the answer. Hooks are a feature of Claude Code and Codex: at set moments, the agent calls Agent OS and waits for its answer before it goes on. hero setup makes both connections after showing you its plan, and hero setup --undo takes them back out.

Five numbered steps. Your agent sends model calls to the Agent OS model gateway, which sends them on to your provider. Your agent calls Agent OS through its hooks and gets an answer. hero status and hero setup --check show you both connections. What runs inside a script is not seen, so a script can call another service directly.
The numbers match the steps below. Model calls and hooks are two separate connections, and each covers different things.

Connection concepts

TermWhat it means
Model gatewayThe part of Agent OS that your agents' model calls pass through on their way to your provider. It listens only on your own machine. The command that starts it is hero proxy, and command output, such as hero status, calls it the proxy. See the path.
HookA moment in a Claude Code or Codex session when the agent calls Agent OS, such as before it runs a tool. See what each connection covers.
Setuphero setup, which connects the agents it finds on your machine, after asking you. See hero setup.
ActivationLinking this machine to your Ekamyth account. Until it's done, nothing is connected and no background service starts. See Activation.
PostureHow Agent OS treats tool calls your rules don't cover. Every install starts on the builder posture. See how it decides.
Slash commandsThe 12 /hero: commands setup adds to Claude Code, and the matching skills it adds to Codex. See Commands inside your agent.
MCP wrapperhero mcp wrap <server>, which you add to your agent's MCP configuration for one server at a time, so each call to that server is checked first. Setup doesn't add it. See How MCP works.

The path of your agent's work, step by step

Before these steps, you install Agent OS and run hero setup. The install line runs setup for you. See Get started.

  1. Your agent sends a model call to the model gateway. Setup pointed Claude Code and Codex there.
  2. The model gateway sends it to your provider with your key or your agent's own sign-in, and returns the answer to your agent. Routing is on by default, so Agent OS can send a call to a different model.
  3. At set moments, your agent calls Agent OS through a hook and waits: when a session starts, when you send a prompt, before and after each tool call, and at the end of a turn.
  4. Agent OS answers. It lets the tool call run, adds context such as your saved memory, or refuses the call and says why.
  5. You check the connections with hero status and hero setup --check.

What each connection covers

The model gateway carries model calls only. Your agent's tools reach Agent OS through the hooks. Some things reach neither.

What your agent doesModel gatewayHooks
Calls a modelPasses throughNone
Reads or edits a file, or runs a shell commandNoneSeen before and after the call
Fetches a page or searches the web in Claude CodeNoneSeen as a tool call
Uses a web search your provider runs on its sideDoesn't reach Agent OSDoesn't reach Agent OS
Calls an MCP toolNoneSeen as a tool call
Runs a script or programNoneThe command is seen. What runs inside it isn't, so a script can call a service directly.

What Agent OS does at each hook:

MomentWhat Agent OS does
A session startsAdds your saved memory to the session as context. See How Brain works.
You send a promptNotices a standing rule you state in chat. If the model gateway isn't running, it stops the prompt from being sent and tells you how to start it.
Before a tool callChecks the call against your rules and the posture. It can refuse the call.
After a tool callRecords what ran.
The end of a turnChecks the reply against facts you've recorded. See Claude Code and Codex for how each agent handles a conflict.

How Agent OS decides what passes

What the connections keep, and what leaves your machine

To see what may leave this machine and what actually left, run hero privacy.

When a connection fails

What failsWhat you seeWhat happens to the work
The model gateway stopsIt runs as a background service that restarts itself. When you send a prompt while it's down, the prompt isn't sent, and the message names the command that starts it.Model calls from a connected agent fail until it's back.
The model gateway isn't answering when you run setupSetup says NOT written: proxy not reachable for that agent.That agent's model route is left as it was, so it keeps reaching its provider.
An optional step in the model gateway fails, such as routing—The call goes on. If a safety step, such as a budget or rule check, can't answer, the call is refused.
A hook can't read your rules or its own inputThe tool call may be refused, in the agent's own refusal format.The call doesn't run.
Claude Code stops the check at its own 15-second hook limit, or kills it—That one call runs unchecked.
On Codex, the check can't run, fails or doesn't answer within 120 secondsEkamyth could not check this action, so it refused it: <reason> [<code>]. Run: hero setup --checkThe call doesn't run.
Codex hasn't approved the hookshero status shows Codex hooks not approved yet, with the step to approve them.Codex runs a hook only once it's approved.
Codex's hooks feature is offhero status names the step: codex features enable hooks.Codex runs no hook at all.

Connections on Claude Code and Codex

Claude CodeCodex
Where setup points model callsANTHROPIC_BASE_URL in ~/.claude/settings.jsonA model provider in ~/.codex/config.toml, plus OPENAI_BASE_URL for shells Codex starts
Hooks56. Codex approves them through its own hook approval. The end-of-turn hook needs Codex 0.114.0 or later.
Slash commands12 /hero: commands12 skills
Saved memory at session startYesWired by setup
A reply that conflicts with your recorded factsAgent OS asks the agent to fix the reply.You see a warning. Codex's end-of-turn hook can't take an instruction, so the agent isn't asked.
Conversations started before setup—When setup can't read Codex's conversation list, it says it can't tell whether those conversations still go straight to OpenAI.

What you can change in the connections

SettingDefaultEffect
hero setup --proxy <url>http://127.0.0.1:8081Points your agents at a model gateway at another address. See --proxy.
HERO_PROXY_PORT=<port>The port saved at install, else 8081The port the model gateway uses. See hero proxy.
Routing offRouting onSet HERO_ROUTE=0 in the model gateway process's environment and restart the model gateway to turn routing off, as described in Turn routing off.
HERO_BRAIN_SESSION_MEMORY=offOnStops adding your saved memory at session start.
hero codify enforce offArmed after setupStops your rules from blocking tool calls. See hero codify.
EKAMYTH_INSTALL_NO_SERVICE=1UnsetInstalls with no background services, and skips the daily job that keeps your rules in sync.
hero setup --undoTakes both connections out of your agents. See Example 5.

See the connections for yourself

Run these on your own machine.

# Both connections are configured: 8 checks, all ok
hero status

# Each agent's model route, hooks and slash commands
hero setup --check

Then open a new Claude Code session and type /hero:health. To read the output line by line, see How to read hero status output and Example 1 of hero setup.

Connection limits and next steps

See Limits of hero setup, Limits of hero proxy and Limits of install, upgrade and remove.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.