Local-first multi-agent coordination for GitHub pull request workflows.
Gitmoot lets humans and AI agents collaborate through the place software teams already audit work: GitHub pull requests. It runs on the user's machine, keeps workflow state in local SQLite, routes PR comments to registered agent runtimes, and writes the agent's work back into the repo and PR discussion.
V1 is intentionally local-only. There is no hosted dashboard, webhook receiver, cloud runner, or remote control plane.
AI agents can already edit code, review diffs, and run local tools. The hard part is coordinating that work across sessions without losing the human audit trail. Gitmoot makes the repository and its pull requests the shared surface:
- PR comments become agent tasks, review requests, retries, and merge signals.
- Local SQLite records agents, repos, jobs, goals, tasks, PRs, and branch locks.
- Runtime adapters keep Codex, Claude Code, and future runtimes behind the same Gitmoot agent model.
- Agent Templates and job snapshots make agent instructions explicit and reproducible.
- Humans can follow progress from GitHub while agents keep working locally.
GitHub PR comments/state
-> local gitmoot daemon
-> local SQLite state machine and job mailbox
-> registered runtime adapter
-> Codex, Claude Code, shell, or another agent runtime
-> GitHub PR comments, statuses, branches, PRs, and merges
The core primitive is a runtime-neutral Gitmoot agent, not a Codex-specific session. Codex and Claude Code are adapters behind the same internal runtime contract.
curl -fsSL https://gitmoot.io/install.sh | sh
gitmoot version
gh auth statusInstall runtime plugin guidance when you want Codex or Claude Code to discover Gitmoot's Agent Skill from their plugin systems:
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctorThe plugins are discovery and guidance surfaces. The gitmoot CLI and local
daemon remain the execution path.
From a project checkout:
gitmoot init
gitmoot repo add owner/repo --path . --poll 30s
gitmoot doctor --repo .Start a Gitmoot-managed Codex agent and daemon:
gitmoot agent start project-planner \
--runtime codex \
--repo owner/repo \
--path . \
--template planner \
--start-daemonFor fast planning in the current Codex or Claude chat, ask the runtime:
Use the Gitmoot planner here. Write the implementation plan.
That uses the same planner template as the background agent, but imports the
prompt into the current chat instead of creating a Gitmoot job.
Ask the registered background planner when you want a queued Gitmoot job:
gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
gitmoot job watch <job-id>Background jobs are conservative by default. The daemon starts with one worker, runtime session locks serialize jobs for the same Codex or Claude session, repo checkout locks protect local checkouts, and branch locks protect implementation ownership.
Route work through PR comments:
/gitmoot project-planner ask Write a task-by-task implementation plan for this PR.
/gitmoot thermo-review review
/gitmoot retry <job-id>
For the full walkthrough, see docs/local-workflow.md.
- Repo: a GitHub repository plus local checkout path that Gitmoot is allowed to monitor and mutate.
- Daemon: the local background process that polls GitHub PRs and routes queued jobs.
- Agent: a named Gitmoot identity with repo access, role, capabilities, and a runtime adapter.
- Runtime adapter: the bridge from Gitmoot jobs to Codex, Claude Code, shell commands, or future runtimes.
- Template: cached prompt content attached to an agent and snapshotted into each job.
- Job: a routed unit of work created from a PR comment, local ask, task run, retry, or merge action.
- Goal and task: Markdown implementation plans imported into local Gitmoot
state with
gitmoot goal import. - Branch lock: local coordination state that prevents multiple agents from racing on the same branch.
Gitmoot includes planner for structured implementation planning
and standard goal-file writing.
gitmoot agent template update planner
gitmoot agent start project-planner \
--runtime codex \
--repo owner/repo \
--path . \
--template planner \
--start-daemonGitmoot includes thermo-nuclear-code-quality-review for strict review-only
work.
gitmoot agent template update thermo-nuclear-code-quality-review
gitmoot agent start thermo-review \
--runtime codex \
--repo owner/repo \
--template thermo-nuclear-code-quality-review \
--start-daemonAsk it from a PR comment:
/gitmoot thermo-review review
Custom agent templates let you keep a local prompt file and bind its snapshotted instructions to any Gitmoot agent.
mkdir -p agents
printf '%s\n' 'Review frontend changes for correctness and responsive behavior.' > agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent start frontend-reviewer \
--runtime codex \
--repo owner/repo \
--template frontend-reviewer \
--role reviewer \
--capability ask \
--capability reviewAfter editing the prompt file, refresh the cached snapshot:
gitmoot agent template diff frontend-reviewer
gitmoot agent template update frontend-reviewerReuse a custom agent prompt in the current Codex or Claude chat without starting a background job:
Use frontend-reviewer here. Review this diff.
The runtime should load the prompt with:
gitmoot agent prompt frontend-reviewerTemplate capture turns a useful current Codex or Claude chat workflow into a reusable agent template. Capture happens in the current chat from visible conversation context and inspected files; Gitmoot does not read hidden model state or runtime memory.
Draft a blank structure when starting from scratch:
gitmoot agent template draft release-plannerOr ask the current chat to fill the structure from the visible session:
Use Gitmoot to capture this session as agent template release-planner. Draft only.
Review the draft before installing it:
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
gitmoot agent prompt release-plannerInstalled custom templates are snapshots. After editing the source file, run
gitmoot agent template diff <id> and gitmoot agent template update <id>.
gitmoot status --repo owner/repo
gitmoot events --repo owner/repo
gitmoot job list --repo owner/repo
gitmoot job show <job-id>
gitmoot daemon logs
gitmoot lock list --repo owner/repo
gitmoot lock release owner/repo <branch> --owner <agent>Detailed command coverage lives in skills/gitmoot/references/CLI.md.
Gitmoot can package its Agent Skill for Codex and Claude Code so the runtime can discover Gitmoot guidance from its plugin system.
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctorPlugins do not start a hosted service, replace the daemon, subscribe agents, or mutate repository state by themselves. See docs/plugins.md for install details and troubleshooting.
- Hosted docs
- LLM index
- Agent Skills package
- CLI reference
- Codex and Claude plugins
- Local workflow walkthrough
- Beta smoke tests
- Runtime adapter authoring
- Troubleshooting
- Local-only: no hosted dashboard, GitHub App bot identity, cloud runner, or remote control plane.
- Polling watches GitHub PRs; there is no webhook receiver in V1.
- GitHub comments are authored by the authenticated
ghuser. Agent identity appears in the comment body. - Local SQLite remains the workflow source of truth.
Gitmoot is early. Keep changes scoped, preserve local-first behavior, and add focused tests for runtime, CLI, daemon, plugin, or workflow changes. Before opening a PR, run the relevant checks for the files you touched.
Gitmoot is licensed under the Apache License 2.0. See NOTICE for copyright and attribution details.
go test ./...
go vet ./...