Skip to main content
goldengoose exposes a small set of built-in MCP tools that agent threads can call. These tools are intentionally limited and high-signal:
  • 3 Team tools: coordinate a team (status, messaging, membership)
  • 3 Process tools: run and monitor background commands (run, status, kill)
In the UI, tool calls show up as tool cards in the timeline so you can see what happened and what output the agent saw.

​
Quick reference

​
Team tools

  • gg_team_status
  • gg_team_message
  • gg_team_manage

​
Process tools

  • gg_process_run
  • gg_process_status
  • gg_process_kill

​
Team tools

​
gg_team_status

Get current status for each team member. Arguments
  • team_id (string, required): the team you want status for.

​
gg_team_message

Send a message scoped to a team. This can be either:
  • a direct message (one recipient), or
  • a broadcast (everybody on the team).
Arguments
  • team_id (string, required): the team to send into.
  • recipient_agent_id (string, required):
    • set to an agent id for a direct message, or
    • set to broadcast to send to the whole team.
  • message (string, required): the text content.
  • image_paths (string[], optional): paths to images on disk to attach after the text message (advanced).

​
gg_team_manage

Add or remove team members. This tool supports two modes:
  • Add member: omit remove_agent_ids
  • Remove member(s): set remove_agent_ids to a non-empty list of agent ids
Who can use it depends on your team permissions:
  • By default, membership changes are lead-driven.
  • If you enable Preferences → General → Team Permissions, non-lead members can also add/remove members via gg_team_manage(...). That’s what unlocks “delegation to delegation” (a member can add another member to take on a sub-task).
Arguments
  • team_id (string, required)
  • Add-member options:
    • title (string, optional): a human-readable role label (for example Reviewer, Docs, Frontend).
    • prompt (string or null, optional): extra onboarding context for the new member.
    • image_paths (string[], optional): image files to attach to onboarding in-order after the onboarding text.
    • model_preset (string or null, optional): a named preset (see Model Presets).
    • worktree_name (string or null, optional): native worktree slug. When provided, gg derives branch/worktree/cwd from runtime settings. For create-new bootstrap timing and failure behavior, see Configure: Worktree Init.
    • use_existing_worktree (boolean, optional): when true, worktree_name is treated as an existing worktree to reuse instead of creating a new one.
    • unsubscribe_from_compaction_notifications (boolean, optional): when omitted/false, the agent that adds the member will receive a timeline notice if that member’s chat is compacted. Set this to true if you don’t want compaction notices.
  • Remove-member options:
    • remove_agent_ids (string[], required for remove mode): list of agent ids to remove.
Validation rules
  • remove_agent_ids switches the call into remove mode and must contain at least one id.
  • In remove mode, add-only fields are rejected: title, prompt, image_paths, model_preset, worktree_name, use_existing_worktree, unsubscribe_from_compaction_notifications.
  • use_existing_worktree=true requires a non-empty worktree_name.
Worktree behavior in add mode Think about add mode as three simple cases:
  • No worktree_name: gg does not create a new native worktree.
  • worktree_name set, with use_existing_worktree omitted or false: gg creates a new native worktree with that name. If .agents/gg/worktree-init.sh exists in the new checkout, gg runs it before the session starts. See Configure: Worktree Init.
  • worktree_name set, with use_existing_worktree=true: gg reuses an existing native worktree with that name. The worktree must already exist, and the init script does not run in this path.

​
Process tools

Process tools are how agents run long commands without blocking the conversation. They’re backed by the Process Manager, which:
  • captures logs with bounds,
  • tracks ownership and status,
  • and injects results back into the owning thread when the command exits.
For deeper behavior and safety policy, see:

​
gg_process_run

Run a shell command in the background and return immediately with a pid and process metadata. Arguments
  • command (string, required): the shell command to run.
  • cwd (string or null, optional): working directory (when omitted, uses the session’s current context).
  • timeout_ms (integer, optional): maximum lifetime in milliseconds; 0 disables timeout.
What happens next
  • The command runs in the background.
  • You can watch it in the Process Monitor and/or query it with gg_process_status.
  • When it exits, gg injects a structured completion result back into the thread that started it.

​
gg_process_status

Inspect a background process. Arguments
  • pid (integer, optional): process id to inspect.
    • If omitted, gg lists caller-owned running processes (team-scoped when in a team).
  • head_lines (integer, optional): how many lines from the start of logs to include.
  • tail_lines (integer, optional): how many lines from the end of logs to include.

​
gg_process_kill

Request termination of a background process started by the caller session. Arguments
  • pid (integer, required)