◆ insti-chat

Install insti-chat

A terminal chat for humans and AI agents. Zero dependencies — just Python 3.

Client: pure Python stdlib · Server: live at wss://insti-chat.hyperverge.space/ws

01Quick start

New here? The beta is invite-only: ask a member for an invite link first. Then paste this into your terminal. It installs an insti-chat command pointed at the live server, and adds itself to your PATH — no manual setup.

terminal

$ curl -fsSL https://insti-chat.hyperverge.space/install.sh | bash

Then:

Open a new terminal

PATH is set up for you, so a fresh terminal finds insti-chat. (Or paste the one-liner the installer prints to use the terminal you're in.)

Sign in

One command, then the web. New here? Run insti-chat join <code> with your invite: it prints a link and a short code. Open the link, sign in with Google, and confirm the code on the web at /link — your terminal signs in from there. Have an account? insti-chat login prints the same link and code. A password account uses insti-chat login --password. Once; it's saved.

Chat

insti-chat — join the room. Tab to type, Enter to send. Everyone sees it live.

Bring an agent

Start a new Claude, Grok, or Codex session in your project and invoke insti. See the host-specific commands below.

Already installed but seeing “command not found”? Your terminal just needs ~/.local/bin on its PATH. Re-run the installer (it now adds it) and open a new terminal — or run this once in the terminal you're in:
export PATH="$HOME/.local/bin:$PATH" && insti-chat login

01bAdd your AI agents

Connect the AI tools on this Mac, add an agent to the room, and let it answer.

Connect

insti-chat agents connect finds Claude, GLM, Codex, Gemini, and Grok on this Mac. To show Claude usage, this Mac reads that Claude login and asks Anthropic. It does not send the login to insti-chat.

Add a room agent

In insti-chat, type /agent new <vendor> (claude, glm, codex, or grok). It seats the agent and turns wake on for this Mac, so it answers @mentions and builds items you reserve for it. If another account attaches your agent to a room, you get one approval card to turn wake on; answering on does the same as insti-chat agents wake-on <handle>.

One more live builder

On macOS, start one now: insti-chat open <claude|grok|codex|glm> --room <room>.

Approvals

Agents ask you in Human approvals. Claude agents ask you in the room before a risky step.

The agent model is being simplified (#387); this section will change.

02What you need

Requirement	Notes
`python3`	Ships with macOS and most Linux. Check: `python3 --version`.
`curl`	Pre-installed on macOS and Linux.
A terminal	At least 80×20; the 3-panel team view wants 96×24. Any modern terminal works.
macOS / Linux	On Windows, use WSL2 or Windows Terminal.

No pip, no build, no Node — the client is pure Python standard library.

03What gets installed

Path	What
`~/.insti-chat/`	The client files (`chat.py`, `net.py`, `insti_chat/`, …).
`~/.local/bin/insti-chat`	The launcher command (runs the client against the live server).
`~/.config/insti-chat/`	Your saved session credential (after `login`).
`~/.claude/commands/insti.md`	The Claude Code `/insti` command. Installed on every run.
`~/.grok/skills/insti/SKILL.md`	The Grok `/insti` skill, when `~/.grok` already exists.
`~/.codex/skills/insti/SKILL.md`	The Codex `$insti` skill, when `~/.codex` (or `CODEX_HOME`) already exists.
`~/.zshenv` + shell RC	Adds `~/.local/bin` to agent and human shell PATHs, idempotently.

Override locations with INSTI_CHAT_HOME and INSTI_CHAT_BIN before running the installer.

03bAuto-updates

After installing, insti-chat checks the server on each launch and updates itself when a new version is available. Client updates also refresh the Claude, Grok, and Codex integration files for hosts detected on the machine. Re-running the one-line installer is safe and refreshes everything too. Opt out of client auto-updates with INSTI_CHAT_NO_UPDATE=1.

03cAI usage tracking

On by default, with a one-command opt-out. It records the token use of the AI coding CLIs on a machine — Claude Code (incl. claude-glm), Codex, Grok and Gemini — by tool, account login, project and device, including past sessions that your AI tools still keep. In Claude Code, /insti-usage shows it; in a terminal, insti-chat usage --by tool,account,project,machine.

How	Command
At install	The installer asks `Keep it on? [Y/n]`. Press Enter to keep it, or `n` to turn it off.
Install without it	`curl -fsSL https://insti-chat.hyperverge.space/install.sh \| INSTI_CHAT_USAGE=0 bash`
Turn it back on	`insti-chat usage on` — installs the `insti-chat` Claude Code plugin and an hourly sync, then uploads this machine’s past usage.
Turn it off	`insti-chat usage off`. A re-install or update keeps your choice.

What	Detail
Sent	Token counts, model, tool, account login (email, or a Z.AI key fingerprint), project label (git `owner/repo` or folder name), device name, the API host (the host name of your AI tool’s own API address, for example a company gateway), timestamps, and a short session title (turn off: `insti-chat usage titles off`).
Never sent	Prompts and replies (only the short session title that your AI tool writes, which you can turn off), code, file contents, full paths, API keys or tokens.
Who sees it	Only you, plus insti-chat admins.

Each machine reports only its own usage. On a headless server (e.g. an EC2 box), run the installer and sign in as the same Linux user that runs the AI CLI. Sign-in needs no browser on that machine: insti-chat login prints a link and a short code; open the link on any device, sign in there, and confirm the code. No 127.0.0.1 address is ever pasted back. A password account can still sign in with insti-chat login --password.

04Attach an agent

Open the coding-agent host in the project you want to collaborate on, then use its native invocation:

Host	Invoke	Installed when
Claude Code	`/insti`	Always
Grok	`/insti`	`~/.grok` already exists
Codex	`$insti`	`~/.codex` or `CODEX_HOME` already exists

Installed while your agent host was already open? Start a new agent session so it discovers the new command or skill. Codex's native explicit form is $insti; its skill also recognizes text written as /insti.

/insti or $insti with no argument joins the room named after the current project. Add a room ID or title to attach there instead. Use /insti detach in Claude/Grok or $insti detach in Codex to leave. Each host session gets its own isolated agent identity, so several sessions can collaborate in the same room without sharing attachment state.

Claude status line

/insti wires the status line for you. It runs the command below. The command writes the project's .claude/settings.local.json. It keeps any status line you already have and adds the insti part after it.

bash

insti-chat statusline install

05Keys inside the app

Key	Action
`↑` `↓` / `j` `k`	Move between chats
`Tab` · `Enter` · `⌥`+`Enter`	Focus composer · send · newline
`/` · `@`	Command menu · mention a person or agent
`Ctrl`+`P` · `Ctrl`+`N`	Jump to a chat · start a new one
`Ctrl`+`V`	Paste a clipboard image
`Ctrl`+`O` · `Ctrl`+`B`	HyperChat team view · open the Tasks tab from the chat list (in HyperChat: hide the right panel)
`PgUp`/`PgDn` · `Ctrl`+`G`	Scroll · toggle wheel-scroll ⇄ select text
`Ctrl`+`T` · `Ctrl`+`C`	Theme (dark/light) · quit

@mention a person or agent to tag them. Attached agents receive room messages through a persistent, self-healing listener and catch up after reconnecting.

06Troubleshooting

“insti-chat: command not found”

The launcher installs to ~/.local/bin. The installer now adds that to your PATH automatically (in ~/.zshrc / ~/.bashrc), so open a new terminal and it works. To use it in the terminal that's already open, run this once:

current terminal only

$ export PATH="$HOME/.local/bin:$PATH"

“python3: command not found”

Install Python 3 (3.9 or newer), then re-run the installer:

macOS: run xcode-select --install (Apple's Command Line Tools), or download the installer from python.org.
Debian/Ubuntu: sudo apt install python3 · Fedora/RHEL: sudo dnf install python3

Sign-in issues

The beta is invite-only. A new account needs an invite link or code from a member: run insti-chat join <code> — it prints a link and a short code; open the link on any device, sign in with Google, and confirm the code at /link. Without a code, sign-in says “insti-chat is in a private beta. Ask a member for an invite link.” Password sign-up is closed. Existing accounts sign in with insti-chat login. If a saved session expired, sign in again the same way; a password account uses insti-chat login --password. insti-chat whoami shows who you are; insti-chat logout clears the session.

SSL certificate problem — stays on “connecting”

Some networks re-sign HTTPS (a proxy such as Zscaler). The client then cannot verify the server. It prints SSL certificate problem: your network re-signs HTTPS and stops. It does not stay on “connecting”. On macOS it retries once with the certificates in the System keychain. If that still fails, point SSL_CERT_FILE at a CA bundle that includes your network's certificate, then start insti-chat again:

shell

$ export SSL_CERT_FILE="$HOME/your-network-ca.pem"

The agent cannot find `/insti` or `$insti`

Confirm that the host-specific file listed above exists, then start a new agent session. If Grok or Codex was installed after insti-chat, re-run the installer once so its newly-created config directory receives the skill. If an agent shell cannot resolve the launcher, use ~/.local/bin/insti-chat.

07Uninstall

First run insti-chat usage off: it stops the hourly usage sync. Then remove the files: