@dhf-claude/grix

Connect local Claude Code to Grix so you can use Claude from the Grix website or mobile PWA.

Before You Start

Make sure this machine already has:

• Claude Code installed, and the claude command works in your terminal
• A valid Claude login on this machine
• The 3 connection values from the Grix console:
  • wsUrl
  • agentId
  • apiKey

If Claude is not logged in yet, run:

claude auth login

Quick Start

1. Install the package

npm install -g @dhf-claude/grix

2. Install and start the background service

grix-claude install --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>

This will:

• Save your connection settings locally
• Install a user-level background service
• Start the local service immediately

Supported background service managers:

• macOS: launchd
• Linux: systemd --user
• Windows: Task Scheduler

3. Start a Claude session from Grix

Open the related Grix private chat and do either of these:

• If Grix shows an open-workspace card, use that card
• Or send:

/grix open <your_working_directory>

The background service will start or resume the Claude session for that directory.

Important:

• One Grix private chat is bound to one working directory
• After a chat is bound, that same chat cannot switch to another directory

Commands You Will Usually Use

grix-claude status
grix-claude restart
grix-claude stop
grix-claude start
grix-claude uninstall

• status: show service and connection status
• restart: restart after config changes or troubleshooting
• stop: stop the background service
• start: start it again
• uninstall: remove the background startup entry

Commands in Grix Chat

Use these in the related Grix private chat:

| Command | Purpose | | --- | --- | | /grix open <working_directory> | Start or resume a Claude session for that directory | | /grix status | Show current session status | | /grix where | Show the current bound directory | | /grix stop | Stop the current Claude session |

Commands You Run Inside Claude

If you are already inside the Claude terminal session, use the same /grix ... command family:

| Command | Purpose | | --- | --- | | /grix status | Show current connection and status hints | | /grix access | Show current access control state | | /grix access pair <code> | Approve a pairing code | | /grix access deny <code> | Reject a pairing code | | /grix access allow <sender_id> | Add a sender to the allowlist | | /grix access remove <sender_id> | Remove a sender from the allowlist | | /grix access policy <allowlist\|open\|disabled> | Change access policy |

Access changes should be typed by you in the Claude terminal, not driven by messages from other people in chat.

Approvals and Questions

When Claude needs confirmation or needs more information, Grix will show interactive cards.

• For approvals, click the card buttons to approve or reject
• For questions, fill the card and submit
• For browser-based sign-in steps, open the link from the card and then return to the card to finish or cancel

These cards are the normal user flow. Legacy text fallback commands are not part of normal use anymore.

Temporary Foreground Run

If you do not want to install a background service, you can run in the foreground:

grix-claude --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>

If config is already saved locally, you can also just run:

grix-claude

File Sending

Claude can send local files back to Grix.

• Maximum size per file: 50MB
• Common image, video, document, archive, and text formats are supported

Troubleshooting

Check service status

grix-claude status

If Claude login expired

claude auth login

Then retry from Grix.

Session log path

Each Grix chat session has its own log file:

~/.grix-claude/sessions/<aibot_session_id>/logs/daemon-session.log

This log is the best place to check when:

• Claude does not reply
• Claude keeps restarting
• Messages are not delivered back to Grix

CLI Reference

grix-claude install [options]
grix-claude start [options]
grix-claude stop [options]
grix-claude restart [options]
grix-claude status [options]
grix-claude uninstall [options]
grix-claude [options]

Recommended default:

• Use install for normal long-running use
• Use plain grix-claude only for temporary foreground runs or debugging

Common Options

--ws-url <value>      Grix Agent API WebSocket URL
--agent-id <value>    Agent ID
--api-key <value>     API Key
--data-dir <path>     daemon data directory
--chunk-limit <n>     max text chunk length
--show-claude         show Claude in a visible Terminal window for debugging
--no-launch           validate and save config only, do not start daemon
--help, -h            show help

Notes:

• On first install or first foreground run, pass the full connection parameters
• If config is already saved locally, you can omit connection parameters
• Use --data-dir if you want a separate data directory for another environment
• --show-claude currently supports macOS Terminal only

For Developers

If you are changing code in this repository:

npm run dev:build

This keeps local build artifacts up to date.

To start grix-claude against the local development environment:

npm run dev

This uses a separate local data directory so it does not overwrite the production daemon state.

To start grix-claude against the current production environment:

npm run prod

This uses the standard production daemon state directory.

To run the daemon locally in another terminal:

npm run daemon

If you want npm run daemon to read connection values from environment variables:

GRIX_CLAUDE_ENDPOINT='ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<agent_id>' \
GRIX_CLAUDE_AGENT_ID='<agent_id>' \
GRIX_CLAUDE_API_KEY='<api_key>' \
npm run daemon -- --no-launch

GRIX_CLAUDE_WS_URL is still supported. If both are provided, the daemon prefers the newer environment variable values.

统一出站端到端测试

统一出站 E2E 测试代码在 AIBot 后端仓库中。测试会启动本适配器作为真实子进程，连接到真实后端，通过后端发送消息，验证 Claude 的回复能完整走通协议链路返回。

前置条件：

• AIBot 后端已启动（在后端仓库执行 make dev-up）
• Claude Code CLI 已安装且已认证（claude auth login）
• 本仓库已构建（npm run build）

运行：

cd <aibot-backend-repo>

GRIX_ADAPTER_E2E=1 \
GRIX_ADAPTER_CLAUDE_AGENT_ID=<agent-id> \
GRIX_ADAPTER_CLAUDE_API_KEY=<api-key> \
GRIX_ADAPTER_E2E_USER_ACCOUNT=<account> \
GRIX_ADAPTER_E2E_USER_PASSWORD=<password> \
go test ./e2e/ -run TestLiveAdapterClaudeRoundtrip -v -timeout 10m

测试流程：启动 node dist/daemon.js --ws-url <url> --agent-id <id> --api-key <key>，等待适配器上线，打开会话，发送带 marker 的消息，验证 Claude 的回复包含 marker。