Sync accepted GitHop state and prompt records
This commit is contained in:
Hop
@@ -1,97 +1,66 @@
|
||||
# Hop
|
||||
# HopWeb
|
||||
|
||||
**Prompt-native version control for coding agents.**
|
||||
HopWeb is a collaborative forge for prompt-native software development.
|
||||
|
||||
Hop remembers why code changed, not just what changed. Every instruction becomes
|
||||
a durable project state before an agent starts working. Agents get isolated
|
||||
workspaces, validate the final result, and safely land accepted work in the
|
||||
project folder you opened.
|
||||
It uses Git for durable source storage and Gitea for the proven forge substrate,
|
||||
but makes Hop's workflow the primary product model:
|
||||
|
||||
Git remains the source-tree and interoperability layer. Hop adds the context
|
||||
agent workflows are missing: prompts, lineage, checkpoints, validation evidence,
|
||||
and safe multi-agent integration.
|
||||
- a **task** captures the outcome someone wants;
|
||||
- a **prompt state** records each instruction in its causal context;
|
||||
- an **attempt** is an isolated line of human or agent work;
|
||||
- a **checkpoint** freezes the exact tree that was evaluated;
|
||||
- **evidence** records checks against that immutable checkpoint;
|
||||
- a **proposal** is a reviewable candidate outcome; and
|
||||
- an **accepted state** is the current shared truth.
|
||||
|
||||
## Why Hop
|
||||
The repository **Prompts** view is the review surface for that causal record:
|
||||
the requested work, agent identity and runtime metadata, response summary, and
|
||||
links to the task, attempt, and immutable state that produced it.
|
||||
|
||||
- **Intent is versioned.** Each prompt is connected to the code it produced.
|
||||
- **Agents stay isolated.** Parallel tasks do not edit the same working folder.
|
||||
- **Integration is intelligent.** Compatible changes merge automatically;
|
||||
genuine conflicts return to an agent for reconciliation.
|
||||
- **Validation follows the code.** Checks run against immutable work and the
|
||||
exact final tree before it becomes accepted.
|
||||
- **Accepted work is visible.** Successful results appear in the selected
|
||||
project folder without moving your active Git branch or index.
|
||||
- **Publishing is automatic.** When an upstream branch exists, each accepted
|
||||
transition is pushed without moving the local branch or force-pushing.
|
||||
- **History stays local by default.** Detected credentials are redacted before
|
||||
prompts and evidence are persisted.
|
||||
Hop automatically writes immutable, portable prompt records to
|
||||
`.hop/records/prompts/` when it creates a proposal. Git tracks those records
|
||||
with the code, while Hop's local database and disposable workspaces remain
|
||||
ignored. Run `make hop-records` to export the complete local record history on
|
||||
demand.
|
||||
|
||||
## How it works
|
||||
The product thesis is simple:
|
||||
|
||||
```text
|
||||
prompt → durable intent → isolated agent work → validate + merge → accepted code
|
||||
```
|
||||
> GitHub organizes collaboration around commits and pull requests. HopWeb
|
||||
> organizes human-agent collaboration around intent, attempts, evidence, and
|
||||
> accepted outcomes.
|
||||
|
||||
Hop ships an open [Agent Skills](https://agentskills.io/) bundle and a controller
|
||||
protocol. The skill makes prompt capture the agent's first repository action; a
|
||||
controller can capture before model delivery. Both use the same state,
|
||||
workspace, validation, reconciliation, and landing protocol. Codex Desktop is
|
||||
one bundled integration, not a boundary of the product.
|
||||
## Foundation
|
||||
|
||||
## Install
|
||||
Gitea supplies the expensive, mature infrastructure we should not rebuild:
|
||||
|
||||
Hop requires Git 2.40 or newer.
|
||||
- Git transport, repositories, LFS, and permissions
|
||||
- users, organizations, teams, OAuth, and access tokens
|
||||
- issues, notifications, webhooks, releases, packages, and Actions
|
||||
- administration, audit surfaces, and deployment primitives
|
||||
|
||||
### macOS and Linux
|
||||
Hop supplies the differentiating control plane and experience:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://githop.xyz/GnosysLabs/Hop/raw/branch/main/scripts/install.sh | sh
|
||||
```
|
||||
- prompt and state graph persistence
|
||||
- task and attempt orchestration
|
||||
- agent identity and attribution
|
||||
- checkpoint-bound validation evidence
|
||||
- proposal review and acceptance semantics
|
||||
- a Hop-native repository, task, attempt, and review interface
|
||||
|
||||
### Windows PowerShell
|
||||
See [the product blueprint](docs/product-blueprint.md) and
|
||||
[the Gitea foundation decision](docs/adr/0001-gitea-as-forge-foundation.md).
|
||||
|
||||
```powershell
|
||||
irm https://githop.xyz/GnosysLabs/Hop/raw/branch/main/scripts/install.ps1 | iex
|
||||
```
|
||||
## First release
|
||||
|
||||
The installer adds the Hop CLI and writes the same embedded skill version to
|
||||
`~/.agents/skills/hop` and `${CODEX_HOME:-~/.codex}/skills/hop`. For CLI-only
|
||||
installation, source builds, version pinning, custom locations, and
|
||||
verification, see the
|
||||
[installation guide](https://githop.xyz/GnosysLabs/Hop/wiki/Installation).
|
||||
The first useful release is not a complete GitHub clone. It is a private,
|
||||
single-installation forge where a user can:
|
||||
|
||||
## Get started
|
||||
1. create or import a repository;
|
||||
2. open a task with a prompt;
|
||||
3. launch one or more isolated agent attempts;
|
||||
4. watch states, diffs, and checks appear live;
|
||||
5. compare proposals by outcome and evidence; and
|
||||
6. accept one proposal into the repository's shared state.
|
||||
|
||||
1. Install Hop.
|
||||
2. Open a Git project in an Agent Skills-compatible client, or make it the
|
||||
controller's working directory.
|
||||
3. Ask the agent to make a change as you normally would.
|
||||
|
||||
That is the full user workflow. You do not run `hop init`, route prompts through
|
||||
a terminal, or work inside `.hop` yourself. After a task, `hop status` shows the
|
||||
accepted state and whether the visible project folder is synchronized.
|
||||
When the repository has an unambiguous Git upstream, Hop also pushes the
|
||||
accepted commit automatically; users do not run `git push` after each task.
|
||||
|
||||
For example, Codex Desktop users restart Codex after installation, select a Git
|
||||
project, and prompt normally. Other compatible runtimes can read the shared
|
||||
skill bundle or receive a single-target installation with the explicit
|
||||
`hop skill install --path /path/to/agent/skills --force` form.
|
||||
|
||||
Hop is currently an early alpha. Expect its state model and CLI to evolve before
|
||||
1.0.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Getting started](https://githop.xyz/GnosysLabs/Hop/wiki/Getting-Started)
|
||||
- [Agent workflow](https://githop.xyz/GnosysLabs/Hop/wiki/Agent-Workflow)
|
||||
- [Parallel agents and conflicts](https://githop.xyz/GnosysLabs/Hop/wiki/Parallel-Agents-and-Conflicts)
|
||||
- [Core concepts](https://githop.xyz/GnosysLabs/Hop/wiki/Core-Concepts)
|
||||
- [CLI reference](https://githop.xyz/GnosysLabs/Hop/wiki/CLI-Reference)
|
||||
- [Security and privacy](https://githop.xyz/GnosysLabs/Hop/wiki/Security-and-Privacy)
|
||||
- [Architecture](https://githop.xyz/GnosysLabs/Hop/wiki/Architecture)
|
||||
- [Product blueprint](docs/product-blueprint.md)
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE) © 2026 Gnosys Labs LLC.
|
||||
Everything else should be inherited from Gitea until the Hop workflow proves
|
||||
that it needs a different abstraction.
|
||||
|
||||
Reference in New Issue
Block a user