AI agent integration

The MCP server exposes the full GTL toolset to AI agents: query allocations, provision worktrees, manage cross-service links, and control the dev server. Agents work with real allocations instead of guessing. See the AI Agents feature page for use cases.

MCP server

Git Treeline ships a built-in Model Context Protocol server. Agents in Cursor, Claude Code, Windsurf, and other MCP-compatible editors call tools directly instead of parsing shell output.

Add it to your editor's MCP configuration:

{
  "mcpServers": {
    "gtl": {
      "command": "gtl",
      "args": ["mcp"]
    }
  }
}

Query tools

Read allocation state, configuration, and routing.

Tool	Description
`status`	Full allocation: ports, database, branch, links, supervisor state, listening status
`list`	All active allocations across all projects (optionally filter by project)
`port`	Get the primary allocated port for a worktree
`db_name`	Get the allocated database name
`routes`	Routing URLs for each allocated port (HTTPS via router or localhost fallback)
`resolve`	Look up another project's URL (same-branch matching, respects link overrides)
`env`	Resolved env vars with metadata on which keys GTL manages
`where`	Find the filesystem path of a worktree by branch name
`doctor`	Health diagnostics: config, allocation, port availability, runtime state
`config_get`	Read a config value by dotted key path (project or user scope)

Provisioning tools

Create worktrees, allocate resources, and manage configuration.

Tool	Description
`new`	Create a git worktree and run full setup in one step (ports, DB, env)
`setup`	Allocate resources for an existing worktree (idempotent)
`link`	Override cross-service resolution (point {resolve:project} at a specific branch)
`unlink`	Remove a link override, revert to same-branch matching
`env_sync`	Re-sync the env file from .treeline.yml (re-resolves all tokens)
`config_set`	Set a user-level config value

Supervisor control

Manage the dev server process.

Tool	Description
`start`	Start or resume the supervised dev server
`stop`	Stop the dev server (supervisor stays alive for quick resume). Pass `kill: true` to shut down the supervisor entirely.
`restart`	Restart the dev server (re-evaluates env including resolve links)

Resources

The MCP server also exposes read-only resources:

URI	Description
`gtl://allocations`	Full allocation registry across all projects
`gtl://config/user`	User-level git-treeline configuration

Every tool accepts an optional path argument. When omitted, the server uses the agent's current working directory.

Autonomous worktree provisioning

With new and setup exposed via MCP, agents can provision worktrees without shell commands:

MCP tool call

tool: new
args:
  branch: fix-auth-bug
  base: main

This creates the worktree, allocates ports, clones the database (if configured), writes the env file, and returns the allocated resources. The agent gets structured JSON with the URL, port, and database name to use immediately.

Lifecycle hooks

For orchestrators that manage worktrees at a higher level, the CLI commands remain the integration points:

# on worktree creation

$ gtl setup .

# on worktree teardown

$ gtl release . --drop-db

Structured output

For agents that do not use MCP, use --json on any read command:

$ gtl status --json

{
  "worktree": "/code/myapp-fix-auth",
  "branch": "fix-auth-bug",
  "ports": [3010],
  "database": "myapp_dev_fix_auth",
  "listening": true,
  "supervisor": "running"
}

Agent context file

gtl install (and gtl init) writes a treeline section to AGENTS.md (created if missing, appended otherwise). If CLAUDE.md exists but AGENTS.md doesn't, it appends there instead. The section tells agents about port discovery, server management, and available MCP tools.

Use --skip-agent-config on gtl init to opt out.

Port discovery

Agents can query the allocated port via MCP (port tool) or shell:

PORT=$(gtl port)
curl http://localhost:$PORT/health