About Hopper,
the things you'll probably want to clear up first

No. Hopper doesn't write code itself, and it isn't a coding agent. It handles acceptance and cost control for AI-written code: you write your requirements as Markdown and drop them in, and it handles triage, queueing, isolation, invoking the agents that actually write the code (Claude Code / Codex), running verification and acceptance gates itself, handing the result to you for review, and merging. Think of it as the "delivery gate plus cost hub for AI coding," not yet another coder AI.

They're complementary. Claude Code / Codex are the execution backends (runners) that actually change code inside an isolated worktree; Hopper is the acceptance and control layer around them, managing intake, dependencies, concurrency, isolation, quality gates, review, and merge. The runner is swappable — today it's Claude/Codex, tomorrow you could plug in a different execution backend.

Those are task boards that record and track "what people need to do." Hopper is an assembly line that executes, actually turning a task into a code change, running it through quality gates, and handing it to you for review. A board stops at "assignment"; Hopper stops at "a reviewed change."

CI/CD runs the fixed scripts you've hard-coded (lint/test/build/deploy), and its input is "already-written code." Hopper drives AI to turn a single statement of intent into a code change — it sits before CI, turning an idea into a reviewable diff. The two coexist: Hopper produces the change, and your CI verifies it as usual. Also, hopper check works standalone: without adopting the Hopper pipeline, it runs the four acceptance gates on any repo's diff and produces a trust report with a single command.

Yes. Beyond the runner executing tasks, Hopper's own triage, prompt compilation, acceptance checking, and docs alignment are also LLM calls (collectively the meta_runner), and they count toward your usage too. But deterministic rules come first — anything that can be decided by rules doesn't call the LLM, so the meta overhead is usually very small.

The delivery gate for coding agents — AI writes the code, Hopper handles acceptance and cost control: you just write Markdown, and it turns your requirements into reviewed code changes reliably, auditably, and recoverably; the orchestration layer is the free foundation.

If you just want a chat-style AI to instantly change a line of code — using Claude Code / Codex directly is faster, and Hopper's pipeline is extra overhead. If your work doesn't involve a code repository, or you don't need auditing / isolation / quality gates, its value won't show. It's designed for cases where you "have a batch of requirements, want them advanced reliably in bulk, and care about control and auditability."

MIT licensed. Hopper itself is free; you only pay for the underlying runner (Claude/Codex subscription or API) and Hopper's own meta LLM calls, which count toward your existing usage.

The MVP main loop runs end to end (init → drop → triage → execution → quality gates → review → merge → recovery), with six layers of test coverage plus a platform contract-conformance layer; GitHub Issues and ZenTao Story intake also have fake / e2e coverage. But some capabilities are still fallback implementations (see which features aren't implemented). We recommend starting with low-risk tasks and dry-runs, then manually verifying the evidence at each step before scaling up.

Hopper itself is a purely local CLI with no server, and it doesn't upload your files. The only thing that goes over the network is the underlying runner and meta LLM calls (the Claude/Codex API) — that's what AI inference itself requires, the same as using them directly. Your files, state, and audit trail all stay local.

No. Everything is plain text on your machine — Markdown tasks + an append-only events.jsonl event stream. The vault is just an ordinary folder (also Obsidian-compatible); you can manage it directly with git and pack it up anytime. Delete Hopper and your docs and code are untouched.

Hopper has no database. The Markdown under ~/Hopper/ plus .hopper/events.jsonl is the entire source of truth — state can be fully rebuilt from the event stream, and it can be reconciled and recovered after a crash. This makes everything auditable, git-able, and inspectable by hand.

Two layers — machines read events.jsonl (fine-grained state, every step recorded), and humans read the coarse state in each task's frontmatter (received → ready → running → review → done). You don't need to, and shouldn't, write status by hand: it's projected from the event stream, and the write-back is protected (editing the body in Obsidian won't be overwritten).

A runner is the backend adapter that executes a task. claude / codex are real agents; fake is a real subprocess used for testing (script-controlled, so it runs end-to-end loops without burning real money). A task can specify which one to use, or leave it to Hopper to pick automatically.

Because a runner self-reporting "I'm finished" isn't trustworthy. As soon as the runner wraps up, Hopper runs 6 quality gates in order inside the isolated worktree: verification (running the frozen test/lint/build), deterministic guardrails, a risk re-review, item-by-item acceptance checking, docs alignment, and a run summary. If any hard gate fails, it's blocked. For code tasks you still have to review + merge before it's truly done.

The default safety boundaries — no push, no changes to main, no touching secrets / forbidden paths, no auto-executing high risk, no auto-merge. These are deterministic gates that backstop after the runner finishes, and they cannot be relaxed by the task body, external content, or the LLM.

Isolation. Each task runs in its own worktree + branch (hopper/<task>-<slug>), without interfering with others — serialized within the same repo, concurrent across repos; the worktree also has git push interception injected. If something goes wrong it only affects that isolated environment and won't pollute your main working tree.

In assisted mode, the runner stops at plan-step boundaries and raises a decision card, and the task waits in place for a human. You handle it in the Console's decision inbox or the CLI: hopper breakpoint list shows the cards, breakpoint release lets one through (with a note, or vetoes it), and breakpoint resume makes the same run continue in place — no starting over. It suits the middle trust tier: eyes on the key steps without babysitting the whole run.

The merge queue is an optional landing channel: once enabled, review approve enqueues the task, the queue worker is the only canonical landing writer, changes land one at a time, and generation fencing keeps a stale run's result from landing; operate it with hopper merge-queue list/run/release. It is not auto-merge — approve remains the human's irreversible decision; the queue only turns the "landing" step into controlled, serialized, auditable automation.

After you drop it, Hopper automatically: triages (deciding project / risk / runner) → queues (checking dependencies) → creates an isolated worktree → compiles the prompt → runs the runner → passes the 6 quality gates → advances the task to review, then stops to wait for you. You come back, look at the diff and evidence, and approve / send back / reject; once satisfied, hopper merge. In a sentence: the first half is fully automatic; approve and merge are always yours.

Your core actions are only three: write requirements, review, merge. You can start a daemon to advance tasks unattended in bulk — but the daemon advances tasks at most to review, never approving or merging for you, and by default only runs low risk automatically. The decision authority always stays in your hands; that's a hard boundary by design, not a limitation.

Four classes, all ultimately converging into Markdown in the vault: ① manual hopper drop file.md (quick drops); ② Obsidian (when you want to browse / edit / see the dependency graph); ③ a Claude Code / Codex session (have the AI write up a plan, then pipe it to hopper drop --stdin); ④ external requirement sources (GitHub Issues via hopper github sync, ZenTao Stories via hopper zentao import).

Three things determine quality: clear intent (what to do and why), checkable acceptance criteria (an Acceptance list that Hopper verifies against evidence item by item), and the necessary frontmatter (such as runner, risk, project). Vague intent or missing acceptance criteria, and the result is hard to guarantee.

hopper link-project --project my-app --repo /abs/path. It registers the project, writes .hopper.project.yml inside the repo, and creates a .hopper-inbox symlink to make dropping from within the repo convenient.

hopper github link associates the repository → hopper github sync pulls open issues matching the label into a bug-list → hopper scan breaks it into executable children. After fixing, you can hopper github sync-back to write the summary back to the original issue. One-way snapshot import — no two-way sync, and it doesn't auto-close issues.

After setting up site and product → project mapping in .hopper/zentao.toml, run hopper zentao doctor to check the connection, auth, and write-back carrier; then use hopper zentao import --product 1 --dry-run to preview, or hopper zentao import --story 109 to read-only import one Story. Imports dedupe via source_path: zentao://..., and the body is treated as external_untrusted.

After a fix, hopper zentao sync-back --task <id> previews by default and only publishes to ZenTao with --yes; it writes a Story comment by default, or custom fields with read-back verification when configured. hopper zentao pull only brings in close / spec / assignedTo suggestions and does not silently mutate Hopper state by default.

The most common cause is being blocked by the risk gate — sensitive words like token/auth/ci/deploy/session/payment in the body get conservatively judged as medium/high (the intentional "risk only goes up, never down"), and the daemon only runs low automatically. Other causes: the project isn't link-project'd (unregistered), dependencies aren't complete, or the pinned runner is unavailable. First run hopper queue explain, or look at the not_runnable_reasons in hopper status — it explains why it isn't runnable, one by one. To handle it: run medium manually with an attended hopper run (the daemon won't touch it, but a human can), tune sensitive_keywords for the project, or register the project with hopper link-project.

At hopper link-project time, verification commands are auto-detected by tech stack: Node with a test script→npm test, Python→pytest, Go→go test, Rust→cargo test, SwiftPM→swift build/test; multi-language sums up all matching stacks. If nothing is detected it writes an empty verification and says so explicitly — and verification is then not_run (it doesn't block, but doesn't guarantee compilation either). The verification plan in effect at the time is frozen before execution (a runner changing the test scripts doesn't affect this gate). To add / change commands, edit the verification in the project config.

Runners are configured in the runners: section of .hopper/config.yml. Claude uses ~/.claude auth by default, usually needing no extra config; for Codex we recommend setting home: ~/.codex explicitly — in some environments (such as inside another agent session) CODEX_HOME is pointed at a temp directory, and without this it can't pick up your login state. Confirm both are logged in before running (runner probe only checks whether the command is on PATH, not whether auth works). We recommend getting a single task working with hopper run first, then moving to concurrency / daemon.

No. By default it doesn't push, doesn't auto-merge, and doesn't change main — that's a deterministic guardrail. The worktree also intercepts git push. Merging is always your explicit hopper merge, and it runs a smoke verification once more before merging.

No. All Markdown / external content (including GitHub issue bodies and ZenTao Story descriptions) is treated as untrusted input, gets flagged, and has no authority to relax any guardrail. The deterministic gates backstop after the runner finishes, and the LLM cannot lower safety rules or dial risk down either. This is a hard design against prompt injection.

Because "events come before side effects" (RunReserved is written before the worktree is created), after a crash hopper reconcile can reconcile the scene, release stale locks, and recover or explain the interrupted run. hopper doctor gives a health report. There's no "stuck in an unexplainable state."

No. Protection for secrets / forbidden paths (such as .env*, secrets/**) is a deterministic guardrail — if a task's changes touch them it's blocked, and it can't be relaxed. You can also extend forbidden_paths in the project config.

usage / rate-limit are hard gates (no scheduling if there isn't enough); USD cost is soft accounting (a run-level cost ledger). Check with hopper usage / hopper budget. A hard budget cap has to be turned on explicitly by you; budget envelopes raise tiered alerts at 70 / 85 / 100% burn, and runs with unknown cost are listed separately as unknown — never counted as zero. Note that Hopper's own meta LLM calls count too.

Yes. But it's subject to multiple constraints: serialized within the same repo, concurrent across repos, layered with the usage gate, budget, the risk allowlist (daemon only low risk), the dependency DAG, and a global concurrency cap. Merge is always serialized. Defaults are conservative (claude 1 / codex 1). To make the same runner truly run multiple tasks concurrently: raise global_max_concurrency, set that runner's fallback_concurrency to ≥2 (when there's no trusted usage data on real agents, concurrency is computed from this, not max_concurrency), and have those tasks land in different repos (the same repo gets serialized by the repo lock).

An honest list: the daemon polls rather than watching files; the /hopper-drop slash command isn't implemented (use drop --stdin); drop --dedupe, retry --verification-plan new, auto-merge that skips human approve, automatic PRs, full Windows support, and so on are still blueprints. What has landed: real 5h/7d usage reads (Claude OAuth endpoint / Codex session snapshot; when unreadable it says unknown and schedules conservatively) + a per-run cost ledger, budget gates and budget envelopes (70/85/100% alerts), multiple runner profiles (exact pin / kind: rotation / round-robin, verified on real agents across multiple concurrent sessions), authoring helpers new/lint, standalone hopper check, a local Console GUI bound to 127.0.0.1 (Control Room / decision inbox / bug report form / task actions), assisted-mode breakpoint cards, the merge queue, the external-orchestrator integration surface (RunSettled / capabilities / --req-id idempotency keys), GitHub Issues intake, and ZenTao Story read-only import, manual write-back, and pull suggestion sync. See the current implementation boundaries in llms-full.

Yes. Hopper is a CLI, and the most reliable way: drop with cat needs.md | hopper drop --stdin --project X → hopper scan && hopper triage → hopper run next → present the hopper review diff and evidence to the human to decide. Note: approve / merge are the human's irreversible decisions; the AI should stop at "ready for review" and not approve / merge for the user.

Yes. Almost every command supports the global --json (machine-consumable), and --debug, --vault <path> are available everywhere too. State can be read by projecting from events.jsonl, or with hopper status --json / hopper show <id> --json. The schema source of truth is zod, exported as JSON Schema.

You receive the prompt compiled by the Task Compiler — containing the task context, acceptance criteria, guardrails, and context manifest. You return a structured result (outcome: completed / needs_review / failed …, plus changed files + test results). Note: the outcome you self-report is not the final state — Hopper runs the frozen verification plan and a quality-gate re-review itself, and you can't change your own report card.