Headmaster by GCAP Labs

Tools are what the agent uses to do things: search the web, run commands, read and edit files, remember, schedule tasks, drive a browser. Tools are grouped into toolsets, and you choose which toolsets are on for each place you use Headmaster (the terminal, a messaging app, and so on).

Toolsets

Category	Examples	What it does
Web	`web_search`, `web_extract`	Search the web and read pages.
Terminal and files	`terminal`, `process`, `read_file`, `patch`	Run commands and change files.
Browser	`browser_exec`, `browser_cdp`	Drive a real browser, with screenshots.
Media	`vision_analyze`, `image_generate`, `text_to_speech`	Look at images, make images, speak.
Planning and delegation	`todo`, `clarify`, `execute_code`, `delegate_task`	Plan, ask you questions, run code, hand work to sub-agents.
Memory	`memory`, `session_search`	Remember across chats and search past ones. See Memory.
Automation	`cronjob`	Create and manage scheduled tasks.
Connections	tools from MCP servers and plugins	Whatever you have connected. See Connections.

Common toolset names include web, search, terminal, file, browser, vision, image_gen, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, messaging and safe. Run headmaster tools to see the ones available to you.

Choosing which tools are on

Run the interactive screen:

headmaster tools

Or use the subcommands:

Command	What it does
`headmaster tools list`	Show every tool and whether it is on.
`headmaster tools enable <name>...`	Turn toolsets on.
`headmaster tools disable <name>...`	Turn toolsets off.
`headmaster tools --summary`	Print what is on for each platform.

Each command takes --platform to say where the change applies. The default is cli, the terminal.

Toolsets use plain names such as web or memory. A single tool from a connected MCP server is written server:tool, for example github:create_issue.

For one run only, pass the toolsets on the command line:

headmaster chat --toolsets "web,terminal"

Changing tools while a chat is open takes effect in your next chat, not the current one. This keeps the running conversation stable.

Where commands run

The terminal tool can run commands in different places. Pick one with terminal.backend in your config:

Backend	What it is
`local`	Your own computer. The default.
`docker`	An isolated container.
`ssh`	A remote server, so the agent stays away from its own files.
`modal`, `daytona`, `vercel_sandbox`	Cloud sandboxes.

terminal:
  backend: local
  cwd: "."
  timeout: 180

Your config file lives in your Headmaster home folder. Run headmaster config path to print its location, or headmaster config edit to open it.

With the Docker backend, one long-lived container serves the whole session, so packages you install and folders you change carry over from one command to the next. To keep real API keys out of that container, see Egress proxy.

Background processes

The agent can start a long command in the background, such as a test run or a dev server, then check on it, read its output, send it input or stop it. A command that ends with & is treated as a background command and goes through the same approval checks.

Shell startup files

The agent runs your shell without a terminal and without you at the prompt. Slow or interactive lines in .bashrc or .zshrc (version managers, prompts, tmux attach, banners) can slow every command or make it hang. Keep heavy setup below the usual guard that returns early in non-interactive shells:

case $- in
  *i*) ;;
  *) return;;
esac

If commands hang for the agent but work in your own terminal, check your shell startup first.

Approvals still apply