@nia-teams/agy-bridge
v0.2.0
Published
Connect Google Antigravity CLI to Nia Teams GroupChats and TaskBar approvals through ACP
Readme
@nia-teams/agy-bridge
English | 简体中文
Connect Google Antigravity CLI (agy) on your computer or server into Nia Teams as an Agent in Nia Teams with two-way communication.
npm install -g @nia-teams/agy-bridge
nia-agy pair --name 'My Antigravity'
nia-agy start --cwd "." --daemonAI coding agents: load skills/nia-teams-agy/SKILL.md; installed path: node_modules/@nia-teams/agy-bridge/skills/nia-teams-agy/SKILL.md.
For connect --invite-code, see invite-code onboarding.
1. Product Overview & Collaboration Model
The bridge drives Google Antigravity CLI through newline-delimited JSON-RPC 2.0 over agy acp stdio. One daemon retains one ACP child with a separate session per GroupChat. Teammates submit tasks, follow live activity, and approve tool execution through TaskBar.
- Create and bind in one flow, without precreating an Agent or distributing static keys: Start pairing on the Google Antigravity host, sign in to Nia Teams from a browser on any device, create the external Agent, and bind the host public key. The private key stays on the host.
- Live presence and per-GroupChat conversation history: The composer activity strip shows disconnected, idle, executing, or waiting state. Each chat retains its own Antigravity session for later turns; the host workspace is shared.
- TaskBar approvals and mid-turn tools: Permission requests display tool names and arguments for Agent-member approval; model tools publish progress and read GroupChat history.

| Concern | Local host | This package | Nia Teams |
| --- | --- | --- | --- |
| Agent runtime | Models, tools, workspace, Antigravity sign-in | Chat-to-runtime sessions, queries, cancellation | External Agent identity and scope |
| Connection and auth | Local Node process and Google Antigravity CLI (agy) | Ed25519 credentials, WebSocket, reconnection | Browser pairing, challenge/lease, delivery |
| Conversation | Inference turns and local tasks | Prompt formatting, session resume, publication | Timeline, members, activity |
| Approval and safety | Antigravity tool permissions and execution scope | Display tool permission requests as TaskBar cards, verify RS256, match pending actions | TaskBar, Agent membership, signed approvals |
2. Five-Step Quick Start
Prerequisites: Node.js 20+, a signed-in local agy CLI, and a Nia Teams account. No external Agent needs to be created in advance.
Step 1: Install the bridge and prepare the host
Requires Node.js 20+ and a locally installed, authenticated Google Antigravity CLI. The protocol targets captured agy 1.4.10 / Antigravity ACP Server 1.5.4 traffic through a persistent agy acp service, not screen scraping or an interactive PTY.
agy --version
npm install -g @nia-teams/agy-bridgeRun the installed agy in a local interactive terminal under the same OS user to complete its account sign-in and verify project access. Nia pairing binds an external Agent identity; it does not replace Google Antigravity authentication.
Executable precedence is --agy-bin, AGY_BIN, agy on PATH, then ~/.local/bin/agy, ~/.antigravity/bin/agy, /opt/homebrew/bin/agy, and /usr/local/bin/agy. An invalid explicit selection fails rather than choosing an unrequested installation.
The daemon starts <agy> acp; stdout/stdin carry newline-delimited JSON-RPC 2.0 and stderr carries diagnostics to the terminal or daemon log. ACP initialization negotiates protocolVersion: 1. GroupChat MCP tools arrive in the session descriptor, without adding MCP configuration to the user's project.
Step 2: Pair the host and create an Agent in the browser
nia-agy statusCheck the saved Agent:, Server:, and config directory first. Reuse an existing intended binding; pair for first setup or an intentional Agent change:
nia-agy pair --name 'My Antigravity'The terminal generates an Ed25519 keypair locally and prints a pairing link valid for 10 minutes:
Pairing code: A7F39C2B
Open this URL to create or bind your external Agent:
https://nia-teams.com/bridge/agent-pair/A7F39C2BOpen the link in a browser on any device and sign in to Nia Teams:
- Keep Create external Agent selected, enter the Agent name, and choose Personal Assistant or an organization you belong to. The creator becomes the Agent’s
owner. - Click Create & Connect. To migrate an existing Agent, select Rebind existing external Agent as its
owneroradmin, select the target, and confirm the new binding; the old host disconnects.

Wait for Paired: <Agent name> (@external-...) and exit code 0 in the terminal. After proving private-key possession, the host saves credentials.json under ~/.config/nia-teams-agy/, using POSIX 0700 directory and 0600 file modes. Pairing is independent of the project directory; later startup reads the same config directory.
nia-agy statusstatus shows the saved identity and server; verify the running connection through the daemon and GroupChat presence in the next steps.
Step 3: Start the daemon
For manual operation, run in an interactive foreground terminal with logs visible:
nia-agy start --cwd /path/to/workspaceFor detached operation or local AI setup, launch in the background:
# Portable background launch (Windows PowerShell/CMD/Git Bash, macOS, Linux):
nia-agy start --cwd "/path/to/workspace" --daemon
# POSIX-only alternative (not Windows):
nohup nia-agy start --cwd /path/to/workspace > /tmp/nia-agy.log 2>&1 &
sleep 2
cat /tmp/nia-agy.log
pgrep -af '[n]ia-agy.*start'Startup opens an authenticated connection to wss://nia-teams.com/ws/agent-bridge. Network interruptions reconnect with exponential backoff. Run one bridge per paired config directory. On macOS, caffeinate prevents system sleep while a task runs and is released when the task finishes.
GroupChats have separate model contexts but share the files, repository, and local tools under --cwd. Credentials and session records are stored separately in credentials.json and threads.json.
ACP sessions, streaming replies, and concurrent chats
Core SessionHost / ThreadMapStore stores each chat's ACP sessionId in ~/.config/nia-teams-agy/threads.json. A later turn calls session/resume with the same cwd and a fresh MCP turn scope. An explicit resume JSON-RPC error permits session/new and mapping replacement; transport failures, child exit, and timeouts do not replay the task.
New sessions append GroupChat collaboration instructions. Optional session/set_mode and session/set_model requests precede session/prompt; both new and resumed sessions apply explicit configuration. Modes are default, accept-edits, auto, and plan; models come from Antigravity account availability.
Streamed output stays on the host. Thinking and tool updates sync live activity status; GroupChat replies are published through send_message.
SessionHost serializes turns within a GroupChat while different ACP sessions can run concurrently in the same child. Client requests match response IDs; notifications and permission requests route by params.sessionId. Server request IDs remain independent even when they collide with client request IDs.
Abort sends session/cancel. If the request does not settle within two seconds, the daemon terminates the child and escalates SIGTERM to SIGKILL when necessary. Other active turns in that child fail without replay. Later tasks initialize a new child generation and resume saved Antigravity sessions where supported.
Step 4: Invite the external Agent and verify presence
Click Go to GroupChat on the pairing confirmation page, or open Nia Teams Messages in the left navigation:
- Start a new conversation: Click the external Agent avatar in the quick strip above the chat list; expand the strip when it overflows. The
+at its right creates a multi-person GroupChat. - Invite into an existing chat: Open the GroupChat, click
+beside member avatars in the upper-right header, select the Agent in Invite existing members, and click Done. - Invitation roles: Organization members can invite organization-affiliated Agents. The creator initially invites a Personal Assistant; other members of that GroupChat may then invoke it.
Watch the activity strip above the composer: red Disconnected changes to Idle / Ready when the host connects. Match the chat Agent to the identity shown by status, then send a short task to verify a reply.
Step 5: Mention the Agent and manage its lifecycle
Type @ in the composer and select the external Agent. Its activity becomes executing while the task runs, and replies appear in GroupChat. Incoming prompts include title, URL, members, sender, messages, and attachment transcripts. Notify a person with their ID: <mention userId="24-hex-id" />, rather than plain @Name.
- Temporary offline: Press
Ctrl+Cin the foreground terminal or send SIGTERM to the recorded background PID. Presence becomes Disconnected. Restart loads existing credentials and session mappings. - Move or unpair a host: An Agent
owner/adminpairs the new host and selects Rebind existing external Agent. To unpair only, use Apps → Agent Settings → Unpair host in a shared chat’s upper-right header. Rebind/unpair incrementskeyGenerationto invalidate old host credentials and disconnects the old host with4401. A competing connection taking over the same identity closes the old connection with4409, stopping reconnects. - Deactivate and archive: When no other contacts remain and you are the sole
owner, use Agent Settings → Deactivate “Agent name” → Confirm. Archiving revokes the Agent’s online connections.
Troubleshooting
- Pairing request expired: Links last 10 minutes. Run
nia-agy pairagain on the host and open the new URL. - status fails: Check OS user, config directory, file permissions, and completed pairing. A locally operated re-pair may be needed after rebind/unpair; diagnose network and origin failures before replacing credentials.
- Chat stays red Disconnected: Inspect the daemon,
/tmp/nia-agy.log, saved Server, and chat Agent identity. Check for another process using the credentials. Close code4409means another connection took over. - Antigravity login or startup fails: Run the Google Antigravity CLI (
agy) under the same OS user, sign in, and verify Node version and binary selection. Antigravity sign-in and Nia pairing are separate. - Execution without a reply: Check the daemon log for runtime or publication errors, and verify the turn was not canceled or interrupted by session rotation.
3. CLI, Environment & Package Exports
nia-agy pair [--server-url <origin>] [--config-dir <dir>]
[--name <label>] [--label <label>] [--timeout-ms <ms>]
nia-agy status [--config-dir <dir>]
nia-agy start [--cwd <dir>] [--config-dir <dir>] [--model <model>]
[--mode default|accept-edits|auto|plan] [--sandbox]
[--full-auto] [--bypass-approvals] [--agy-bin <path>]
nia-agy --help--server-url: Pairing origin; precedence is flag,NIA_TEAMS_URL, thenhttps://nia-teams.com. Later connections use the saved origin.--config-dir: Explicit path overridesNIA_AGY_CONFIG_DIR, then defaults to~/.config/nia-teams-agy. Use the same directory for pair, status, and start.--name/--label: Pairing host label; defaults toagy@<hostname>. When both are present,--namewins. The browser can choose a different Agent display name.--timeout-ms: Pairing wait limit; defaults to 600000 milliseconds with two-second polling. Must be positive.--cwd: Project directory; defaults to the current directory and resolves to an absolute path. GroupChats share this workspace.--model: Select an Antigravity-available model throughsession/set_model; no account model list is hardcoded.--mode: Configuresession/set_modewithdefault,accept-edits,auto, orplan; agy interprets execution policy.--sandbox: Boolean flag passed toagy acp, not the string-valued Codex sandbox option.--full-auto/--bypass-approvals: Skip bridge confirmation and pass--dangerously-skip-permissions; default an unspecified mode toauto. An explicit mode wins.--agy-bin/AGY_BIN: Select the local executable; otherwise use PATH and common installation paths.--help/-h: Show command overview; no command also shows help.
Exports and embedding
| Entrypoint | Purpose |
| --- | --- |
| nia-agy | Pairing, identity inspection, and daemon |
| AgyRunner | Own the ACP child with run(context) and close() |
| createAgyRunner | Create a core TurnRunner with asynchronous close() |
| resolveAgyBinary | Resolve explicit selection, environment, PATH, and installation locations |
| AcpClient / AcpRpcError | Multiplex requests, notifications, server requests, and explicit RPC errors |
| SessionHost | Reuse core queues, private state, approvals, and cancellation |
| AgyOptions / AgyMode / AcpMessage | TypeScript runner, mode, and message types |
| dist/**/*.d.ts | Exact method signatures and configuration |
Public export-map entries are . and ./package.json. For embedding, pass createAgyRunner(options) to core runSessionDaemon and await runner.close() in finally. Do not maintain another durable session mapping outside core. Frames, timeouts, and cancellation are specified in docs/SPECIFICATION.md.
4. Approvals, GroupChat Tools & Security Boundaries

1. Signed TaskBar approval flow
- An active-session
session/request_permissioncreates a TaskBar card bound to its ACP session, toolCall, options, and current turn. - Nia Teams checks that the clicker is an active Agent
owner,admin, ormember, then signs_meta["nia/confirmationToken"]and returns it withcard.action. - The host uses
@nia-teams/mcp-sdk/authand keys from${issuer}/oauth2/jwksto verify RS256 signature, issuer,aud: nia-teams-workload, lifetime, service identity, andhuman_confirmed: true. - It checks
context_server: agent-bridge,context_tool: agy.approval, canonical-JSON argument SHA-256 digest, andconfirmation_card_id === cardId. Expected values come from the locally stored request, not chat text. - A valid result allows only that request. Missing/invalid tokens, dismissal, expiry, and cancellation deny it. Pending cards expire after five minutes by default.
ACP replies contain outcome: { outcome: "selected", optionId }. Approval selects only allow_once; denial selects reject_once. Missing safe options return cancelled rather than upgrading a one-shot verdict to allow_always. Unknown or finished sessions cannot be approved, including in full-auto mode.
2. GroupChat tools, messages, and native mentions
send_message({ content })publishes Markdown or Rich HTML to the current GroupChat for progress or questions. All replies require an explicit send; turn-end text stays private.chat_history({ limit?, offset? })paginates history;limitdefaults to 50 in 1..100, andoffsetdefaults to 0 and must be non-negative. The host supplies the Nia session; the model does not choose a chat ID.- GroupChat tools belong to the active turn. After interruption or Nia session rotation, old requests cannot publish into the new GroupChat session.
The bundled MCP service uses a temporary per-turn credential to access the current GroupChat; the credential expires when the turn ends. MCP helpers do not read the Nia Teams private key. See the protocol specification for messages and request scope.
Incoming prompts list Members: Alice (<userId>), ...; each message includes sender ID, timestamp, message ID, reply reference, and attachment transcripts. Generic headers may appear as [chat:<chatId>] Alice (<userId>): ..., or structured channels may expose senderId; raw bridge frames use messages[].authorId. Use <mention userId="24-hex-id" /> with a received sender/member ID for native notifications.
3. Roles and local execution boundaries
- Chat members may invoke an Agent; rebinding/unpairing requires its
owner/admin, and archiving follows the sole-owner rule. Card approval additionally requires active Agent membership. - Human membership is distinct from workload
sub,org:*, androle:*claims. Text saying “approved” creates neither a signed confirmation nor local execution permission. - Ed25519 private keys stay in the config directory. Loading validates permissions, symlinks, and keypair consistency; keep credential files out of project repositories and logs.
- Publications retain idempotency keys in a process-local FIFO during transient outages, with 256 entries / 16 MiB admission and a 512 KiB frame limit. Process exit does not persist unsent queue entries.
- Connections use 20-second heartbeat, 60-second inbound idle timeout, and jittered backoff reconnects;
4409terminates a superseded connection. Model session isolation is not filesystem or OS isolation.
5. Development, Trademark & License
npm install
npm run build
npm run typecheck
npm test
npm pack --dry-runUpdate both READMEs, the shipped skill, declarations, and protocol specification when changing runtime interfaces or Antigravity contracts.
Google and Antigravity are Google product names or trademarks. This package is maintained by Nia Teams and is not affiliated with Google.
MIT © Nia Teams
