Groupchat

Last updated: August 30, 2026

Groupchat is the remote agent client for Groupchat. Keep it running on a machine that has codex installed, and Codex responds to @mentions from your Groupchat workspace — running locally on that machine and streaming its work back into the conversation.

Install

npm install -g groupchat

The npm package installs a small launcher plus a platform-specific binary package. Current binary targets are:

• macOS arm64 and x64
• Linux arm64 and x64
• Windows x64

Start

groupchat

On first launch, Groupchat opens a browser login flow. Auth tokens are stored in your OS keychain, and your selected org is stored under ~/.config/groupchat/.

Once you're logged in (and have picked an org, if you belong to several), Groupchat shows a compact control panel and goes online as a remote:

• It advertises the session as available for remote agent runs.
• When someone @mentions an agent in your workspace, it runs Codex locally in the directory you launched from (or in GROUPCHAT_WORKSPACE_DIR, if set).
• The response streams back into the conversation as it happens, and follow-up thread replies continue the same Codex conversation.

The panel shows connection status, whether codex is available on PATH, active runs with live progress, and recent run history.

Codex and Claude sessions stay available for five minutes after a successful turn, so nearby follow-ups can reuse the running process. Later replies resume the saved conversation. See remote session lifecycle for limits and implementation details.

Keyboard Shortcuts

| Shortcut | Action | | --- | --- | | Ctrl+O | Log out. | | Ctrl+C twice | Exit the app. |

Configuration

Groupchat uses production services by default:

• Console: https://app.groupchatty.com
• WebSocket: wss://api.groupchatty.com/socket

For development or staging, override them with environment variables:

GROUPCHAT_CONSOLE_URL=http://localhost:4000 \
GROUPCHAT_WS_URL=ws://localhost:4000/socket \
groupchat

Useful environment variables:

| Variable | Purpose | | --- | --- | | GROUPCHAT_CONSOLE_URL | Browser login and HTTP API base URL. | | GROUPCHAT_WS_URL | Phoenix socket URL. | | GROUPCHAT_PROFILE | Override the keychain/config profile, useful for multiple test users. Dev launches default to dev; production keeps the unprofiled store. | | GROUPCHAT_DEBUG=1 | Enable debug logging. | | GROUPCHAT_DEBUG_FILE | Override the debug log path. Defaults to .logs/tui-debug.log. | | GROUPCHAT_DEBUG_STDERR=1 | Also write debug logs to stderr. | | GROUPCHAT_WORKSPACE_DIR | Run agents in this directory instead of the one you launched from. ~ is expanded; a bad path exits with an error. |

Development

This package is the OpenTUI/Solid terminal client.

bun install
bun run dev                # watch mode
bun run dev:user2          # watch mode with GROUPCHAT_PROFILE=user2
bun run dev:debug          # debug log at .logs/tui-debug.log
bun run dev:debug:watch    # debug logging + watch mode
bun run dev:debug:console  # debug logging + OpenTUI console
bun run build              # production bundle + current-platform binary
bun run build --all        # production binaries for every supported target
bun run start              # run dist/index.js after a build
bun run typecheck          # TypeScript check
bun test ./test            # test suite
bun run test:watch         # watch tests
bun run test:update-snapshots

The build writes standalone binaries under npm/<platform>-<arch>/bin/. The published groupchat package delegates to the matching @groupchat-cli/<platform>-<arch> optional dependency.

Running against a different repo

Dev runs must start in tui/ — that is where bunfig.toml (which preloads the Solid JSX transform), .env, and node_modules resolve from. But the working directory is also where agent runs execute, so a plain bun run dev points agents at tui/ itself.

GROUPCHAT_WORKSPACE_DIR separates the two. Set it and the app chdirs at startup, after bunfig.toml and .env have been read:

GROUPCHAT_WORKSPACE_DIR=~/code/groupchat-main bun run dev

Or put GROUPCHAT_WORKSPACE_DIR=~/code/groupchat-main in tui/.env and plain bun run dev picks it up. One chdir moves everything downstream: the workspace label in the web status pill, the Claude and Codex run directories, and the Codex sandbox's writable root.

The old chat UI

Earlier versions of this package were a full terminal chat client (channels, DMs, presence, inline /claude and /codex agents, local ! shell commands). That UI was retired when the remote agent client became the product; the web app is the chat surface now. The code is preserved under archived/chat-ui/ (excluded from the build, typecheck, and tests) — see archived/chat-ui/README.md for what's there and how to resurrect it.

Contributing

Contributions are welcome for new harness integrations and terminal UX improvements.

Questions: svapnila at gmail dot com

License

AGPL-3.0-or-later