Codex Agent

Ask the Codex agent to write, explain, and fix SQL in a right-sidebar chat that already knows your open file and schema.

The Codex CLI

The agent is OpenAI's Codex CLI. The codex binary runs locally on your machine, but it is a client: it sends each prompt to OpenAI's hosted models in the cloud and streams the reply back. Arris shells out to that binary rather than calling an API itself, so there is no API key to enter or manage inside Arris. The provider, model, and authentication all come from your own Codex configuration (~/.codex/config.toml), which is why the badge shows whatever model you have set there. As the info icon notes, the agent “needs an active Codex (ChatGPT) subscription or an OPENAI_API_KEY.”

Make sure codex is installed and on your PATH. If Arris cannot find it, the input is disabled and shows “Codex CLI not found on PATH. Install it to use the agent.” Authentication is not pre-checked: if Codex is signed out, the turn still runs and its error (for example, a not-logged-in message) streams back into the conversation.

Arris runs Codex with guardrails suited to query writing: a read-only sandbox so the agent cannot touch your filesystem, no auto-approval so it never proceeds with a privileged action on its own, and project docs disabled so any AGENTS.md files in your repos cannot derail a turn. Your global model and credentials still apply.

Privacy

Arris does not operate a cloud service for the agent and never sees your prompts: it hands them to your local Codex CLI, which sends them to OpenAI's cloud under your own account. What Arris puts into a turn is scoped to what you can see:

Your prompt, plus the active file and selection chips.
The connection's schema as DDL (table and view names, columns, and types) and its dialect, capped in size so a huge schema cannot blow the context window.

Your row data is never sent automatically. Result rows leave your machine only when you explicitly click Run & share on a SQL block. Database passwords and connection credentials are never included. Whatever the Codex CLI does with the prompt is governed by Codex's own configuration and privacy model.

Opening the agent

The Agent lives in the right sidebar, where it shares space with the connections tree, the chart editor, and pinned queries. Open it with ⌘8 (Show Agent) or by clicking the agent icon in the right-sidebar switcher at the bottom. ⌘K (Ask Agent) also brings it up so you can start typing right away.

The pane header reads AGENT with an info icon, and a badge showing the active provider and model as Codex · model (for example Codex · gpt-5.5). The model name is read from your Codex CLI configuration, not chosen inside Arris. Once a conversation has started, a trash icon clears it.

The Arris Agent pane in the right sidebar with the AGENT header, a Codex · gpt-5.5 badge, a stg_invoices.sql context chip, the empty state 'Ask Codex about your SQL', and the 'Ask the agent…' input at the bottom — The Agent pane — the Codex · model badge, the attached file chip, the empty state, and the input box with the right-sidebar pane switcher below.

Editor context

The agent reads your editor automatically, so you rarely have to paste code. Just under the header, Arris shows context chips for what it will send with your next message:

File — the active editor tab, labeled with its file name (e.g. stg_invoices.sql). The whole file is included.
Selection — when you have text highlighted, a second chip appears as selection · N lines and only that range is sent.

The chips update as you switch tabs or change your selection. Click the × on a chip to drop it from the next message if you would rather not include that context. When a connection is active, the agent is also given your database schema and dialect (see Privacy) so the SQL it writes matches your tables and syntax.

Asking a question

Type into the box at the bottom (Ask the agent…) and press ⌘↩ to send. The empty state sums up what it is for: “Ask Codex about your SQL. Write, explain, or fix a query.” Good prompts look like “write a query for the top 10 customers by revenue this quarter”, “explain what this CTE does”, or “why is this join returning duplicates?”

Each conversation is tied to the active connection, so switching connections gives you a separate thread, and follow-up messages continue the same Codex session with full context of the exchange so far. While the agent is working, an animated indicator shows in the stream with a red Stop button to cancel the turn. Replies arrive as a mix of prose, fenced SQL blocks, and collapsible cards for any tool steps the agent ran.

Working with replies

Every SQL block in a reply is rendered as a read-only, syntax-highlighted snippet with action buttons so you can move it into your editor without copy and paste:

Action	What it does
Insert at cursor	Drops the SQL into the active editor at the cursor position and highlights what was inserted.
Replace selection	Swaps your highlighted text for the SQL. With nothing selected, it replaces the whole document.

Nothing is written to your editor until you click one of these, and nothing runs on its own. You review the SQL, place it, and execute it yourself with ⌘↩ as usual.

A Codex Agent reply: the user message 'Monthly sales broken down by product category and customer, order by sales amount in descending order', a syntax-highlighted SELECT query with Insert at cursor and Replace selection buttons, and a closing note 'Returns monthly sales by product category and customer, highest sales first.' — A reply — the request, a syntax-highlighted SQL block with Insert at cursor and Replace selection, and a short explanation below it.

When a connection is active, each SQL block also offers to run itself and feed the output back to the agent, which is how you turn a one-shot answer into a back-and-forth:

Run & share 100 rows with Codex — runs the query locally and sends the first 100 rows back as the next message.
Run & share full results with Codex — sends the entire result set. Arris warns that “all rows can be slow on large tables and consumes far more Codex tokens.”