This page takes you from install to a first prompt that goes through Cortex. It also tells you how to undo each step.
Run this command:
curl -fsSL https://www.rossoctl.dev/cortex/install.sh | shSetup lists what it will change and asks once (Continue? [Y/n]).
It does these steps:
- It installs
agentopandcortexto~/.local/bin. - It adds
~/.local/bintoPATHin your shell profile. - It writes
~/.cortex/config.yaml. - It runs the proxy on
127.0.0.1:47600, as a launchd user agent on macOS or a systemd user service on Linux.
To skip the question, add --yes:
curl -fsSL https://www.rossoctl.dev/cortex/install.sh | sh -s -- --yesWhen setup is done, open a new terminal. The new terminal reads the new PATH.
install.sh and agentop setup don't run on Windows yet (#1520). Install by hand:
- From the releases page, download
agentop_<version>_windows_amd64.zipandcortex_<version>_windows_amd64.zip(arm64on an Arm PC), andchecksums.txt. - Check them in PowerShell.
checksums.txthas lower-case hashes, andGet-FileHashprints upper case, so compare(Get-FileHash .\agentop_<version>_windows_amd64.zip -Algorithm SHA256).Hash.ToLower()with the line for that file, and the same forcortex. - Unblock both:
Unblock-File .\agentop_<version>_windows_amd64.zip, and the same forcortex. The binaries are not signed yet, and a downloaded.zippasses its "from the internet" mark on to what it holds, so without this SmartScreen may block them. - Unzip both into one folder, for example
$HOME\.local\bin, and add that folder to your userPATH. Then open a new terminal: a terminal that is already open keeps the oldPATH. - In that new terminal, run the proxy:
cortex --local. It writes~/.cortex/config.yamlon first run. Stop it withCtrl-C. If it says it can't parse~/.cortex/config.yaml, a file written by an earlier Windows build, delete that file and run it again: Cortex writes a fresh one. - In a second new terminal, run
agentop observe.
Then connect Claude Code with agentop configure claude-code enable, or run one session through Cortex with agentop exec -- claude.
Not on Windows yet: agentop service, setup, uninstall and update (they refuse and say so), so the proxy runs only while its terminal is open. Tools other than Node (git, curl, Python) inside a session don't trust the TLS bridge yet.
Connect each agent that you use. Do this one time per agent.
| Agent | Connect | Start it | Running agent |
|---|---|---|---|
| Claude Code | agentop configure claude-code enable |
claude |
Restart a running claude. claude --resume opens the conversation again. |
| OpenCode | agentop configure opencode enable |
opencode |
enable restarts the OpenCode background service. This stops every OpenCode session that uses the service. |
| Codex | agentop configure codex enable |
codex |
Restart a running codex. It reads ~/.codex/.env only when it starts. enable restarts the Codex background app-server. |
| IBM Bob | agentop configure bob enable |
The Bob editor, or bob in a new terminal |
Restart Bob. Bob then reads its settings again. |
| Pi | agentop configure pi enable |
pi in a new terminal |
Start pi in a new terminal. |
| Any other agent | Not necessary | agentop exec -- <command> |
Nothing to restart. |
Each agent has a guide in agents/<agent>.md. The first column links to it.
- In a second terminal, run
agentop observe. - Send one prompt to your agent.
- Look for a new row in Sessions.
With two or more agents, agentop observe opens the Agents pane first.
Press Enter on an agent to show its sessions.
The row shows the session id, the title, the time of the last change, the event count, the tokens and the cost.
The AGENT column appears when Sessions lists two or more agents.
Press Enter on the row to open the events pane. Its METHOD column shows the model name.
When no row appears, run agentop doctor.
Each line of its output starts with one of these marks:
- ✓: the item is correct.
- !: advice.
- ✗: a problem. The line gives the command that repairs it.
Then read Troubleshooting.
This is the Sessions pane at 100 columns:
agentop · http://127.0.0.1:47601
LAST 1H TODAY 7 DAYS MONTH
$4.04 $18.80 $216.44 $703.18
────────────────────────────────────────────────────────────────────────────────────────────────────
SESSION TITLE UPDATED EVENTS TOKENS COST SAVED~ CTX(1M)
567-89ab …src/append-spans 3s ago 42 48.2k $0.12 $0.01 ████░░░
890-cdef weather-agent 18m ago 15 1.2k <$0.01 — ▏░░░░░░
321-0fed 42m ago 7 2.9k — — ██░░░░░
default 1h ago 8 — — — —
● connected 2.1 events/sec feedback: https://github.com/rossoctl/cortex/issues/new/choose
[↵] drill [u] usage [$] spend [/] search [?] keys [q] quit
- The band
LAST 1H,TODAY,7 DAYS,MONTHshows what your agents spent in each time span. SESSIONshows the session id, cut short.TITLEshows the conversation title.UPDATEDshows the time since the last event.EVENTSshows the event count.TOKENSandCOSTshow the totals for the full session.SAVED~shows whattool-prunesaved.CTX(1M)shows how full the context was on the last turn, against a window of one million tokens.- The footer shows the connection state and the keys.
| Key | Action |
|---|---|
↑ / ↓ |
Move between rows |
Enter |
Open the row |
Esc |
Go back |
/ |
Search the pane |
? |
Show every key |
$ |
Open the spend breakdown, by model, endpoint or agent |
u |
Open the usage charts |
T |
Open the timeline of the highlighted session |
A |
Open the per-agent breakdown |
q |
Quit |
Press ? for every key.
For more detail, read Keybindings.
More: Using agentop.
- Add the history from before Cortex:
agentop import --dry-run, thenagentop import. Read Importing agent history. - Change the model server:
agentop server. Read inference-servers.md. - See the cost:
agentop cost --window month --by agent. Read pricing.md.
To disconnect one agent, run agentop configure <agent> disable. Then restart the agent.
To remove Cortex, run agentop uninstall. It asks once.
agentop uninstall --purge also deletes ~/.cortex.
Uninstall disconnects Claude Code, OpenCode, IBM Bob and Pi.
It does not disconnect Codex. If you use Codex, run agentop configure codex disable first.
On Windows, agentop uninstall is not supported yet (#1520). Remove Cortex by hand:
- Disconnect each agent you connected:
agentop configure <agent> disable. Then restart the agent. - Stop the proxy:
Ctrl-Cin its terminal. - Delete
agentop.exeandcortex.exe, and remove their folder from your userPATHif you added it only for them. - Optional, and separate: delete
~/.cortex. That deletes everything Cortex kept, including the session archive, the cost ledger and the TLS bridge's CA.
For more detail, read Remove it.