> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexgate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# hexgate chat

> Single-process REPL against a local or registered agent.

`hexgate chat` is the inner-loop REPL — a single process against a local or
registered agent. No platform, no Docker, no browser. It sets `HEXGATE_LOCAL_MODE=1`
automatically so audit stays on your machine even if `HEXGATE_API_KEY` lives in
your `.env` from an earlier session. Denies and approval-required calls render as
inline panels in the terminal — the same `Decision` data the platform would log,
surfaced where you're iterating.

Reach for `chat` when you're authoring a policy YAML, tweaking a tool, or shaping
a system prompt. See [Which path do I pick?](/two-paths) for chat-vs-serve.

```bash theme={null}
hexgate chat --agent example_agent                                   # demo agent in the repo's examples/ (run from the repo root)
hexgate chat --list-agents                                           # show resolvable agents
hexgate chat --agent my_app.agents:my_agent                          # by module:attr spec
hexgate chat --use examples/file_agents.py --agent workspace_explorer
hexgate chat --use examples/research_agents.py --agent update_researcher --approval-mode ask
```

Run `hexgate --help` for all subcommands (`chat`, `serve`, `register`, `policy`)
and `hexgate <subcommand> --help` for each one's flags.

## Agent resolution

`--agent` accepts either a plain agent id (`example_agent`) or a uvicorn-style
`module.path:attr` spec (`my_app.agents:my_agent`). The CLI discovers agents
from:

* `./<agent_dir>/agent.yaml`, `./agents/<agent_dir>/agent.yaml`, `./examples/<agent_dir>/agent.yaml`
* code-defined agents registered from a `--use` script (e.g. `examples/file_agents.py`)

## Keys the example agent uses

The `example_agent` (in the repo's `examples/example_agent/`, resolved when you
run from the repo root) uses the filesystem tools `read_file` / `glob` / `grep`,
which need no API keys — only the model does:

* `OPENAI_API_KEY` — the default `openai:gpt-5.4` model

Bootstrap doesn't hard-require it; it's read when the agent is built (see the
[environment reference](/reference/environment)).