goldengooseAI coding agent workspace

How It Works

gg Tools

The 3 built-in tools for messaging, team coordination, and background processes.

goldengoose exposes three small, high-signal tools to agent threads:

  • gg_message for direct messages and broadcasts.
  • gg_team for status, add, remove, and managed-worktree assignment.
  • gg_process for run, list, status, and cancel.

Tool cards appear in the timeline so you can inspect both the request and the result. Caller identity is supplied by the runtime. Agents never pass or select a team identifier.

Quick reference

  • gg_message
  • gg_team
  • gg_process

Coordination tools

gg_team status mode

Get the current status of every member in the persistent team. The result includes activity, recent team-message context, context-window headroom, logical managed-worktree state, and member provenance.

Call it with { "mode": "status" }.

Model-facing status requires the trusted caller to be a current member and fails closed for a teamless caller. The persistent shell itself can still be empty—with no members and no lead—but that unaffiliated state is observed through the desktop UI or no-ID Tauri singleton view, not by calling this tool from a teamless thread. The first member becomes lead. Removing the last member returns the same shell to that empty state.

gg_message

Send a direct message to an agent or broadcast to the caller’s current team.

Arguments

  • target (object, required), exactly one of:
    • { "kind": "agent", "agent_id": "careful_bamboo" } for direct delivery.
    • { "kind": "broadcast" } for the caller’s team.
  • message (string, required): non-empty text content.
  • image_paths (string[], optional): up to eight native image paths, attached in caller order.

Direct messages can reach another agent without shared membership. Broadcasts require the caller to be a current member and snapshot the current roster. Sender identity is trusted runtime context, not an argument.

{
  "target": { "kind": "agent", "agent_id": "careful_bamboo" },
  "message": "Please review this change."
}
{
  "target": { "kind": "broadcast" },
  "message": "The integration is ready."
}

gg_team management modes

Manage the persistent team in exactly one mode: add, remove, or assign a worktree. There is no create, delete, list, switch, or team-selection mode.

Who may change membership depends on Team Permissions:

  • The lead can always add or remove members.
  • Preferences can allow non-lead members to add or remove members, enabling deeper delegation.

Add mode

Set mode to add. { "mode": "add" } is a valid minimal add.

  • title (string, optional): role label such as Reviewer or Frontend.
  • prompt (string or null, optional): onboarding instructions.
  • image_paths (string[], optional): up to eight onboarding images in caller order.
  • model_preset (string or null, optional): a named Model Preset.
  • worktree_name (string or null, optional): a logical managed-worktree name.
  • creator_compaction_subscription (optional): auto by default, or unsubscribed to disable creator-scoped compaction notices for this member.

When worktree_name is present, the managed-worktree control plane creates it if it does not exist or reuses the existing named worktree automatically. A newly created worktree runs .agents/gg/worktree-init.sh before session creation when the script is present. See Configure: Worktree Init.

Remove mode

Set mode to remove.

  • remove_agent_ids (string[], required): one or more member agent IDs.
  • preserve_worktrees (boolean, optional): preserve managed worktrees that lose their final association.

Add and assign fields are rejected in remove mode.

Assign worktree mode

Set mode to assign_worktree.

  • assign_worktree (object, required):
    • agent_id (string, required): an existing idle member.
    • worktree_name (string, required): the named managed worktree.
    • preserve_previous_worktree (boolean, optional): preserve the previous worktree after the member moves.

Add and remove fields are rejected in assign mode. Assignment is fail-closed if provider rebinding, durable ownership, or worktree recovery cannot be proven.

Process tool

Process tools run long commands without blocking the conversation. The Process Manager captures bounded logs, tracks caller ownership, and injects a structured result into the owning thread when the command exits.

gg_process run mode

Set mode to run. The command is accepted immediately and returns a stable process_id while the scheduler starts it when capacity is available.

  • command (string, required): shell command to run.
  • cwd (string, optional): working directory; omitted uses current session context.
  • timeout_ms (integer, optional): maximum lifetime after launch; 0 disables the timeout.

Completion is pushed automatically. Do not poll after starting a command.

gg_process list mode

Call { "mode": "list" } to list queued and running processes across the caller’s workspace team.

gg_process status mode

Inspect one queued, running, or retained terminal process visible to the caller’s workspace team.

  • process_id (string, required): stable proc_... ID returned by run.

gg_process cancel mode

Request termination of a process started by the caller session.

  • process_id (string, required): stable proc_... ID returned by run.