vertex documentation.

vertex is a terminal coding assistant for macOS on Apple silicon. In a project folder it reads files, searches code, edits with a diff you can see, and runs commands in a sandbox. This page covers installing it, using it and fixing the usual snags.

Install

Run the install line in Terminal. It downloads the binary, checks its SHA 256 checksum, and puts it in ~/.local/bin. No sudo. Before it replaces anything it starts the new binary once to make sure it runs, so a download that is broken or doesn't match its checksum never overwrites a working install. If ~/.local/bin isn't on your PATH yet, it tells you the line to add.

curl -fsSL https://thyfwxit.com/vertex/install.sh | sh

Requirements: A Mac with Apple silicon (arm64) running macOS 11 or newer. Intel Macs, Linux and Windows are not supported yet.

Download and check it yourself

If you'd rather download the file and check it by hand, get the binary and its checksum into the same folder:

After a browser download macOS may block the file because it is not notarized. This checks the file against its checksum, makes it runnable, and clears the block on that one file:

The download is a compiled binary so the source stays private. Like any program it can still be studied, and it is free to use.

Quickstart

1. Install it with the install line above.
2. Open a project. cd into a project folder and run vertex. It works in the folder you start it in, so start it inside a project, not your home folder.
3. Connect a model. The first time you open vertex you see a Welcome card and nothing else. Pick how vertex reaches a model, and the rest of the app appears once that works. Esc leaves the card, and /login opens it again whenever you want.
4. Ask in plain words. For example: add a --verbose flag to the CLI and update the README. vertex reads what it needs, shows each change as a diff, and asks before it edits.

Sign in with a personal API key

On the Welcome card pick Personal API key, choose your provider, paste your key, and type a few letters to narrow the model list. vertex checks the key with that provider, lists the models it can use, and lets you pick a default. Custom endpoint takes any https base URL, like https://host/v1. If a key looks like it belongs to a different provider than the one you chose, vertex asks before sending it anywhere.

Sign in with a Nexus server

Someone who runs a Nexus server can give you a chat only access key that starts with nxa_, together with the server's address. On the Welcome card pick Nexus access key at the top of the list, type the server address, paste the key and pick a model. Plain http is only accepted for local network or WireGuard addresses, so a typo can't send the key across the internet unencrypted.

Commands

Type / in the input box to open the command menu. It filters as you type: arrows move, Enter or Tab picks. /help lists every command and keyboard shortcut.

Keys to know

• Shift+Tab switches modes: manual, accept edits, plan and auto.
• Ctrl+C stops a reply; twice quits. Ctrl+D and /quit leave too.

vertex commands

/model

Pick the model. On a Nexus server the choices are Lunar (fast), Solar (code) and Galactic (cloud). Every saved personal key adds a section with its own models: Enter makes the highlighted model your default for new sessions, and s uses it for this session only.

/effort

How hard it thinks, from low to max, with Ultracode as its own switch. /effort with no level opens a box.

/compact

Shrinks the conversation into a summary to free up context. vertex also does it on its own near the limit. It needs a Nexus server (an account or an access key) and isn't available on a personal API key yet.

/clear

Starts a fresh conversation; this chat's history is forgotten.

/usage

Today's use against each limit that applies to how you're signed in.

/cost

What replies cost per model, local ones included: this session, today, and the last 7 and 30 days. /cost budget 5 sets a daily warning (here, 5 dollars) at 80% and again when it's passed, and /cost budget off clears it. See What it costs.

/github

The branch's pull request and checks in the status row: /github on or /github off. See The status row.

/rewind

Puts back the files vertex's own tools changed, to before a request you pick from this session (also /undo). See Modes and the command sandbox for what it can't undo.

/tips

Tips under the spinner and the welcome card: /tips on or /tips off.

/login

Opens the sign in card, where you add or switch keys or sign this machine in to Nexus.

/logout

Signs this machine out.

/history

Shows recent turns saved on this machine.

/help

Every command and keyboard shortcut.

/release-notes

What's new in each vertex version, without leaving vertex.

/quit

Leaves vertex. Ctrl+D works too, and Ctrl+C stops a reply.

/settings

Theme, emoji and the default model and effort.

/think

Shows or hides the model's reasoning while it streams.

/thoughts

Reads the reasoning behind recent replies.

/forget

Clears the conversation history saved on this machine. Your typed input history and saved reasoning stay; delete ~/.nexus to remove everything.

/logo

Previews a logo: atom, molecule, compact or classic.

Models and effort

/model is a list you move through with the arrow keys. On a Nexus server it shows the server's local models first and its cloud picks under their own heading. The first time you pick a cloud model in a session, vertex asks a two choice question before anything leaves the server's own machines. With a personal key, each saved key adds a section with your default model on that key and a way to pick from all of its models.

/effort sets how much the model is asked to do before it answers and how many tool steps it may take. It is one line of five levels. On a Nexus server the level also sets the model's thinking; with a personal key or a model on your Mac, vertex changes its instructions and step budget, not the provider's own thinking setting.

low

Short, direct answers. Up to 4 tool steps.

medium

Checks every requirement before answering. Up to 8 tool steps. The default.

high

Works the problem through before answering. Up to 12 tool steps.

xhigh

Also asked to run its code and fix what fails. Up to 16 tool steps.

max

The same, with up to 24 tool steps. Slow: use it for the hardest tasks.

Ultracode

Ultracode is a separate switch at the end of the effort line (press Tab in the /effort box). It works at every effort level and never changes the level: it adds a planned, checked workflow on top of that level's thinking, and more effort means deeper thinking in each step.

With Ultracode on, every task goes through five phases, kept short on a simple task:

1. Frame. State the outcome and how it will be checked.
2. Plan. A short numbered task list. One task is fine for a small change.
3. Do. Work the tasks one at a time with the tools.
4. Check. Run the real tests, the program or a syntax check, read the actual errors and fix them. It stops after two attempts that fail the same way.
5. Review. Compare the changes with the request, look for anything missed or changed by mistake, then report which checks passed and what is still uncertain.

These are instructions to the model, with a larger step budget (10 at low up to 48 at max). A good model follows them closely; vertex can't force a model to, so read its report of what passed.

Modes and the command sandbox

Every change vertex's file tools make shows its diff: in manual mode before you choose, in the other modes as the change is made. Commands the model runs can also change files, and those don't show a diff. Shift+Tab cycles four modes, and the current one shows in the status line:

manual

Asks before every change. The default.

accept edits

Makes file changes without asking.

plan

Only reads, and finishes with a numbered plan. It changes no file and runs no command.

auto

Accepts edits and also runs commands without asking, where the command sandbox applies.

At a change prompt, Yes allows one change and Yes, allow all edits this session switches to accept edits. No lets you tell vertex what to do differently. In manual and accept edits modes, vertex also asks before each command, with a choice to allow that exact command for the rest of the session.

What the sandbox does

Where macOS's sandbox is available, every command vertex runs goes through it, with a profile made for that run. A sandboxed command:

• Can't use the network. That includes Unix sockets and DNS.
• Can only write inside your project folder and a private temp folder. It can't create or write a .git folder anywhere in the project, in any letter case, because a hook or a config line there would run later under your own git. vertex's own file edits can't touch .git either.
• Can't read most of your home folder. It can read the project, the folders on your PATH, specific toolchain folders such as ~/.local/bin, ~/.cargo/bin, ~/.nvm, ~/.pyenv and ~/.rustup, and your git config files. It can't read the whole of ~/.local, ~/.cargo or ~/.config/git, which can hold tokens. Whatever a command prints goes back to the model, which is why reads are limited. Outside your home folder it can read what your user account can, and a secret kept inside an allowed folder (the project, a PATH folder) is readable too.
• Can't reach other apps. open, osascript, launchctl and security can't run, and the services they talk to are closed, so it can't touch the Keychain.
• Gets a trimmed environment with only a few basics such as PATH and HOME.
• Is ended as a group. When a command finishes, vertex ends its process group, not just the first process. A process that deliberately leaves the group can keep running.

Where the sandbox can't apply, vertex says so and asks before every command, unless you told it not to ask again for that one, and approved commands then have your normal file and network access. A few kinds of command are refused in every mode: system and privilege changes such as sudo, and history changes such as git push --force and git reset --hard.

vertex also refuses to run commands when it was started in your home folder or above it, because a command there could reach your shell startup files, LaunchAgents or ~/.ssh. In the home folder every file change asks too, whatever the mode. Start vertex inside a project folder. If you run in auto mode, keep tokens out of ~/.local, ~/.cargo and git's config.

Providers and keys

vertex reaches a model one of three ways, and you can save more than one and switch between them in /model.

Your own API key

Use the account you already have. vertex checks the key with the provider, lists the models it can use, and sends the key to that provider and nowhere else.

A Nexus access key

Someone who runs a Nexus server can give you a chat only key that starts with nxa_, together with the server's address. It reaches the models they chose for it, up to a daily cap, and they can revoke it at any time.

Models on this Mac: Ollama and LM Studio

Pick Ollama or LM Studio in /login. There is no key to paste. vertex uses the server at its standard address on this Mac, 127.0.0.1:11434 for Ollama and 127.0.0.1:1234 for LM Studio, so start the server first: the Ollama app or ollama serve, or LM Studio's Developer tab. The model gets the same tools as any other model.

The context size comes from what the server runs the model with, and falls back to 8,192 when the server doesn't say. For long tasks, set Ollama's context length higher, for example OLLAMA_CONTEXT_LENGTH=32768. Your prompts and code go to that server on your Mac and nowhere else, and replies count as free in /cost.

Usage and limits

/usage shows today's use (by UTC day) against each limit that applies to how you're signed in. On a personal key it shows what the provider reports about that key's rate limits: the requests left in the provider's window as of your last reply. On a Nexus access key it shows your requests and tokens against the key's daily cap.

While a reply streams, the counter under it climbs as tokens arrive, so you can tell a slow reply from a stuck one.

The status row

The row at the bottom of vertex shows, from left to right: the model, whether it runs Local or in the Cloud, a context meter, and what this session has cost so far. Spend shows in dollars for paid models, as free with a token count for local models and free tiers, and as +? when a reply had no known price.

Then comes git, when you started vertex inside a repository:

• The branch, with ↑ for commits ahead of its upstream and ↓ for commits behind.
• + staged files, ~ changed files, ? untracked files and ! conflicts.
• The branch's pull request number with ✓ when its checks pass, ✗ when they fail and ◷ while they are pending. This needs the GitHub CLI (gh) installed and signed in. /github off turns it off.

Wide windows also show how long the session has run and, on a Nexus account, who you're signed in as. As the window narrows, those go first. Then git gets shorter: the counts collapse to a single dot and the folder name goes, while the branch and the checks stay. If it still doesn't fit, git goes, then the spend, the context meter and Local or Cloud, in that order. The model's name always stays.

What it costs

/cost prices each reply like this:

1. The provider's own figure, when it sends one.
2. OpenRouter's model list, for models reached through OpenRouter.
3. Otherwise a price table from LiteLLM's MIT licensed list, built into each release. /cost shows the date of that table.

If there is no price, the reply is unpriced and shows +?. vertex never guesses. Cached input is counted at its own rate when the price table has one, else at the input rate. The figures are estimates from each reply's own token counts, and a reply stopped before the provider reported its counts isn't counted. Local models and Nexus's free tiers count as free. Your electricity isn't counted.

The records are kept on your Mac, per day and per model, for the last 90 days you used vertex. /cost budget 5 warns you once you reach 80% of 5 dollars a day and again when it's passed.

Tips and Sputnik

Tips show under the spinner while a reply is on its way, and under the welcome card. /tips off hides them.

Click Sputnik, vertex's mascot, on the welcome card to play a short show and open an about line. Its docs link opens in your browser.

Where your data lives

Keys

Personal API keys are saved in the macOS Keychain under the service name vertex and only sent to the provider you picked. ~/.nexus/vertex.json records the provider, the model and the last 4 characters of each key, never the key itself. A Nexus sign in token, if you have one, is in ~/.nexus/credentials, readable only by you.

History

Your chat history (~/.nexus/history.jsonl), what you typed (~/.nexus/history) and the model's reasoning (~/.nexus/thoughts.jsonl) stay on your Mac. /forget clears the chat history (typed input and reasoning stay). The /cost records are in ~/.nexus/vertex-spend.json: token counts and dollars per day and per model, for the last 90 days you used vertex, never sent anywhere. The app unpacks itself into ~/.cache/vertex on first run.

No telemetry

vertex sends nothing about you to me: no usage data, no crash reports, no analytics. Your prompts and code go only to the model provider or Nexus server you choose. The vertex privacy policy has the details.

Updating and uninstalling

Update

Run the install line again. It checks the new download against its checksum, starts it once to make sure it runs, and only then replaces ~/.local/bin/vertex. Releases are named by date, like 2026.10.16 (earlier ones were 0.2 to 0.4). vertex --version shows the version you have, and /release-notes inside vertex shows what changed. The same notes are on the what's new page.

Uninstall

Remove the program and the folder it unpacks into:

The chat history, settings and sign in token vertex keeps are the files in ~/.nexus listed above, and your saved keys are the Keychain entries for the service vertex. You can delete them at any time. Deleting local files does not delete anything already sent to a provider or a Nexus server; see the privacy policy for how to have records on my Nexus server deleted.

Troubleshooting

macOS says the file can't be opened

After a browser download macOS may block the file because it is not notarized. Check the file against its checksum and clear the block on that one file with the command in the install section. The curl install line avoids that step.

Command refused in the home folder

The message says vertex was started in the home folder or above it, so it won't run commands. Quit, cd into a project folder, and start vertex there.

Not signed in

vertex shows Not signed in with /login beside it. Type /login to open the sign in card, then pick Personal API key or Nexus access key as described in the quickstart.

vertex: command not found

The install put it in ~/.local/bin, which may not be on your PATH yet. The installer prints the line to add. For zsh it is:

The install says the download doesn't match its checksum

Nothing was installed. Run the install line again. A download that can't start on your Mac, or that doesn't report a version, is refused the same way.

Questions or something else

Email xavier@thyfwxit.com.