Working name: Grove
Grove turns GitHub issues, comments, projects, and repos into a local-first agent workspace. It uses your local
ghlogin and local agent CLIs, so teams can start without hosting a central server.
Most coding agent platforms introduce a new server-side workspace, task database, permission system, repo mirror, and agent configuration layer.
Grove takes the opposite approach:
- GitHub remains the source of truth for collaboration.
- GitHub orgs represent workspaces.
- GitHub repos represent projects.
- GitHub issues and project items represent tasks.
- A local daemon runs agents on a developer machine or controlled runner.
- The daemon uses local
ghandgitcredentials instead of a central token broker. - Agent profiles, skills, and policies live in a normal GitHub config repo.
The goal is not to replace GitHub. The goal is to make GitHub issue workflows agent-native.
| Concept | Grove Mapping |
|---|---|
| Workspace | GitHub organization or user account |
| Project | GitHub repo, or a GitHub Project filtered to a repo |
| Task | GitHub issue, issue comment trigger, or project item |
| Agent profile | YAML file in an org-level config repo |
| Skill | Folder in an org-level config repo |
| Runtime | Local CLI such as Codex, Claude, Cursor, OpenCode |
| Task state | GitHub labels, comments, reactions, or project fields |
| Source checkout | Local daemon-managed clone/worktree |
| Final output | GitHub issue comment, commit, branch, PR, project update |
Recommended name: Grove.
Why:
- Short and memorable.
- Suggests a group of agents working in a shared code environment.
- Avoids being tied to one model provider.
- Works well with terms like
grove daemon,grove agent,grove skill,grove run. - The GitHub/org metaphor fits naturally: repos are trees, an org is a grove.
Other possible names:
- Branchline: Strong git association, but less agent-specific.
- Foreman: Good execution metaphor, but sounds less open and more managerial.
- Taskwood: Git/tree metaphor, but a little awkward.
- IssueForge: Clear, but more generic and heavier.
- Harbor: Nice product name, but weaker connection to GitHub/issues.
-
GitHub-native Grove should use GitHub issues, comments, labels, projects, branches, commits, and PRs as first-class primitives.
-
Local-first execution Agents run on machines controlled by the user or team. Grove does not need to host user code or execute arbitrary code on a central server.
-
No mandatory server The MVP should work with only GitHub + local daemon + local
ghauth. -
Config as code Agents, skills, repo allowlists, routing rules, and policies live in a GitHub repo and are reviewed like code.
-
Explicit boundaries Every task should have a clear target repo, triggering user, allowed agent, allowed operations, and final reporting behavior.
-
Provider-neutral Grove should run multiple agent CLIs behind one local execution interface.
-
Progressive hardening Start serverless. Add an optional thin server only when teams need stronger leases, bot identity, secret brokerage, audit, and fleet management.
GitHub Org
.grove config repo
agents/
skills/
policies/
routing/
project repos
issues
comments
projects
branches
pull requests
Local Machine / Runner
grove daemon
reads .grove config
polls or receives GitHub events
claims eligible tasks
checks out repos
prepares agent context
launches agent CLI
streams local logs
writes progress/result back to GitHub
local tools
gh
git
codex / claude / cursor / opencode / other CLIs
test/build/runtime dependencies
Each GitHub org can have a config repo, for example:
github.com/acme/.grove
grove.yaml
agents/
engineer.yaml
reviewer.yaml
triage.yaml
skills/
code-review/
SKILL.md
references/
scripts/
migration/
SKILL.md
frontend-polish/
SKILL.md
policies/
repos.yaml
permissions.yaml
labels.yaml
routing/
issue-routing.yaml
comment-triggers.yaml
Example agents/engineer.yaml:
id: engineer
name: Engineer
runtime: codex
model: gpt-5-codex
description: General coding agent for implementation tasks.
instructions: |
You are a pragmatic software engineer. Read the repository first,
keep changes focused, run relevant checks, and report the result.
skills:
- code-review
- migration
allowed_repos:
- acme/web
- acme/api
allowed_operations:
- read_issues
- comment_issues
- checkout_repo
- commit
- push_branch
- create_pr
limits:
max_concurrent_tasks: 1
require_human_approval_for_push: falseExample routing/comment-triggers.yaml:
triggers:
- pattern: "@engineer"
agent: engineer
action: run_issue
- pattern: "@reviewer review"
agent: reviewer
action: review_prExample policies/repos.yaml:
repos:
acme/web:
default_branch: main
agents:
- engineer
- reviewer
acme/api:
default_branch: main
agents:
- engineer
- reviewerThe daemon can support two modes.
The daemon periodically calls GitHub through gh api:
- list issues with labels like
grove:queued - list recent comments containing
@agent-name - list project items in a configured status
- inspect PR review requests
This is simple and requires no server.
An optional webhook relay can receive GitHub events and notify daemons.
This is useful later, but not required for the MVP.
The MVP can encode task state in GitHub itself:
| State | GitHub Representation |
|---|---|
| Queued | grove:queued label or trigger comment |
| Claimed | grove:running label + daemon claim comment |
| Running | progress comment edited by daemon |
| Completed | grove:done label + result comment |
| Failed | grove:failed label + failure comment |
| Canceled | grove:cancel label or /cancel comment |
Example claim comment:
<!-- grove-task: 01HY... -->
Grove started `engineer` on `acme/web`.
- Daemon: `fk-macbook`
- Runtime: `codex`
- Branch: `grove/engineer/123-fix-login`
- Started: `2026-05-22T14:30:00Z`The HTML comment gives the daemon a stable marker without cluttering the visible text too much.
Without a server, task claiming is weaker but workable.
The daemon should:
- Find a candidate issue/comment.
- Re-read the issue immediately before claiming.
- Check that no active
<!-- grove-task: ... status=running -->marker exists. - Add a running label or claim comment.
- Re-read again to confirm its own marker won.
This does not provide perfect distributed locking, but it is good enough for a local-first MVP.
For stronger guarantees, Grove can later add an optional server-side lease API:
POST /tasks/claim
POST /tasks/:id/heartbeat
POST /tasks/:id/complete
POST /tasks/:id/fail
The daemon relies on local gh authentication:
gh auth status
gh issue view
gh issue comment
gh pr create
gh api
git pushThis means the agent inherits the current machine user's GitHub permissions.
That is acceptable for MVP and personal/team-local workflows, but Grove must make this explicit:
- The daemon should print the active GitHub user on startup.
- The daemon should refuse to run without an org/repo allowlist.
- The daemon should include the triggering GitHub user and local executor identity in every task context.
- The daemon should support dry-run and approval gates for push/PR operations.
Example startup check:
Grove daemon
GitHub user: fankaidev
Allowed orgs: acme
Allowed repos: acme/web, acme/api
Config source: acme/.grove@main
The daemon manages local repos instead of asking the agent to clone blindly.
Suggested layout:
~/.grove/
config/
acme/
.grove/
repos/
acme/
web.git/ # bare cache
api.git/
worktrees/
acme/
web/
issue-123-engineer/
api/
issue-456-engineer/
runs/
01HY.../
task.json
prompt.md
events.jsonl
logs/
For each task:
- Fetch the bare repo cache.
- Create a worktree.
- Create a branch such as
grove/engineer/123-short-title. - Write task context to disk.
- Launch the agent CLI in the worktree.
- Let the agent commit/push/create PR according to policy.
- Preserve or clean up the worktree depending on config.
Before launching the agent, Grove writes a task context file:
{
"task_id": "01HY...",
"org": "acme",
"repo": "acme/web",
"issue": {
"number": 123,
"title": "Fix login redirect",
"url": "https://github.com/acme/web/issues/123"
},
"trigger": {
"type": "issue_comment",
"user": "alice",
"comment_url": "https://github.com/acme/web/issues/123#issuecomment-..."
},
"executor": {
"machine": "fk-macbook",
"github_user": "fankaidev"
},
"agent": {
"id": "engineer",
"runtime": "codex",
"skills": ["code-review", "migration"]
},
"allowed_operations": [
"comment_issues",
"commit",
"push_branch",
"create_pr"
]
}The prompt should tell the agent to inspect the local context instead of trusting only the natural-language issue text.
Example prompt:
You are running inside Grove.
Read `.grove/task.json` first.
Use the checked-out repository in the current working directory.
Read the GitHub issue and comments with `gh` if needed.
Make a focused change, run relevant checks, commit if appropriate, and report the result back to the issue.
Do not work outside the allowed repository.
Do not push directly to the default branch.Grove should translate shared skills into provider-specific locations:
| Runtime | Skill / Instruction Location |
|---|---|
| Codex | AGENTS.md and runtime home |
| Claude | CLAUDE.md and .claude/skills/ |
| Cursor | .cursor/ |
| OpenCode | .opencode/ |
| Generic | .grove/skills/ |
The config repo remains provider-neutral. The daemon performs runtime-specific materialization.
Grove should define one internal runtime interface:
type Runtime interface {
Name() string
Detect(ctx context.Context) (*RuntimeInfo, error)
Execute(ctx context.Context, task Task, opts ExecuteOptions) (*Result, error)
}Initial runtimes:
- Codex CLI
- Claude Code
- OpenCode
- Cursor CLI, if available
- Generic shell command runtime
The daemon should support three reporting levels:
One final comment:
Grove completed this task with `engineer`.
- Branch: `grove/engineer/123-fix-login`
- PR: #456
- Checks: `pnpm test` passedOne progress comment edited in place, plus final result.
Progress comment plus collapsible logs:
<details>
<summary>Execution log</summary>
...
</details>Verbose mode should be opt-in to avoid polluting issues.
Supported cancellation signals:
- Add label
grove:cancel - Comment
/grove cancel - Remove the triggering label
- Close the issue, if policy says closed issues cancel running tasks
The daemon should poll cancellation state while the agent runs and terminate the child process if canceled.
The serverless model is intentionally simple, but it has sharp edges.
Main risks:
- Agent inherits the local
ghuser's permissions. - A malicious issue could prompt-inject the agent.
- A broad repo allowlist could allow unintended writes.
- Local secrets may be visible to the agent process.
- Multiple daemons can race on the same task.
Required mitigations:
- Repo allowlist is mandatory.
- Agent allowlist per repo is mandatory.
- Push/PR behavior is policy-controlled.
- Direct pushes to default branch are forbidden by default.
- The daemon passes a minimal environment to agent processes.
- The task context clearly distinguishes trusted config from untrusted issue text.
- The daemon logs the active GitHub user, machine, runtime, repo, and branch.
- Skills and agent configs should be reviewed through PRs.
Grove should not require a server for MVP, but it can later support one.
A thin server would add:
- Strong task leasing
- Webhook fanout
- Bot identity
- Short-lived token brokerage
- Secret management
- Central audit log
- Multi-daemon fleet view
- Realtime web UI
- Usage accounting
This should be an upgrade path, not a prerequisite.
Suggested commands:
grove init
grove doctor
grove daemon
grove daemon --org acme
grove run acme/web#123 --agent engineer
grove issue claim acme/web#123 --agent engineer
grove config sync
grove agents list
grove skills list
grove repos list
grove runs list
grove runs show 01HY...MVP should include:
- Read org config repo.
- Validate agent and repo policy files.
- Use local
ghauth. - Poll issues by label and comment trigger.
- Claim task with issue label/comment.
- Checkout repo with bare cache + worktree.
- Inject agent prompt and skills.
- Run one runtime, preferably Codex first.
- Stream local logs to
~/.grove/runs/.... - Write final issue comment.
- Optionally create branch/PR.
Explicitly out of scope for MVP:
- Hosted web UI
- Central server
- Secret brokerage
- Perfect distributed locking
- Billing/usage dashboard
- Complex multi-agent planning
- Cross-org task routing
grove run acme/web#123 --agent engineerNo polling. No task claiming. Just prove config loading, checkout, prompt generation, runtime execution, and final comment.
Daemon polls issues with grove:queued, claims them, runs them, and comments back.
Support @engineer and /grove run engineer.
Create branch and PR by policy.
Materialize skills into provider-specific locations.
Add Claude, OpenCode, and generic command runtimes.
Add strong leases and webhook relay only after the local-first model is useful.
Grove is for teams that already live in GitHub and want agents to join that workflow without adopting a separate project-management backend.
It should feel like:
Install daemon.
Add .grove config repo.
Label an issue.
Watch an agent open a PR.
That is the whole product promise.