Ask AI
Ask AI Start conversation ↵

I'm an AI assistant with Grove's codebase and documentation in context.

Ask me anything about Grove.

EXAMPLE QUESTIONS

CLI

Previous Next

Manage your fleet from the command line

Every command and flag reaches the same engine as the TUI.

Pressing TAB through grove commands and model names in a terminal, with each completion list drawn from live values
Completion reads live values. Workspace ids, configured agents, models, branches and sessions appear at Tab. See tab completion.

Find the right workflow

  • grove --help lists commands and grove <topic> --help lists a topic's flags.
  • grove skills list --details lists every installed workflow and grove skills show <name> reads one, with no daemon needed.
  • Any agent writes to another with grove mailbox contacts then grove mailbox send --to <id> --subject … --body …. A reply is the same command with the addresses swapped. See native sessions and the MCP learning path.

The contract

  • Most commands resolve the repo from cwd upward. daemon, auth, fleet and tickets owned are host wide.
  • A WORKSPACE argument takes an exact id or a unique prefix, and an ambiguous one exits 1 with the candidates.
  • ls, fleet and debug are JSON native and the session commands take --json.
  • Exit 0 succeeds, 1 is a Grove error, 2 is bad input. No pagers, and no prompt but grove kill's, which --yes skips.

grove

Launches the TUI at cwd. See the TUI tour and tab completion.

cd /path/to/my-project
grove

Read commands

Read workspace state and transcripts without changing them.

grove ls

Lists repository workspaces as JSON. See status semantics.

grove ls
# Every workspace that needs attention, without opening the TUI.
grove ls | jq -r '.[] | select(.status=="offline" or .status=="orphaned" or .status=="error") | "\(.status)\t\(.title)\t\(.branch)"'

grove fleet

Lists host workspaces as JSON.

grove fleet
grove fleet | jq '.projects[].workspaces[] | select(.needs_attention)'

grove show

One workspace's identity, git counts, agent state, task phase and todo list, recent turns and a live pane snapshot. The peek rail as a command.

grove show [WORKSPACE] [--last/-l N]

grove show            # from inside a worktree, infers the workspace
grove show a1b2 -l 5  # by id prefix, last 5 turns

grove edit

Changes a workspace title or description.

grove edit [WORKSPACE] [--title TEXT] [--description TEXT]

grove edit --title "quota gateway"    # from inside the worktree
grove edit a1b2 -d "spike, do not merge"
grove edit --description ""           # clear the description

A title is 1 to 120 characters, an empty description clears it, --json returns the record, and the TUI and web dashboard rename through grove edit too.

grove phase

Sets or reads task phase.

grove phase [REF] [PHASE] [--note TEXT] [--ticket PROVIDER:ID] [--blocked]   # set
grove phase [REF]                                                            # read

grove phase implementing --note "wiring the CLI verb"   # from inside the worktree
grove phase a1b2 verifying                    # another workspace, by id prefix
grove phase verifying --ticket gitea:42       # scoped to one attached ticket
grove phase implementing --blocked            # stuck on this step
grove phase                                   # read the cwd-inferred phase, tickets included
  • The phases are scoping, planning, implementing, verifying, delivering and done, and a note is one line under 200 characters.
  • --ticket scopes the claim to one attached ticket's provider:id for a workspace working several at once.
  • --blocked is a flag beside the phase, never a replacement for it.

grove sessions

Lists project conversations, newest first. grove sessions recollect recovers compacted instructions.

grove sessions list

grove sessions list [--host] [--agent KIND] [-w PREFIX] [--since WINDOW] [-n N] [--json]

--host scans every repo, see the Session Catalog. --since takes 30m, 6h, 2d, 1w or an ISO date.

# Which agents are waiting for a human?
grove sessions list --json \
  | jq -r '.[] | select(.state=="waiting" or .state=="blocked") | "\(.state)\t\(.workspace_title // "-")\t\(.title // .last_prompt)"'

# Only what moved in the last two hours, five most recent.
grove sessions list --since 2h --limit 5

grove sessions show

grove sessions show REF [-l N] [--json]

grove sessions show 7b3f2c1a --last 3

grove sessions dump

grove sessions dump REF [--jsonl]

grove sessions dump 7b3f2c1a --jsonl | jq -c 'select(.type=="assistant")'   # original lines verbatim

grove sessions recollect and grove recollect

Recovers every direct user query from a session, the workspace primary when omitted.

grove sessions recollect [SESSION] [--last/-l N] [--json]
grove recollect [SESSION] [--last/-l N] [--json]

# Recover the original task after a compaction.
grove recollect 7b3f2c1a

# Machine-readable most recent instructions.
grove sessions recollect 7b3f2c1a --last 3 --json

grove sessions remap

Pins the workspace primary session. See cli_sessions.py.

grove sessions remap WORKSPACE SESSION

grove sessions remap a1b2 cafef00d

Lifecycle commands

Create, reach and remove workspaces.

grove create

Creates a worktree, branch and agent.

grove create [TITLE] [--agent/-a NAME] [--model/-m ID] [--runtime host|container] [branch flags] [--base REF] [--description/-d TEXT] [--no-init] [--prompt/-p TEXT] [--brief/--no-brief] [--native/--terminal] [--cwd PATH] [--resume-session ID] [--attach/--no-attach]
  • Branch. Auto names one from the title, --branch names it off --base, --checkout reuses a local branch, --track follows a remote one, and --root runs in the repo root with no worktree.
  • Agent and model. --agent matches a name in your config, --model is forwarded verbatim and never validated, and --native or --terminal overrides the roster entry's session mode for this workspace.
  • Runtime and setup. --runtime host|container is create time only. --no-init skips the init script once, --cwd starts the agent in a directory inside the worktree, and --brief or --no-brief decides whether the agent gets Grove's first turn note.
  • The first turn. --prompt delivers the first task at boot, --resume-session continues an existing session by id, and --attach hands your terminal over once it is up, which is the default when output is a terminal.
# Quick create: saved defaults, generated title, attached
grove create

# Auto branch (title slug → grove/fix-login-YYYYMMDD-HHmmss)
grove create "fix login" --agent claude

# Named branch off main
grove create "fix login" --agent claude --branch fix/login --base origin/main

# Reuse an existing local branch
grove create "review pr" --agent claude --checkout existing-wip

# Track a remote branch
grove create "track ci" --agent claude --track origin/feature/ci

# In-place (no worktree, no new branch)
grove create "in place" --agent claude --root

# Start working immediately
grove create "add cache" --agent claude --prompt "add an LRU cache in front of the API client"

# Start the agent in a monorepo's API directory
grove create "add endpoint" --agent claude --cwd services/api

Steer, pause, resume, respawn, kill, attach, shell

grove message a1b2 "now add a test for the empty case"   # a direction to a running agent
grove pause a1b2 --force        # drop worktree and session, keep the branch; --force discards uncommitted changes
grove resume a1b2               # rebuild a paused workspace from its branch
grove respawn a1b2              # recreate a vanished tmux session over the worktree
grove kill a1b2 --keep-branch -y   # remove the workspace; --delete-branch or --keep-branch override provenance, -y skips the prompt
grove attach a1b2               # hand your terminal to the session
grove shell a1b2                # an interactive shell inside the container

A native workspace attaches read only. Its pane is Grove's worker printing one protocol frame per line, so steer it with grove message or the dashboards.

grove agent

Manages additional container agents.

grove agent list WORKSPACE
grove agent add WORKSPACE [--agent NAME] [--name SLOT] [--model ID] [--prompt TEXT]
grove agent attach WORKSPACE SLOT
grove agent peek WORKSPACE SLOT [--lines N]
grove agent message WORKSPACE SLOT TEXT
grove agent kill WORKSPACE SLOT [--yes]

grove agent add a1b2 --agent codex --name reviewer
grove agent message a1b2 reviewer "review the last three commits"

grove code

Opens a container workspace in VS Code. See Container Workspaces.

grove code WORKSPACE
grove code a1b2

grove diagram

Opens, reads, updates or stops an existing .drawio file without creating or publishing it.

grove diagram open PATH
grove diagram read
grove diagram preview
grove diagram update INPUT --revision HASH --session-id ID
grove diagram stop --revision HASH --session-id ID
  • Use the latest revision and session identity for update or stop.
  • Stopping leaves it readable. See Diagram collaboration.

grove tickets

Attaches tickets and hands issues to the fleet.

grove tickets attach REF [--workspace/-w ID]
grove tickets list [--workspace/-w ID]
grove tickets detach REF [--workspace/-w ID]
grove tickets handover REF
grove tickets owned
grove tickets handback REF

grove tickets attach https://github.com/acme/api/pull/42   # cwd-inferred workspace
grove tickets attach '#42' -w a1b2
grove tickets list

grove tickets handover 42   # assign Grove's account, start a workspace on it
grove tickets owned         # every ticket Grove holds, host-wide, and whether work is live
grove tickets handback 42   # unassign, leaving any workspace alone

Using the CLI from an agent

A coding agent with shell access inside a Grove managed worktree has the full command surface, reading what siblings are doing and, when authorized, driving the same fleet.

  • Pass --json whenever you parse the result. Treat a non zero exit as no data.
  • Stop at the first rung that answers your question. list is cheapest, show and recollect cost a few turns, dump is the last resort and goes to a file, never your context.
# Sibling sessions: everything on this host except your own branch.
MY_BRANCH=$(git branch --show-current)
grove sessions list --json \
  | jq -r --arg me "$MY_BRANCH" '
      .[] | select(.git_branch != $me)
      | "\(.session_id[0:8])  \(.state)  \(.workspace_title // "-")  \(.title // .last_prompt // "")"'

grove sessions list --since 1h                 # cheapest: what moved recently
grove sessions show a91e0d34 --last 5          # mid cost: a sibling's last turns
grove recollect a91e0d34 --last 5              # every direct instruction, including pre-compaction
grove sessions dump a91e0d34 --jsonl > /tmp/a91e0d34.jsonl   # last resort

# Spin one up, steer it, check it, pause it.
grove create "add retry logic" --agent claude --prompt "wrap the API client's fetch with exponential backoff"
grove message a1b2 "now add a test for the retry case"
grove sessions show a1b2 --last 3
grove pause a1b2

Admin commands

One fence per verb. Each takes --help for its full flag set.

grove config show | jq '.worktree.root_template'   # the resolved cascade for this repo, as JSON
grove config add-project /path/to/other-project    # register a repo for host wide views
grove config init --with-onboarding                # write .grove/config.json, install skills, register MCP
grove config schema --stdout                       # the JSON Schema, to disk without the flag
grove skills install -t user --agent claude        # Grove skills for claude | codex | all
grove mcp install --target project --agent claude  # this install as an MCP server
grove init devcontainer --force                    # a default .devcontainer/devcontainer.json
grove doctor --json                                # container requirements, as a table without the flag
grove version
grove debug                                        # every resolved path and whether config loaded

grove init devcontainer and grove doctor serve Container Workspaces.

grove daemon serve

Runs the daemon behind the web dashboard. See the systemd user service.

grove daemon serve              # 127.0.0.1:7421
grove daemon serve --port 7777

--host defaults to loopback on purpose, see the security model. --port 0 picks a free one and --print-port prints it once listening.

grove auth

Manages pairing requests and active sessions. See authentication.

grove auth pending                 # requests waiting for approval, with their codes
grove auth approve <challenge-id>  # or deny
grove auth sessions                # active sessions
grove auth revoke <session-id>

GROVE_DEBUG=1

Sets standard error logging to DEBUG for one command while standard output stays pipeable JSON.

GROVE_DEBUG=1 grove ls

Tab completion

Install completion for your shell.

  • grove completions install finds a directory without editing an rc file.
  • Zsh uses the first writable fpath directory. Bash and fish autoload normally.
  • grove completions show --shell zsh prints a script for dotfiles.
  • Completion omits unavailable values.
grove completions install          # detects zsh, bash or fish
exec $SHELL                        # start a new shell to pick it up

What completes

  • Every workspace argument completes to the ids in this repo with their title and branch.
  • --agent completes to your resolved config, --model to that agent's catalog, --checkout, --track and --base to local and remote branches, --cwd to the configured working directories, and --resume-session to recorded session ids.
  • grove phase completes both the six phase names and workspace ids, --ticket and grove tickets detach complete attached tickets, grove agent verbs complete the agents live in the container, and grove auth verbs complete pending challenges and active sessions.

If nothing happens when you press Tab

Answering a completion means starting grove, about a second on a typical host, and some zsh completion frameworks give a completer far less than that and silently drop it.

  • The common case is zsh-autocomplete, whose default budget is 0.4 seconds. Raise it in ~/.zshrc with the line below.
  • Note the single trailing colon. :autocomplete: is the exact context the setting is read from, and ':autocomplete:*' does not match it.
  • To tell this apart from an install problem, run the round trip by hand with the command below.
  • Candidates printed means Grove is fine and the shell is discarding them. Nothing printed is a real fault worth reporting.
zstyle ':autocomplete:' timeout 3

time ( env _TYPER_COMPLETE_ARGS="grove show " _GROVE_COMPLETE=complete_zsh grove )

See also

TUI Tour Web Dashboard
User Guide
Developer Reference