Terminal client
An interface built with Ink, which is React rendered in the terminal. Rooms, a list of who is online, a scrollable history and a stable colour per user.
Real-time chat, without
leaving the terminal.
hackerchat is a chat client that runs in the terminal, a lean WebSocket server and a JavaScript SDK. Start the server, join a room and talk straight from your shell, or from any interface that speaks WebSocket.
$
Three parts, one protocol.
Client, server and SDK exchange JSON frames over WebSocket. Each part is its own repository, and any of them can be swapped for an implementation of your own.
WebSocket server
A Node.js hub that creates rooms on demand and routes messages between connected clients. No database, no sign-up, no state outside memory.
JavaScript SDK
A client for the browser or Node, with optional React bindings. Wires any interface to the server in a few lines.
The protocol on the wire
Every message is a JSON object with an event and a payload. Four events cover everything: joining a room, sending a message, receiving the user list and hearing when someone comes or goes.
{ "event": "joinRoom",
"message": { "userName": "alice",
"roomId": "general" } }
{ "event": "message",
"message": "hello, world" }{ "event": "updateUsers",
"message": [{ "id": "…", "userName": "alice" }] }
{ "event": "newUserConnected",
"message": { "id": "…", "userName": "alice" } }
{ "event": "message",
"message": { "userName": "alice",
"message": "hello, world" } }
{ "event": "disconnectUser",
"message": { "id": "…", "userName": "alice" } }Running in two terminals.
The public server has been retired. Clone the server, run it locally and point the client at it. It takes under a minute.
Requires Node.js 24 or newer.
Start the server
Clone the repository and run it in development mode. It listens on port 9898 by default; set PORT to change that.
terminal 1 git clone https://github.com/matheussartori/hackerchat-server.git cd hackerchat-server npm install npm run dev # listening on ws://0.0.0.0:9898Connect a client
In another terminal, run the client with npx, nothing to install. The --username and --room flags are required, and --hostUri points at your server.
terminal 2 npx @matheussartori/hackerchat-client \ --username alice \ --room general \ --hostUri ws://localhost:9898Chat
Open a third terminal with a different username, or join from the playground at the bottom of the page, and watch messages arrive in real time.
terminal 3 npx @matheussartori/hackerchat-client \ --username bob \ --room general \ --hostUri ws://localhost:9898
Prefer a shorter command?
Install the client globally and call hackerchat directly.
npm install -g @matheussartori/hackerchat-client
hackerchat --username alice --room general --hostUri ws://localhost:9898Flags, shortcuts and variables.
Everything the client and the server accept, in one place.
| flag | description | usage |
|---|---|---|
--username | Display name shown in the room. | required |
--room | Room to join. Created if it does not exist yet. | required |
--hostUri | WebSocket URL of the server, with ws:// or wss://. Without it the client tries the old public address, which has been retired. | recommended |
| key | action |
|---|---|
| Enter | Send the message. |
| PgUp / PgDn | Scroll the history one page at a time. |
| Ctrl+U / Ctrl+D | Scroll the history one line at a time. |
| Home / End | Jump to the oldest message or back to the newest. |
| Esc / Ctrl+C | Exit the client. |
| variable | default | description |
|---|---|---|
PORT | 9898 | TCP port the server listens on. |
LOG_LEVEL | error | Minimum log level: debug, info, warning or error. |
Three repositories, two npm packages.
All TypeScript, all MIT. The server is not published to npm: clone it and run it.
Repositories on GitHub
Packages on npm
- @matheussartori/hackerchat-client (opens in a new tab)v1.0.2The terminal client, ready to run with npx.
npx @matheussartori/hackerchat-client - @matheussartori/hackerchat-js-sdk (opens in a new tab)v1.0.0The SDK, with exports for plain JavaScript and for React.
npm install @matheussartori/hackerchat-js-sdk
Try the SDK in the browser.
This section uses @matheussartori/hackerchat-js-sdk to connect to a hackerchat server. Start a local server, or enter the address of your own, and join a room.
import { useHackerchat } from '@matheussartori/hackerchat-js-sdk/react'
const { status, users, messages, sendMessage } = useHackerchat({
url: 'ws://localhost:9898',
userName: 'alice',
roomId: 'general',
})