Grovie

Grovie is a local-first, GitHub-native multi-agent platform for coordinating coding agents across real repository work.

It keeps execution on your machines while GitHub remains the shared workflow, audit trail, and review surface. Agents run locally with your tools, credentials, prompts, and runtime permissions; coordination happens through the GitHub artifacts your team already uses.

gh auth login
npx @fankaidev/grovie@latest init
npx @fankaidev/grovie@latest doctor
npx @fankaidev/grovie@latest daemon start

Why Grovie?

• No hosted service to sign up for, operate, or trust with your source checkout.
• No new task database, dashboard, queue, account system, or central coordinator.
• GitHub remains the shared workflow, audit trail, and review surface.
• Agents run on your machines with your local tools, credentials, prompts, and runtime permissions.
• Work happens in isolated local worktrees under ~/.grovie/.
• Results come back as ordinary GitHub branches, pull requests, comments, review summaries, and CI checks.
• Local run state, logs, and worktrees stay inspectable on disk.
• Safe publishing is the default: no default-branch pushes and no force-pushes over remote work.

Who It Is For

Grovie is for developers and small teams who want multiple coding agents to collaborate on real repository work while keeping execution, credentials, source checkouts, and raw logs on their own machines.

It is especially useful when you want local agents to share a durable workflow, produce reviewable pull requests, and leave an auditable trail in GitHub without adopting a hosted agent platform.

Quick Start

Prerequisites:

• Git
• GitHub CLI authenticated with gh auth login
• Node.js 20 or newer
• A local agent runtime such as Codex CLI, Claude Code, or Pi

Run Grovie with npx:

npx @fankaidev/grovie@latest --version
npx @fankaidev/grovie@latest --help

Create the global Grovie config:

npx @fankaidev/grovie@latest init

In an interactive terminal, init can pick a watched repository from the current GitHub remote or recent GitHub repositories, enable detected local runtimes as agents, and enable the local-only admin console. For non-interactive setup, pass explicit values:

npx @fankaidev/grovie@latest init --yes --repo owner/repo --runtime codex

This starts with one local agent when you enable a runtime. The agent name is combined with this machine's id to form labels and run targets such as codex@your-machine-id. The daemon concurrency limit caps total local runs across all watched repositories.

Check the local Grovie setup:

npx @fankaidev/grovie@latest doctor

Use the Machine id and Configured agents lines from grovie doctor to find the concrete agent id for this machine, such as codex@kai-mini.

Add or adjust repositories in the global daemon schedule by editing watchedRepositories in ~/.grovie/config.yml.

Start the local daemon:

npx @fankaidev/grovie@latest daemon start
npx @fankaidev/grovie@latest daemon status

Trigger issue work through GitHub:

gh issue edit 123 --repo owner/repo --add-label grovie
npx @fankaidev/grovie@latest issue assign owner/repo#123 codex@your-machine-id
gh issue comment 123 --repo owner/repo --body "Please start."

Inspect the background daemon when needed:

npx @fankaidev/grovie@latest daemon status
npx @fankaidev/grovie@latest daemon logs

Example Workflow

1. Create a GitHub issue, such as Fix failing login test.
2. Add the queue label, usually grovie.
3. Assign the issue to a local agent with grovie issue assign owner/repo#123 codex@your-machine-id.
4. Grovie sees the issue from the local daemon schedule.
5. Grovie prepares an isolated worktree under ~/.grovie/.
6. The configured local agent receives the issue context and works in that worktree.
7. If code changes are produced, Grovie commits them to a generated branch and opens a pull request.
8. Grovie comments back on the issue with the run id, local run directory, branch, and pull request link.
9. Humans review, merge, or ask the agent to continue using normal GitHub workflow.

When you want the assigned agent to act again, add a normal GitHub issue comment asking it to continue. The daemon picks that visible activity up through polling and handled cursors.

Demo Issues

These small demo issues show how Grovie coordinates local agents through ordinary GitHub workflow:

• #338: demo: count from 1 to 6 shows multi-agent turn-taking through issue comments.
• #339: demo: programmer joke contest shows multi-agent discussion and lightweight consensus.
• #340: demo: README demos and version bump shows a code-change workflow with review, merge, and a follow-up version bump.

How It Works

Grovie splits responsibility between GitHub and the local machine.

GitHub is the control plane. Issues describe work, labels route that work to agents, comments carry human-visible updates, pull requests hold code changes, and CI remains the review gate.

The local machine is the executor. A Grovie daemon runs on your machine, polls the repositories configured in ~/.grovie/config.yml, and starts work only for issues that are eligible for a configured local agent.

flowchart TD
  config["~/.grovie/config.yml<br/>local agents + watched repos"]
  issue["GitHub issue<br/>queue label + agent assignment"]
  daemon["Local Grovie daemon<br/>polls GitHub and checks eligibility"]
  run["Local run<br/>one issue-agent execution"]
  state["~/.grovie/<br/>session worktree + run logs + task handoff"]
  runtime["Local agent runtime<br/>Codex, Claude Code, or Pi"]
  result{"Runtime result"}
  comment["GitHub issue comment<br/>status, reason, local paths, links"]
  pr["Generated branch + pull request<br/>normal review and CI"]
  review["Human and agent follow-up<br/>comments, reviews, relabeling, reruns"]

  config --> daemon
  issue --> daemon
  daemon --> run
  run --> state
  state --> runtime
  runtime --> result
  result --> comment
  result --> pr
  comment --> review
  pr --> review
  review --> issue

The loop has two durable boundaries:

• GitHub holds shared coordination state: issues, labels, comments, pull requests, reviews, and CI.
• The local machine owns execution state: daemon locks, isolated worktrees, runtime handoff files, stdout/stderr logs, events, and result metadata.

Grovie is organized around user-visible areas:

| Area | What it owns | |------|--------------| | Agent | Machine identity, local agents, and assignment labels. | | Daemon | Watched repositories, queue polling, daemon lifecycle, and local scheduling. | | Session | Long-lived issue-agent context, persistent worktrees, handled cursors, cleanup, and recovery. | | Run | Concrete daemon-triggered executions, runtime handoff, logs, cancellation, and safe result publishing. | | GitHub | Human-visible issue and pull request updates without dumping raw prompts or logs into comments. | | State repo | Optional remote sync of local run metadata for observability and recovery. |

The detailed behavior lives in docs/use-cases, with the scenario format described in docs/bdd.md.

Agent Coordination Model

Grovie does not include a central semantic coordinator that decides which agent should act next. GitHub remains the shared workspace, and Grovie's daemon performs mechanical routing from visible GitHub state such as issue labels, comments, pull requests, reviews, and CI activity.

An issue can be assigned to multiple local agents. Each assigned agent gets the relevant GitHub context and decides from its own guide, runtime prompt, and the issue timeline whether to act, do nothing, ask for clarification, review work, hand off to another agent, or take a lightweight lead role. Different behavior should come from the agent's instructions and the issue context, not from hidden Grovie workflow rules.

This keeps collaboration inspectable: humans and agents coordinate through normal GitHub artifacts, while Grovie provides isolated runs, local state, logs, cancellation, and safe publishing. Agents that should be proactive can be guided to lead or delegate; agents that should be conservative can be guided to no-op unless they are explicitly mentioned or the issue reaches a relevant state.

Commands

grovie init creates the global Grovie config at ~/.grovie/config.yml. In an interactive terminal it can pick a watched repository from the current GitHub remote or recent GitHub repositories, choose which issue creators are allowed to trigger automatic runs, enable detected local runtimes as agents, and enable the local-only admin console. Existing configs are kept unless you confirm replacement; scripts can use grovie init --yes --repo owner/repo --runtime codex or grovie init --force --yes --repo owner/repo --runtime codex.

Edit watchedRepositories in ~/.grovie/config.yml after initialization to control the global daemon schedule. Each entry can include the repository, queue label, branch policy, and trusted authors in one visible config block.

watchedRepositories:
  - repository: owner/repo
    label: grovie
    trust:
      allowedAuthors:
        - your-github-login

To allow any issue creator for a watched repository, use allowedAuthors: ["*"] explicitly.

grovie doctor validates the global Grovie config, then confirms the current gh login plus CLI runtime availability.

grovie issue assign owner/repo#123 codex@your-machine-id adds the matching agent:... issue label. grovie issue unassign owner/repo#123 codex@your-machine-id removes it.

grovie daemon start polls watched repositories from ~/.grovie/config.yml in a local background process, resolves repository policy from each watched repository entry, acquires a local execution lock for one (issue, agent) at a time, and runs eligible work locally.

grovie status and grovie runs list show recent local session status, issue identity, branches, log paths, and last event time. grovie runs show <run-id> shows the worktree, run directory, stdout/stderr logs, and recent events for one run.

grovie runs cleanup --dry-run previews explicit local cleanup. Without --dry-run, completed session worktrees can be removed while preserving session and run history.

Safety Model

Grovie is a local executor, so it runs with your local filesystem, GitHub credentials, and agent CLI permissions. The safety boundary is intentionally simple:

• grovie daemon start polls repositories listed in ~/.grovie/config.yml; that list is scheduling configuration, not an authorization boundary.
• Automatic daemon queue runs require the issue creator to match the watched repository author trust policy. allowedAuthors lists allowed GitHub logins; a single * allows any issue creator.
• It prepares issue work in isolated worktrees under ~/.grovie/worktrees/.
• It stores task handoff files and logs under ~/.grovie/runs/.
• It passes runtime child processes only a small baseline environment plus variables explicitly listed in the configured agent envKeys.
• It refuses config that enables default-branch pushes.
• It publishes code changes through a generated Grovie branch.
• It excludes .grovie/ handoff files from commits and unstages them before commit.
• It does not publish empty code-change results for no-change runs.
• It coordinates daemon work with local execution locks and supports explicit cancellation through issue comments or cancel labels.

Manual GitHub Checklist

Use this checklist before trusting a new machine or repository:

1. Run gh auth status and confirm it is authenticated to the target account.
2. Run grovie init to create ~/.grovie/config.yml with at least one configured local agent.
3. Run grovie doctor and confirm config, GitHub auth, and local agent runtime availability are green.
4. Note the concrete agent id shown by grovie doctor, such as codex@your-machine-id.
5. Edit watchedRepositories in ~/.grovie/config.yml if you need to add or adjust repositories this machine should poll.
6. Confirm each watched repository has the intended trust.allowedAuthors policy.
7. Create a small test issue in GitHub and label it with the queue label, usually grovie.
8. Start the daemon with grovie daemon start.
9. Assign the issue with grovie issue assign owner/repo#123 codex@your-machine-id.
10. Add an issue comment asking the assigned agent to continue, then wait for the daemon to poll.
11. Confirm the issue receives a Grovie result comment with a run id and local run directory.
12. For code-change runs, confirm Grovie publishes a generated branch and links the result from the issue.
13. Confirm no direct push was made to the default branch.
14. Add /grovie cancel to a running issue and confirm the daemon marks it canceled.

Isolated Smoke Validation

For end-to-end smoke tests, run Grovie with a temporary HOME so daemon state, locks, repository cache, run files, worktrees, and logs stay separate from your normal ~/.grovie daemon. Reuse real GitHub authentication through GH_CONFIG_DIR when the test should create issues or comments, and put a fake agent CLI earlier in PATH when you only need to validate the Grovie CLI, daemon, GitHub, worktree, and result-comment flow without asking a real model to edit code. If the temporary home needs to clone private repositories, configure git in that home to use gh auth git-credential. This validates Grovie orchestration, not real agent reasoning or code-generation quality.

Contributing

Grovie is open source, and contributions are welcome. Issues, ideas, documentation improvements, and pull requests are all useful.

Install the current source checkout for development:

pnpm install
pnpm build
pnpm link --global
grovie --version
grovie --help

Use pnpm check before opening a pull request when possible.

See AGENTS.md for development commands, validation, and the lightweight Grovie engineering workflow.