AI Agents

Agents provision worktrees,
not just query them.

The MCP server exposes the full GTL toolset: create worktrees, allocate resources, wire up cross-repo dependencies, and control the dev server. AI agents work with real allocations instead of guessing.

Agents don't know about your environment

Your AI agent creates a worktree and tries to start the server. It doesn't know about port allocation, database cloning, or env files.

agent without treeline

agent $ git worktree add ../fix-bug fix-bug

agent $ cd ../fix-bug && npm start

Error: EADDRINUSE :::3000

# Agent tries a random port...

agent $ PORT=4567 npm start

Warning: DATABASE_URL not set

# Agent guesses at database names...

agent $ createdb fix_bug_dev

# Works sometimes. Breaks often.

One MCP call provisions everything

The new tool creates the worktree, allocates ports, clones the database, writes the env file, and returns structured JSON with everything the agent needs.

MCP tool call 
tool: new
args:
  branch: fix-auth-bug
  base: main
response 
{
  "worktree": "/code/myapp-fix-auth",
  "branch": "fix-auth-bug",
  "ports": [3010],
  "database": "myapp_dev_fix_auth",
  "url": "https://myapp-fix-auth-bug.prt.dev"
}

What this makes possible

The declarative config and a git hook (installed by gtl install) do the heavy lifting. The MCP server is how agents execute provisioning and stay informed about what's running.

Agents provision full environments

The new and setup tools create worktrees with allocated ports, cloned databases, and resolved env files. One tool call, complete environment.

Agents wire cross-repo dependencies

The link tool overrides resolution so {resolve:api} points to a specific branch. env_sync and restart apply the change.

Multiple agents, no collisions

Each worktree stays isolated: its own ports, database name, and supervisor socket. An orchestrator running three agents in parallel reads deterministic state via status or list.

Three lines in your editor config

MCP config (any MCP-compatible editor) 
{
  "mcpServers": {
    "gtl": {
      "command": "gtl",
      "args": ["mcp"]
    }
  }
}

The agent can call new, setup, link, start, and status as structured tool calls. No shell commands, no output parsing.

Full toolset

Query, provision, link, and control. Everything the CLI can do, agents can do via MCP.

Provisioning tools

Create worktrees, allocate resources, and manage configuration. These are the heavy lifters.

new
Create worktree and run full setup in one step
setup
Allocate ports, DB, env for an existing worktree
link
Override {resolve:project} to a specific branch
unlink
Revert to same-branch resolution
env_sync
Re-sync env file from .treeline.yml
config_set
Set user-level config values

Query tools

Read allocation state, configuration, routing URLs, and cross-service resolution.

status
Full allocation: ports, DB, links, supervisor state
list
All worktrees across all projects
port
Primary allocated port
routes
Routing URLs for each allocated port
resolve
Another project's URL (same-branch matching)
env
Resolved env vars with managed-key metadata
where
Filesystem path by branch name
doctor
Health diagnostics
db_name
Allocated database name
config_get
Read config by key path

Supervisor control

Start, stop, and restart the dev server. Restart re-evaluates env including resolve links.

start
Boot the server via the supervisor
stop
Stop the server (supervisor stays for quick resume)
restart
Restart with fresh env evaluation

Structured output for non-MCP agents

For agents that can run shell commands but don't support MCP, use --json on any read command:

  • gtl status --json
  • gtl routes --json
  • gtl doctor --json
  • gtl env --json
  • gtl resolve <project> --json

MCP is the preferred interface (native tool calls, no parsing), but --json works for any agent that can run commands.

Connect your agent

Add the MCP config to your editor. Agents can then provision worktrees, manage links, and control the dev server.

{
  "mcpServers": {
    "gtl": {
      "command": "gtl",
      "args": ["mcp"]
    }
  }
}
Full agent integration reference →