Launch an AI coding agent with your full stack context injected automatically. Work on a single branch or describe a feature and let the agent build it as incremental stacked PRs. Requires worktree mode (the default).
When your agent CLI is claude, ezs agent automatically installs the ezs-mcp server and registers it with Claude Code before launching the session. The agent gets the full 21-tool ezstack surface natively — no go install, no claude mcp add, no embedded docs paste.
On every launch, ezs agent checks that ezs-mcp is on PATH and that its version matches the running ezs binary. If it's missing or stale, ezs runs go install pinned to the current release tag, falling back to @latest for untagged dev builds.
$ ezs agent
Installing github.com/KulkarniKaustubh/ezstack/v4/cmd/ezs-mcp@v4.4.3 (not installed)...
✓ ezs-mcp installed
Registering ezstack MCP with claude (user scope)...
✓ registered
Launching claude with stack context...If the ezstack MCP server isn't already registered, ezs runs the equivalent of claude mcp add ezstack --scope user -- ezs-mcp for you. User scope means one registration covers every repo you work in — ezstack's first-launch MCP setup is now a no-op after the very first time.
# Equivalent to running this yourself — once, automatically:
$ claude mcp add ezstack --scope user -- ezs-mcp
✓ added MCP server "ezstack" (user scope)With MCP active, the shipped prompt switches from the full DOCUMENTATION.md dump to a short stub that tells the agent to prefer MCP tools. The agent gets strict tool schemas (with destructive annotations on mutating operations) instead of prose instructions — cheaper in tokens, more reliable in behavior.
# Before MCP: ~8KB of DOCUMENTATION.md embedded in every prompt
# After MCP: a short stub + 21 tool schemas delivered via MCP
→ ezstack_status { "decorated": true }
→ ezstack_commit { "message": "Add auth middleware" }
→ ezstack_pr_create { "title": "Add auth middleware" }
— agents call tools directly instead of shelling out to ezs--no-mcpIf you'd rather skip MCP entirely — running in an air-gapped environment, debugging a shipped prompt, or using a non-claude CLI — pass --no-mcp. ezs skips the binary check, skips the registration, and falls back to embedding DOCUMENTATION.md in the prompt like the pre-4.4 flow.
# Legacy doc-paste flow, no claude mcp interaction
$ ezs agent --no-mcp
# MCP is only attempted when the agent CLI is claude:
$ ezs config set agent_command aider
$ ezs agent # → skips MCP, uses embedded docsThe agent launches in your branch's worktree with the full stack structure, parent branch info, and ezstack documentation injected as context. It knows exactly where it is and what commands are available.
Run ezs agent from any branch in a stack. The agent opens in that branch's worktree directory with full context.
# Launch on current branch
$ ezs agent
# Or target a specific branch
$ ezs agent --branch auth-middleware
# Or a specific stack
$ ezs agent -s a1b2cThe agent receives your stack structure as JSON, the current branch and parent names, worktree path, and — when launched with claude — the full 21-tool ezstack MCP surface (auto-installed on first launch; see MCP Integration). With --no-mcp or a non-claude CLI, the prompt embeds the full ezstack documentation as a fallback instead.
# What the agent sees (injected as the first message):
Stack: auth-feature [a1b2c]
Branch: auth-middleware
Parent: auth-service
Worktree: ~/worktrees/auth-middleware
MCP: ezstack (21 tools via ezs-mcp)
→ ezstack_status, ezstack_commit, ezstack_pr_create, …The agent can make changes, commit, sync, and create PRs — all scoped to the single stack it was launched on. It uses ezs -y commands for non-interactive operation.
# Agent runs commands like:
$ ezs -y commit -m "Add middleware validation"
[auth-middleware abc1234] Add middleware validation
Syncing children... done.
$ ezs -y pr create -t "Add auth middleware"
https://github.com/you/repo/pull/45Give the agent a feature description and it explores your codebase, plans a series of small incremental branches, and implements each one with commits and PRs.
Pass a feature description as a string. The agent receives it as a visible initial prompt so you can see exactly what it was told.
$ ezs agent feature "Add user authentication with JWT tokens, including signup, login, and protected route middleware"The agent reads your codebase, understands the existing architecture, and presents a plan of stacked branches for your approval before writing any code.
# Agent proposes a plan like:
Branch 1: jwt-types
Add JWT token types, config, and utility functions
Branch 2: jwt-middleware (parent: jwt-types)
Add authentication middleware
Branch 3: jwt-routes (parent: jwt-middleware)
Add signup/login endpoints and protect routesAfter approval, the agent creates each branch with ezs -y new, implements the changes, commits, and pushes. Each branch is one small, reviewable unit of work.
# Agent creates the stack:
$ ezs -y new jwt-types
Created branch 'jwt-types' with worktree
# ... implements changes ...
$ ezs -y commit -m "Add JWT types and utilities"
$ ezs push
$ ezs -y new jwt-middleware --parent jwt-types
# ... implements changes ...
$ ezs -y commit -m "Add auth middleware"
$ ezs pushYou get a clean stack of small, focused PRs ready for review. Each PR builds on its parent, and stack descriptions are linked automatically.
$ ezs ls
main
└── jwt-types PR #44 +48 -0
└── jwt-middleware PR #45 +72 -3
└── jwt-routes PR #46 +95 -12Agent prompts are composed from three layers: a shipped prompt (updated with releases), custom instructions (~/.ezstack/), and repo-specific instructions (<repo>/.ezstack/). You write only additions — never a full prompt copy.
agent-work-prompt.md — Custom instructions injected into the shipped work prompt. Add rules, context, or conventions for ezs agent.
# Edit custom instructions
$ ezs agent prompt --edit work
# Edit repo-specific instructions
$ ezs agent prompt --edit --repo work
# View the shipped prompt
$ ezs agent prompt --shipped workagent-feature-prompt.md — Custom instructions for ezs agent feature. Includes planning process and branch creation guidelines.
# Edit custom instructions
$ ezs agent prompt --edit feature
# Edit repo-specific instructions
$ ezs agent prompt --edit --repo feature
# View the shipped prompt
$ ezs agent prompt --shipped featureThese placeholders in your prompt files are replaced with live data at runtime.
| Variable | Description |
|---|---|
| {{STACK_JSON}} | Full stack structure as JSON — branches, parents, worktree paths, PR URLs |
| {{BRANCH_NAME}} | Name of the current branch the agent is scoped to |
| {{PARENT_NAME}} | Name of the current branch's parent in the stack |
| {{WORKTREE_PATH}} | Absolute path to the current branch's worktree directory |
| {{EZS_DOCS}} | Full ezstack documentation — concepts, commands, exit codes, workflows |
| {{FEATURE_DESCRIPTION}} | The feature description string (feature builder mode only) |
| {{CUSTOM_INSTRUCTIONS}} | Custom instructions from ~/.ezstack/ (injected automatically) |
| {{REPO_INSTRUCTIONS}} | Repo-specific instructions from <repo>/.ezstack/ (injected automatically) |
Preview the composed prompt with dry-run:
The agent command works with any AI CLI tool. Configure which one to use and you're ready to go.
By default, ezstack uses claude (Claude Code). You can change this to any CLI tool that accepts a positional prompt argument.
# Default: claude
$ ezs config set agent_command claude
# Or use a different tool
$ ezs config set agent_command my-ai-cli
# Override per-invocation
$ ezs agent --cmd my-ai-cli
# Skip MCP auto-install and embed docs in the prompt instead
$ ezs agent --no-mcp