{"id":50802912,"url":"https://github.com/jerryfane/gitmoot","last_synced_at":"2026-07-02T21:00:42.787Z","repository":{"id":359580631,"uuid":"1244593267","full_name":"jerryfane/gitmoot","owner":"jerryfane","description":"A local-first control layer for AI agents","archived":false,"fork":false,"pushed_at":"2026-06-07T13:50:33.000Z","size":7825,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T15:21:23.911Z","etag":null,"topics":["agentic-skill","agentic-workflows","agents","agentskills","ai","ai-agents","ai-tools"],"latest_commit_sha":null,"homepage":"https://gitmoot.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jerryfane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T12:12:25.000Z","updated_at":"2026-06-07T13:43:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jerryfane/gitmoot","commit_stats":null,"previous_names":["jerryfane/gitmoot"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/jerryfane/gitmoot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerryfane%2Fgitmoot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerryfane%2Fgitmoot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerryfane%2Fgitmoot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerryfane%2Fgitmoot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jerryfane","download_url":"https://codeload.github.com/jerryfane/gitmoot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerryfane%2Fgitmoot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34263874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-skill","agentic-workflows","agents","agentskills","ai","ai-agents","ai-tools"],"created_at":"2026-06-12T22:02:20.779Z","updated_at":"2026-07-02T21:00:42.779Z","avatar_url":"https://github.com/jerryfane.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/gitmoot-hero.png\" alt=\"Gitmoot coordinates local agent runtimes through GitHub pull request workflows\" width=\"900\"\u003e\n\u003c/p\u003e\n\n# Gitmoot\n\nLocal-first multi-agent coordination for GitHub pull request workflows.\n\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-black.svg)](./LICENSE)\n[![GitHub release](https://img.shields.io/github/v/release/jerryfane/gitmoot?include_prereleases\u0026color=black)](https://github.com/jerryfane/gitmoot/releases)\n[![Go module](https://img.shields.io/badge/go-module-black.svg)](./go.mod)\n[![CI](https://github.com/jerryfane/gitmoot/actions/workflows/ci.yml/badge.svg)](https://github.com/jerryfane/gitmoot/actions/workflows/ci.yml)\n\nGitmoot lets humans and AI agents collaborate through the place software teams\nalready audit work: GitHub pull requests. It runs on the user's machine, keeps\nworkflow state in local SQLite, routes PR comments to registered agent\nruntimes, and writes the agent's work back into the repo and PR discussion.\n\nV1 is intentionally local-only. There is no hosted dashboard, webhook receiver,\ncloud runner, or remote control plane.\n\n## Why Gitmoot\n\nAI agents can already edit code, review diffs, and run local tools. The hard\npart is coordinating that work across sessions without losing the human audit\ntrail. Gitmoot makes the repository and its pull requests the shared surface:\n\n- PR comments become agent tasks, review requests, retries, and merge signals.\n- Local SQLite records agents, repos, jobs, goals, tasks, PRs, and branch locks.\n- Runtime adapters keep Codex, Claude Code, Kimi Code (plus the legacy\n  `kimi-cli`, a deterministic `shell` adapter), and future runtimes behind the\n  same Gitmoot agent model.\n- **Orchestra** is Gitmoot's name for structured multi-agent delegation: a\n  conductor (coordinator) returns a validated `delegations[]` DAG that Gitmoot\n  dispatches as child jobs (the players), then enqueues one continuation job\n  (the finale) to synthesize their results (replacing the old `next_agents`\n  mechanism). Use `gitmoot orchestrate \u003cagent\u003e \"...\"` to start one.\n- Delegation trees are bounded by a depth cap, a per-root job budget, a per-root\n  wall-clock budget, a per-coordinator width cap, and loop detection. When a\n  bound trips, the engine enqueues one graceful finalize continuation so the\n  coordinator synthesizes a best-effort result instead of recursing forever or\n  dropping work silently.\n- Agent Templates and job snapshots make agent instructions explicit and\n  reproducible — and can be backed up to / pulled from a GitHub repo.\n- Heartbeat schedules run recurring agent work without an external cron, and an\n  opt-in `[events]` webhook streams job/candidate lifecycle events to your own\n  systems.\n- Humans can follow progress from GitHub while agents keep working locally —\n  in the PR thread, the terminal TUI, or the read-only web dashboard.\n\n## How It Works\n\n```text\nGitHub PR comments/state\n  -\u003e local gitmoot daemon\n  -\u003e local SQLite state machine and job mailbox\n  -\u003e registered runtime adapter\n  -\u003e Codex, Claude Code, Kimi Code, shell, or another agent runtime\n  -\u003e GitHub PR comments, statuses, branches, PRs, and merges\n```\n\nThe core primitive is a runtime-neutral Gitmoot agent, not a Codex-specific\nsession. Codex, Claude Code, and Kimi Code are adapters behind the same internal\nruntime contract.\n\n## Install\n\n```sh\ncurl -fsSL https://gitmoot.io/install.sh | sh\ngitmoot version\ngh auth status\n```\n\nLater, self-update from GitHub Releases:\n\n```sh\ngitmoot update --check\ngitmoot update --restart-daemon\n```\n\nInstall runtime plugin guidance when you want Codex or Claude Code to discover\nGitmoot's Agent Skill from their plugin systems:\n\n```sh\ngitmoot plugin install codex\ngitmoot plugin install claude\ngitmoot plugin doctor\n```\n\nThe plugins are discovery and guidance surfaces. The `gitmoot` CLI and local\ndaemon remain the execution path.\n\nFor sandboxed Codex sessions, print a launch command that grants access to the\nresolved Gitmoot home:\n\n```sh\ngitmoot plugin codex-launch --repo .\n```\n\n## Quick Start\n\nOne command registers the repo, subscribes an agent, and launches a\ntagging-ready daemon (`--watch-issues` defaults on):\n\n```sh\ngitmoot setup --repo owner/repo --path . --agent helper --runtime claude --session last --start-daemon\n```\n\nOr step through the manual path from a project checkout:\n\n```sh\ngitmoot init\ngitmoot repo add owner/repo --path . --poll 30s\ngitmoot doctor --repo .\n```\n\nStart a Gitmoot-managed Codex agent and daemon:\n\n```sh\ngitmoot agent start project-planner \\\n  --runtime codex \\\n  --repo owner/repo \\\n  --path . \\\n  --template planner \\\n  --start-daemon\n```\n\n`--runtime` accepts `codex`, `claude`, `kimi`, or `kimi-cli` (the opt-in legacy\nKimi CLI adapter). For Kimi Code, run `kimi login` and restart the Gitmoot\ndaemon so it inherits the session, then start the agent with `--runtime kimi`.\n\nFor fast planning in the current Codex or Claude chat, ask the runtime:\n\n```text\nUse the Gitmoot planner here. Write the implementation plan.\n```\n\nThat uses the same `planner` template as the background agent, but imports the\nprompt into the current chat instead of creating a Gitmoot job.\n\nAsk the registered background planner when you want a queued analysis or\nplanning job:\n\n```sh\ngitmoot agent ask project-planner --repo owner/repo --background \"Write the implementation plan and goal file.\"\ngitmoot job watch \u003cjob-id\u003e\n```\n\nRun one job through a different runtime (or model) without re-registering the\nagent — the agent's default runtime and session are untouched:\n\n```sh\ngitmoot agent ask project-planner --repo owner/repo --runtime claude \"Compare the approaches.\"\ngitmoot agent run lead --repo owner/repo --model gpt-5-codex \"Implement this task.\"\n```\n\nFor coordinator delegation (the Orchestra pattern) where the request may require\nreview or file edits, use `agent run` and let Gitmoot select the safe workflow\npath:\n\n```sh\ngitmoot agent run lead --repo owner/repo --task task-001 --background \"Implement this task.\"\ngitmoot agent run reviewer --repo owner/repo --pr 12 --background \"Review this PR.\"\n```\n\n`gitmoot orchestrate \u003cagent\u003e \"...\" [--repo R]` is sugar for\n`gitmoot agent run \u003cagent\u003e --background \"...\"` — it starts an orchestra of agents\nfrom a conductor that returns a `delegations[]` score.\n\nBackground jobs are safe by default. The daemon starts with one worker, repo\ncheckout locks protect local checkouts, branch locks protect implementation\nownership, and busy Codex/Claude runtime sessions can fork bounded temporary\nworkers when `[parallel_sessions]` allows it. Temp workers still require\ncheckout/worktree safety and write-capable agents for implementation jobs.\n`gitmoot daemon start --parallel N` runs a repo's queued jobs N-wide\n(auto-selecting the pool scheduler); see\n[docs/parallel-jobs.md](docs/parallel-jobs.md).\n\n`daemon start --repo owner/repo` scopes the daemon to a **single** repo: it\npolls only that repo's PRs and claims only that repo's queued jobs. Omit\n`--repo` and one daemon supervises every enabled repo; cap an individual repo's\nparallelism on that shared daemon with the `[repos.\"owner/repo\"] max_parallel`\nconfig key. Both `daemon run` and `daemon start` accept\n`--session \u003croot-job-id\u003e` (alias `--root`) to pin the worker to a single\norchestration run — it then runs only jobs whose `root_job_id` matches that\nvalue plus the root coordinator job itself:\n\n```sh\ngitmoot daemon start --session \u003croot-job-id\u003e\n```\n\nRoute work through PR comments:\n\n```text\n/gitmoot project-planner ask Write a task-by-task implementation plan for this PR.\n/gitmoot thermo-review review\n/gitmoot retry \u003cjob-id\u003e\n/gitmoot resume \u003cjob-id\u003e retry|continue|abort|answer [instructions]\n@project-planner ask What is blocking this PR?\n```\n\nA bare `@\u003cagent\u003e \u003caction\u003e` mention works as the same command; with the daemon's\n`--watch-issues` flag (on by default in `gitmoot setup`) mentions on **issues**\nare routed too. `/gitmoot resume` continues a delegation tree paused for a\nhuman (`escalate_human` failures or ask-gate questions) — the daemon @-tags you\nwith the exact resume command when a tree pauses.\n\nFor the full walkthrough, see [docs/local-workflow.md](docs/local-workflow.md).\n\n### Operate the daemon\n\n```sh\ngitmoot daemon status                 # scheduler mode, workers, runtime auth\ngitmoot daemon start --parallel 5     # run queued jobs 5-wide (pool scheduler)\nkill -HUP \u003cdaemon-pid\u003e                # live-reload [daemon] poll/workers/scheduler — no restart\ngitmoot daemon restart                # restart WITHOUT losing the persisted Claude token\ngitmoot daemon stop [--forget-runtime-auth]\n```\n\nReconfigure live with SIGHUP (#577) instead of restarting: the running daemon\nre-reads the `[daemon]` config keys with no teardown, dropped jobs, or env\nre-inheritance. Cap a single repo from config with `[repos.\"owner/repo\"]\nmax_parallel = N` (#576) — applied live, no relaunch. Runtime auth survives\nrestarts (#578): the daemon persists its Claude token to a 0600\n`daemon-runtime.env` file, `daemon restart` recovers it even from a token-less\nshell (plain `stop`+`start` does not), and `--forget-runtime-auth` deletes it.\nAn opt-in `[events]` webhook streams `job.finished/failed/blocked/\nneeds_attention/deferred` and `candidate.*` events to one HTTP endpoint\n([docs/events.md](docs/events.md)).\n\n## Core Concepts\n\n- **Repo**: a GitHub repository plus local checkout path that Gitmoot is allowed\n  to monitor and mutate.\n- **Daemon**: the local background process that polls GitHub PRs and routes\n  queued jobs. Passing `--repo owner/repo` scopes it to that single repo\n  (polling + job claims); omit `--repo` and it supervises every enabled repo\n  (cap one repo via `[repos.\"owner/repo\"] max_parallel`).\n  `--session \u003croot-job-id\u003e` scopes it to one orchestration run.\n- **Agent**: a named Gitmoot identity with repo access, role, capabilities, and\n  a runtime adapter.\n- **Runtime adapter**: the bridge from Gitmoot jobs to Codex, Claude Code,\n  Kimi Code, shell commands, or future runtimes.\n- **Template**: cached prompt content attached to an agent and snapshotted into\n  each job.\n- **Job**: a routed unit of work created from a PR comment, local ask, task run,\n  retry, or merge action.\n- **Goal and task**: Markdown implementation plans imported into local Gitmoot\n  state with `gitmoot goal import`.\n- **Branch lock**: local coordination state that prevents multiple agents from\n  racing on the same branch.\n\n## Common Workflows\n\n### Planner Agent\n\nGitmoot includes `planner` for structured implementation planning\nand standard goal-file writing.\n\n```sh\ngitmoot agent template update planner\ngitmoot agent start project-planner \\\n  --runtime codex \\\n  --repo owner/repo \\\n  --path . \\\n  --template planner \\\n  --start-daemon\n```\n\n### Review Agent\n\nGitmoot includes `thermo-nuclear-code-quality-review` for strict review-only\nwork.\n\n```sh\ngitmoot agent template update thermo-nuclear-code-quality-review\ngitmoot agent start thermo-review \\\n  --runtime codex \\\n  --repo owner/repo \\\n  --template thermo-nuclear-code-quality-review \\\n  --start-daemon\n```\n\nAsk it from a PR comment:\n\n```text\n/gitmoot thermo-review review\n```\n\n### Coordinator Recipes\n\nCoordinator recipes are built-in templates that turn the Orchestra pattern into\none command. Each runs a coordinator that fans work out to ephemeral workers (no\npre-registration) and reconvenes them in a single continuation. `review-panel`\nconvenes a panel of diverse-lens reviewers over a PR and synthesizes one verdict;\n`decompose-and-verify` splits an implementation task into parallel, file-disjoint\nlegs and runs a verify step that depends on all of them; `verifier` is the\nminimal produce-vs-independent-check pair (one producer leg plus one read-only\nverify leg on a different runtime). Route any coordinator agent through a\nrecipe with `--recipe`:\n\n```sh\ngitmoot orchestrate project-planner \"Review PR #123 in this repo.\" --repo owner/repo --recipe review-panel\ngitmoot orchestrate project-planner \"Implement the export feature described in the task.\" --repo owner/repo --recipe decompose-and-verify\ngitmoot orchestrate project-planner \"Implement the rate limiter and prove it works.\" --repo owner/repo --recipe verifier\n```\n\n### Custom Prompt Agents\n\nCustom agent templates let you keep a local template file and bind its\nsnapshotted instructions to any Gitmoot agent.\n\n```sh\nmkdir -p agents\ngitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md\n$EDITOR agents/frontend-reviewer.md\ngitmoot agent template validate agents/frontend-reviewer.md\ngitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md\ngitmoot agent start frontend-reviewer \\\n  --runtime codex \\\n  --repo owner/repo \\\n  --template frontend-reviewer \\\n  --role reviewer \\\n  --capability ask \\\n  --capability review\n```\n\nAfter editing the template file, refresh the cached snapshot:\n\n```sh\ngitmoot agent template diff frontend-reviewer\ngitmoot agent template update frontend-reviewer\n```\n\nTemplate updates are versioned locally. `gitmoot agent template show \u003cid\u003e`\nprints the current version, content hash, source commit, and promotion state.\nAgents use the current promoted version by default, or a pinned version when\nconfigured with a reference such as `--template frontend-reviewer@v1`.\nQueued jobs keep the exact template content snapshot they were created with.\n\nDiscover templates by metadata:\n\n```sh\ngitmoot agent template list --runtime codex --output goal_file\ngitmoot agent template list --tag review --capability ask\ngitmoot agent template show frontend-reviewer\n```\n\nBack up and share templates via a GitHub repo (#476):\n\n```sh\ngitmoot agent template remote set owner/my-templates   # default remote ([template_remote]; ref=main, path=templates/)\ngitmoot agent template publish --all                   # commit templates to the remote (--create makes the repo)\ngitmoot agent template pull frontend-reviewer          # install/refresh from the remote\ngitmoot agent template add frontend-reviewer --from-repo owner/my-templates\n```\n\nTemplates are stored and published **verbatim** (prompt body + metadata) —\npoint the remote at a private repo unless the prompts are meant to be public.\n\nReuse a custom agent prompt in the current Codex or Claude chat without\nstarting a background job:\n\n```text\nUse frontend-reviewer here. Review this diff.\n```\n\nThe runtime should load the prompt with:\n\n```sh\ngitmoot agent prompt frontend-reviewer\n```\n\n### Template Capture\n\nTemplate capture turns a useful current Codex or Claude chat workflow into a\nreusable agent template. Capture happens in the current chat from visible\nconversation context and inspected files; Gitmoot does not read hidden model\nstate or runtime memory.\n\nDraft a blank structure when starting from scratch:\n\n```sh\ngitmoot agent template draft release-planner\n```\n\nOr ask the current chat to fill the structure from the visible session:\n\n```text\nUse Gitmoot to capture this session as agent template release-planner. Draft only.\n```\n\nReview the draft before installing it:\n\n```sh\ngitmoot agent template validate .gitmoot/templates/release-planner.md\ngitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md\ngitmoot agent prompt release-planner\n```\n\nInstalled custom templates are snapshots. After editing the source file, run\n`gitmoot agent template diff \u003cid\u003e` and `gitmoot agent template update \u003cid\u003e`.\n\n### Dashboard Cockpit\n\nOn a terminal, `gitmoot dashboard` opens an interactive TUI that can act on\neverything it shows: answer prompts and retry blocked/failed jobs from the\nAttention page (plus `s` to restart a stopped daemon), open/stop/delete train\nsessions (with optional cleanup of GitHub repos gitmoot created for them),\ncreate/delete agents, revert a template to a previous version, start a training\nrun for an agent with a codex/claude backend pick (`o`), and cancel queued or\nrunning jobs. For failed, blocked, or cancelled jobs, `B` opens a redacted bug\nreport preview and `g` creates or reuses a GitHub issue. Press `?` on any page\nfor its keys. Piped/`--plain`/`--json` output is unchanged and script-stable.\n\n```sh\ngitmoot dashboard           # interactive cockpit\ngitmoot dashboard --json    # one-shot snapshot for scripts\ngitmoot dashboard --web [--addr 127.0.0.1:8080]   # read-only web dashboard\n```\n\n`gitmoot dashboard --web` serves a read-only browser view — a live\norchestration/delegation graph with run summaries and prompt/output\ninspection — until interrupted.\n\nAgents should answer directly from the SessionStart snapshot or read-only CLI\nchecks first. The dashboard remains the live cockpit for humans.\n\n### Heartbeat Schedules\n\nHeartbeats let the daemon run recurring agent work itself — cron-like\nbackground jobs without an external cron (off by default):\n\n```sh\ngitmoot agent heartbeat add repo-maintainer daily-status \\\n  --repo owner/repo --interval 24h --prompt \"Daily status report.\" --enabled\ngitmoot agent heartbeat list\n```\n\nSee [docs/heartbeats.md](docs/heartbeats.md).\n\n### Jobs, Locks, And Recovery\n\n```sh\ngitmoot status --repo owner/repo\ngitmoot events --repo owner/repo\ngitmoot job list --repo owner/repo\ngitmoot job show \u003cjob-id\u003e\ngitmoot job events \u003cjob-id\u003e\ngitmoot job retry \u003cjob-id\u003e\ngitmoot job cancel \u003cjob-id\u003e\ngitmoot job kill \u003croot-job-id\u003e\ngitmoot report bug --job \u003cjob-id\u003e [--preview]\ngitmoot report bug --job \u003cjob-id\u003e --create --yes\ngitmoot daemon logs\ngitmoot lock list --repo owner/repo\ngitmoot lock release owner/repo \u003cbranch\u003e --owner \u003cagent\u003e\n```\n\n`gitmoot job kill \u003croot-job-id\u003e` is the operator kill switch for a whole\ndelegation tree: in-flight jobs finish, the coordinator's next continuation is\nrouted through the graceful finalize path, and the daemon stops starting queued\nchildren of that root.\n\n`gitmoot report bug` builds a redacted issue draft with job context, selected\nerror, recent events, redaction notes, labels, and a duplicate-detection\nfingerprint. Agents should preview first and create only when the user explicitly\nasks or the active workflow policy allows filing the report, then return the\ncreated or existing issue URL.\n\n### SkillOpt Exchange\n\n```sh\ngitmoot skillopt train init --name \u003cname\u003e --template \u003cid\u003e --review-repo owner/repo --artifact-kind kind --preview kind (--request text|--request-file path)\ngitmoot skillopt train init templates --json\ngitmoot interactive list --state pending --json\ngitmoot interactive show \u003cprompt-id\u003e --json\ngitmoot interactive answer \u003cprompt-id\u003e \u003cvalue\u003e --source agent\ngitmoot skillopt train start --config .gitmoot/skillopt/\u003cname\u003e/config.toml --workspace-repo \u003cowner/repo\u003e --yes\ngitmoot skillopt review create --template \u003cid\u003e --repo owner/repo --run \u003crun-id\u003e\ngitmoot skillopt review item add --run \u003crun-id\u003e --item \u003citem-id\u003e --baseline baseline.md --candidate candidate.md [--title text]\ngitmoot skillopt review create --template \u003cid\u003e --repo owner/repo --run \u003crun-id\u003e --mode explore --options 4\ngitmoot skillopt review item add --run \u003crun-id\u003e --item \u003citem-id\u003e --option a=option-a.md --option b=option-b.md [...]\ngitmoot skillopt review status --run \u003crun-id\u003e\ngitmoot skillopt export --run \u003crun-id\u003e --output training.json\ngitmoot skillopt import --file candidate.json [--artifact-dir artifacts]\ngitmoot skillopt candidate list [--template id]\ngitmoot skillopt candidate show \u003cversion-id\u003e\ngitmoot skillopt candidate promote \u003cversion-id\u003e\ngitmoot skillopt candidate reject \u003cversion-id\u003e [--reason text]\ngitmoot skillopt feedback markdown export --run \u003crun-id\u003e --output .gitmoot/evals/\u003crun-id\u003e\ngitmoot skillopt feedback markdown import --packet .gitmoot/evals/\u003crun-id\u003e\ngitmoot skillopt feedback github publish --run \u003crun-id\u003e [--repo owner/repo] [--pr \u003cnumber\u003e]\ngitmoot skillopt feedback github sync --run \u003crun-id\u003e [--repo owner/repo] (--issue \u003cnumber\u003e|--pr \u003cnumber\u003e)\n```\n\nUse `skillopt train init` to create a local scaffold under\n`.gitmoot/skillopt/\u003cname\u003e/` without starting model work. The scaffold pins the\ntemplate/version, writes `config.toml`, `task.md`, and starter\n`review-items.yml`, and prints the exact `train start --config` command. Agents\ncan list template choices with `train init templates --json`; when an\ninteractive setup needs missing values, they can answer the stored prompts with\n`gitmoot interactive list/show/answer`. On a real terminal, missing fields are\ncollected through an interactive form (arrow-key template/preview pickers, inline\nvalidation); each field is still published as a prompt record, so another\nterminal can answer it with `gitmoot interactive answer` and the form advances\nautomatically. Set `GITMOOT_NO_TUI=1` (or pipe stdin) to use the line-based\nwizard instead.\n\nOn a real terminal, `gitmoot skillopt train run [--config path | --session \u003cid\u003e]`\nopens an interactive view of one train session: a phase bar\n(generate → review → optimize → promote) and a single keypress per step — `enter`\ngenerates options / publishes the review / syncs feedback / runs the optimizer\n(the long generate and optimizer steps run in a detached background process, so\nquitting the TUI with `q` leaves the run going), `p`/`x` promote or reject a\ncandidate, `n` starts the next iteration. At a review-blocked phase it shows the\nGitHub issue link so you can instead comment on the issue and let the\nreview-watcher continue. Piped/`--plain`/`GITMOOT_NO_TUI` print a one-shot status\nsnapshot. Pass `--create-repos` to `train start` (or accept the in-form prompt\nduring `train init`) to create a missing target/workspace/review repo on GitHub.\n\nFor lower-level debugging, create a review run, add saved baseline/candidate outputs as review items,\nexport a Markdown or GitHub feedback packet, import the completed feedback, then\nexport `training.json` for a future external `gitmoot-skillopt` optimizer.\nUse ranked exploration when the template needs broad search: start with\n`--mode explore --options 4` to `6`, rank every option, record useful/rejected\ntraits, then narrow into `refine`, `distill`, and finally A/B `validate`.\n`skillopt review status` reports ranking stability and the recommended next\nmode, but the recommendation is advisory only.\nDry-run optimization validates the contract without model calls:\n\n```sh\ngitmoot-skillopt optimize \\\n  --training-package training.json \\\n  --artifact-root ~/.gitmoot/evals/blobs \\\n  --out-root .gitmoot/skillopt/run-2026-05-31 \\\n  --candidate-output candidate.json \\\n  --dry-run\n```\n\nBefore real model-backed optimization, run `gitmoot-skillopt optimize --help`\nand verify required model/backend environment variables for the installed\noptimizer version. Imported candidates stay pending until a human review\nworkflow promotes them.\nWhen a candidate package includes new artifact manifest entries, pass\n`--artifact-dir` to the directory containing those files; Gitmoot verifies\nrelative paths and SHA256 hashes before storing blobs.\nThe external optimizer walkthrough lives in\n[`jerryfane/gitmoot-skillopt`](https://github.com/jerryfane/gitmoot-skillopt/blob/main/docs/guide/gitmoot-mvp-workflow.md).\nUse `skillopt candidate show` to inspect the candidate metadata, eval report,\nfeedback summary, and content diff before `promote` or `reject` records the\ndecision.\n\nUse the Markdown feedback collector for a local blind A/B packet: open\n`index.md`, review `items/*.md`, set `reviewer`, edit `feedback.yml` with `a`,\n`b`, `tie`, `neither`, or `skip`, and import it. Keep `.assignments.json`\nuntouched so Gitmoot can validate and de-blind the mapping.\n\nUse the GitHub feedback collector when review should happen in an issue or an\nexisting PR thread. Reviewers can reply with either the copy-paste YAML block or\nrun-scoped short lines such as `run_id: run-1` followed by\n`item-001: b - More concrete.`. Gitmoot imports matching comments into\ncanonical feedback events and ignores unrelated comments. Repo selection uses\n`--repo`, then the eval run target repo, then the template source repo, then\noptional `[feedback].repo = \"owner/reviews\"` in Gitmoot config.\n\nDetailed ranked exploration examples, including a landing-page visual task and\na non-visual writing task, live in\n[docs/skillopt-exchange-contract.md](docs/skillopt-exchange-contract.md).\n\nDetailed command coverage lives in\n[skills/gitmoot/references/CLI.md](skills/gitmoot/references/CLI.md).\n\n## Plugins\n\nGitmoot can package its Agent Skill for Codex and Claude Code so the runtime\ncan discover Gitmoot guidance from its plugin system.\n\n```sh\ngitmoot plugin install codex\ngitmoot plugin install claude\ngitmoot plugin doctor\ngitmoot plugin codex-launch --repo .\n```\n\nPlugins do not start a hosted service, replace the daemon, subscribe agents, or\nmutate repository state by themselves. See [docs/plugins.md](docs/plugins.md)\nfor install details and troubleshooting.\n\n## Documentation\n\n- [Hosted docs](https://gitmoot.io/docs/intro)\n- [LLM index](https://gitmoot.io/llms.txt) — machine-readable docs index; agents start here (full context: [llms-full.txt](https://gitmoot.io/llms-full.txt))\n- [Agent Skills package](skills/gitmoot/SKILL.md)\n- [CLI reference](skills/gitmoot/references/CLI.md)\n- [Codex and Claude plugins](docs/plugins.md)\n- [Local workflow walkthrough](docs/local-workflow.md)\n- [Run jobs in parallel](docs/parallel-jobs.md)\n- [Heartbeat schedules](docs/heartbeats.md)\n- [Outbound event stream](docs/events.md)\n- [Cockpit and the [orchestrate] config](docs/cockpit-orchestrate.md)\n- [Beta smoke tests](docs/beta-smoke-tests.md)\n- [Runtime adapter authoring](docs/adapters.md)\n- [Troubleshooting](docs/troubleshooting.md)\n\n## Status And V1 Limits\n\n- Local-only: no hosted dashboard, GitHub App bot identity, cloud runner, or\n  remote control plane.\n- Polling watches GitHub PRs; there is no webhook receiver in V1.\n- GitHub comments are authored by the authenticated `gh` user. Agent identity\n  appears in the comment body.\n- Local SQLite remains the workflow source of truth.\n\n## Contributing\n\nGitmoot is early. Keep changes scoped, preserve local-first behavior, and add\nfocused tests for runtime, CLI, daemon, plugin, or workflow changes. Before\nopening a PR, run the relevant checks for the files you touched.\n\n## License\n\nGitmoot is licensed under the [Apache License 2.0](./LICENSE). See\n[NOTICE](./NOTICE) for copyright and attribution details.\n\n## Development\n\n```sh\ngo test ./...\ngo vet ./...\n```\n\nGitHub Actions enforces the same gate on every push to `main` and every pull\nrequest: build, vet, and test, plus the race detector on `internal/workflow`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerryfane%2Fgitmoot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjerryfane%2Fgitmoot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerryfane%2Fgitmoot/lists"}