지속적인 히스토리와 재사용 가능한 워크플로우를 통해 Claude Code 및 Cursor와 같은 로컬 헤드리스 에이전트에 코딩 작업을 할당합니다.
다른 이름 Harflow-Dev/HarflowMCP, harflowmcp
- 스타
- 1
- Tools
- —
- 다운로드, 30일
- 3,545
- 최신 버전
- 0.0.14
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
Harflow MCP란?
Harflow은(는) MCP server입니다. 지속적인 히스토리와 재사용 가능한 워크플로우를 통해 Claude Code 및 Cursor와 같은 로컬 헤드리스 에이전트에 코딩 작업을 할당합니다.
프로젝트 README에서 생성된 요약
Harflow MCP server 정보
HarflowMCP는 Claude Code, Cursor Agent CLI, Codex, opencode, Vibe, Antigravity를 포함한 다양한 헤드리스 에이전트에 코딩 작업을 할당하도록 설계된 로컬 MCP server입니다. 개발자는 지속적인 작업 히스토리와 구축된 워크플로우 재사용 기능을 통해 복잡한 프로그래밍 워크플로우를 관리할 수 있습니다. 이 server는 로컬에서 작동하며, 지원되는 Claude Code 버전에서 개별 Bash, Read, Write 또는 Edit 요청을 하나씩 승인하는 것과 같은 고급 권한 제어를 지원합니다.
사용자는 allowed_commands와 같은 기능을 통해 무제한 권한 대신 특정 Bash 접근 권한만 부여함으로써 세밀한 보안을 구현할 수 있습니다. Cursor 사용자의 경우, 헤드리스 할당을 위해 agent login 또는 CURSOR_API_KEY가 필요합니다. 시스템은 작업 취소, 대기 중인 실행 확인, 상태 점검을 지원하는 harflow-ctl CLI 도구를 통해 상세한 작업 관리 기능을 제공합니다. 이는 도구의 영향과 명령어 실행을 엄격하게 감독하면서 여러 에이전트를 오케스트레이션해야 하는 개발자에게 특히 유용합니다.
활용 사례
- 1세밀한 명령어 권한 제어개발자는 에이전트에게 무제한 권한을 주는 대신 특정 Bash 명령어 목록으로 권한을 제한할 수 있습니다.
- 2헤드리스 Cursor 에이전트 관리API 키를 제공하거나 agent login을 수행하여 Cursor를 헤드리스 모드로 실행할 수 있습니다.
- 3활성 코딩 작업 취소특정 ID를 사용하여 실행 중인 작업을 중단하고 취소 시의 최종 상태를 확인할 수 있습니다.
- 4거부된 요청으로부터의 복구에이전트의 요청이 거부된 경우, 특정 재개 명령어를 사용하여 프로세스를 다시 시작할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Harflow MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Harflow MCP 설치
$ claude mcp add harflowmcp -- uvx harflow-mcpCursor에 Harflow MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"harflowmcp": {
"command": "uvx",
"args": [
"harflow-mcp"
]
}
}
}VS Code에 Harflow MCP 설치
.vscode/mcp.json
{
"servers": {
"harflowmcp": {
"type": "stdio",
"command": "uvx",
"args": [
"harflow-mcp"
]
}
}
}VS Code CLI에 Harflow MCP 설치
$ code --add-mcp '{"name":"harflowmcp","type":"stdio","command":"uvx","args":["harflow-mcp"]}'Claude Desktop에 Harflow MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"harflowmcp": {
"command": "uvx",
"args": [
"harflow-mcp"
]
}
}
}Codex에 Harflow MCP 설치
$ codex mcp add harflowmcp -- uvx harflow-mcpCodex config.toml에 Harflow MCP 설치
~/.codex/config.toml
[mcp_servers.harflowmcp] command = "uvx" args = ["harflow-mcp"]
Gemini CLI에 Harflow MCP 설치
$ gemini mcp add -s user harflowmcp uvx -- harflow-mcpGemini settings.json에 Harflow MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"harflowmcp": {
"command": "uvx",
"args": [
"harflow-mcp"
]
}
}
}자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능harflow-dev/harflowmcp is public and reachablegithub.com/harflow-dev/harflowmcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)Sigstore attestation for harflow-mcppypi.org/project/harflow-mcp/ ↗통과
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-14github.com/harflow-dev/harflowmcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from harflow-mcp통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음the package checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기HarflowMCP
HarflowMCP is a local MCP server that dispatches coding tasks to Claude Code, Codex, opencode, Vibe, Antigravity, and the Cursor Agent CLI. It provides persistent task history, bounded reads, cancellation, continuation, and reusable workflows. On measured Claude Code versions, callers can opt in to approving individual Bash, Read, Write and Edit requests one exact action at a time (see harness permissions); on macOS with codex-cli 0.163.0 the same opt-in approves individual Codex commands and, with caller_write_approvals, patches through codex app-server (see Codex caller approvals), and can grant a task a bounded list of specific Bash commands with allowed_commands instead of unrestricted access (see dispatch-time command grants).
Signing into the Cursor editor does not sign in the agent CLI. Headless Cursor dispatch needs agent login or CURSOR_API_KEY. Confirm with agent status: it has to report an access token. That check reads the CLI credential store for the current HOME, so a shell whose home directory is somewhere else still says it is not logged in after a successful agent login. Cursor refuses caller approvals and allowed_commands. Its read_only launch asks for plan mode; write_in_repo, publish, and unrestricted share one print-mode command until a measured boundary separates them. There is no live follow-up on stdin. The pinned CLI is 2026.10.22-27dcf5f on macOS arm64. See harness permissions and backend CLI facts.
MCP task status and single-task waits default to compact polling while preserving the complete
final summary, approval attention and recovery diagnostics. Use detail="full" for execution
metadata; include_tail=true explicitly includes the raw tail in either mode. Workflow discovery
returns names, descriptions, revisions and IDs by default; get_workflow(name) reads the full
graph. Prefer wait holds of 50 seconds or less on remote MCP connections. See the
waiting and polling guide.
Task ids and workflow run ids may be passed as unique prefixes of at least 8 characters; replies echo the
resolved id in resolved_from, and an ambiguous prefix lists its candidates. See
id prefixes.
harflow-ctl cancel TASK_ID --json includes a bounded final observation of recorded tasks and
pending launches (task-cancel-cascade.v1): stopped, running or unknown per target, with explicit
discovery coverage. See the cancellation observation contract.
Direct human clients can discover pre-record launch attempts after restart with
harflow-ctl task-pending-page --json and look up an exact full ID with
task-pending-status --task-id FULL_ID --json. These bounded read-only views preserve source
uncertainty; cancellation support describes a mechanism and grants no permission. See the
pending launch contract.
While bounded reads are still establishing caller authority, preparation responses expose only neutral status, source and reason, with empty content and unknown counts. This also applies to a cold index for a direct caller; retry until authority is established. See bounded read authority.
After a dispatch server restart, surviving execution is reported as a quiet observation change;
lost or uncertain owner/capture evidence remains visible. Full diagnostics retain the original
dispatcher identity. See supervision.
For stable read-only parent-process observation continuity, use harflow-ctl status TASK_ID --observer-parent --json (also supported by status-batch); see public contracts.
Builders support explicitly requested conversational turns through ctl and agent MCP steering. A prose reply waits for another caller request; a valid framed proposal remains subject to draft revision checks and explicit Apply/Save. This requires the qualified original external caller or a verified native human and a supported finite harness cap. Ordinary builder messages keep their existing behavior. See builder steering. Orchestrators also support safe-boundary conversation with exact decision revisions: prose waits, and only a framed, validated configured action can resume execution. Already issued work and active sibling results remain real. See orchestrator steering.
Qualified workers support one finite response per explicit caller message, with their actual configured permissions and real tool effects. Steering does not consume or reset normal execution attempts. Epoch-scoped replay and bounded retention require an explicit protocol upgrade; old receipts may expire with visible history gaps. See worker steering and bounded history.
Root connected workers configured headless in fixed Fresh mode also support exact prestart withdrawal and a linked same-assignment retry. A spawn race stays unknown; the operation never authorizes a late signal or poststart replacement. See prestart worker replanning.
Workflow callers can see every pending child question in status and wait replies and answer them independently by decision ID through the root run. Questions and structured clarification items remain complete, and forwarded answers return a durable child acceptance receipt. Resolved attention reasons disappear when execution resumes; unreadable workflow approval metadata is reported separately from requests needing a decision. See workflow input and recovery.
Permission features use cached, binary-bound qualification: measured versions seed the cache, and unseen versions run isolated no-paid behavior probes before use. harflow-ctl qualify <backend> explicitly reruns the probes; cached discovery reports per-feature results. Add --qualification-only to permission-preview or workflow-preview NAME to discover only the features requested by that launch without provider self-tests; qualify --feature FEATURE is repeatable. Ordinary permission previews may qualify requested features. Automatic probes currently require macOS isolation. See qualification.
Current seed measurements for these two features: allowed_commands is qualified on Claude Code 2.1.310 and 2.1.312 and Vibe 3.0.3 on macOS through ACP; caller approvals are qualified on Claude Code 2.1.302 (Bash approvals) and 2.1.310/2.1.312, and on Codex through codex app-server for codex-cli 0.163.0 on macOS only (commands, and patches with caller_write_approvals), and on Vibe 3.0.3/macOS through vibe-acp (Bash and file reads; writes/edits with caller_write_approvals); other backends refuse them. Approvals are not available to native workflow children, and a request unanswered after 1800 seconds (or at the node's attempt deadline) is rejected by Harflow, never approved. After a denial there is no approve-later path: recovery is always a new resume_task or continue_task execution guided by denial_remedy (allowed_commands covers only Bash approval_required and chained-command parts; a denied Read, Write or Edit needs a resumed run so the agent can raise a fresh request; a deny_rule cannot be lifted by grants). Workflow permission-grant retry remains unavailable. On compatible engines the Mac Monitor can answer caller-owned requests; authority follows the existing inferred, cooperative same-user model and does not authenticate a human or the app. See harness permissions.
Vibe 3.0.1 and 3.0.3 headless dispatch use its Rust CLI and the ask approval profile for read_only. This is an approval policy, not a write-tool exclusion: inherited policies or custom profiles can pre-approve writes. The retained VIBE_CLI=python selector is ignored by Vibe 3; interactive takeover inherits the user's environment.
Vibe permission results retain structured tool refusals and the scopes requested by approval callbacks. Known refusal shapes distinguish approval requirements, policy denials and denylist rules; unknown reasons remain unclassified. Vibe 3.0.3/macOS uses a qualified ACP transport for caller approvals, allowed_commands and explicit configured-model selection. Requests and responses are bound to the exact tool input; grants never replace the native allowlist or override native deny policies. Ordinary launches without these options retain the established headless transport. See Vibe permission denials.
Vibe provider HTTP 402 failures retain a safe explanation even without final agent prose. A measured usage-limit response is reported as a usage limit; an unknown payment response stays a provider error and asks you to check billing and usage. Neither automatically retries or switches providers.
publish authorizes publication attempts; its enforcement depends on the backend:
| Backend | Publish mechanism |
|---|---|
| Claude | Allows git commit, git push, gh pr create/edit/view/comment/review/checks/diff/list, and gh repo view, including their --help forms. |
| Codex | Requests network enabled in its workspace sandbox; it does not restrict individual GitHub commands. |
| opencode | Uses the same build policy as write_in_repo; inherited harness settings still decide command approval. |
| Vibe / Antigravity | Uses the same approval bypass as unrestricted; individual GitHub operations are not filtered. |
| Cursor | Uses the same print-mode command as write_in_repo and unrestricted. Plan mode is requested only for read_only. Individual GitHub operations are not filtered, and caller approvals and allowed_commands are refused. |
Claude's built-in list excludes merge, repository deletion, releases and raw gh api calls.
Its prefix matcher cannot safely distinguish read API calls from writes; use gh pr view --json
or gh repo view --json for supported reads. These are Harflow-supplied command grants,
not an OS Git sandbox; inherited settings and hooks can still allow or deny commands.
Permission previews expose the actual mechanism and caveats. See publication permissions.
Version 0.0.10 is a pre-release candidate. Harflow, the companion macOS application, is maintained separately and prepares its own exact paired engine runtime. Its managed runtime and MCP registrations work independently of the app process; see the managed runtime guide.
Task phase slots can serialize heavy commands while code-writing tasks overlap. Explicit human enable, durable FIFO leases and optional conservative host cleanup are documented in phase slots; Monitor queue UI remains outstanding. Phase operations distinguish a disabled layout with the stable error code phase_slots_not_enabled; see the phase slot contract.
Detached task owners preserve output capture and live input across MCP server restarts.
Tasks can take turns on a named, exclusive resource (a simulator, a device, a database) with resources; a waiting task is acknowledged at once and reports waiting_for_resources until it spawns. A task can also run in its own linked Git worktree with worktree, leaving your checkout untouched. Workflows can declare run and node resource scopes and share one root-run worktree across nodes and linked child runs. See resources and worktrees. Final review summaries and workflow plans receive task-identifiable files discoverable through task artifacts, including read-only runs. Public harflow-ctl task-artifacts reads use the enveloped v1 contract and require task-artifacts.v1; pages distinguish empty registrations from unavailable metadata and expose cursor/preparation error reasons. See the public artifact contract. Child workflows receive pinned parent specifications throughout their nodes. Every task also gets scratch folders shared across its resume chain and its group (HARFLOW_CHAIN_SCRATCH, HARFLOW_GROUP_SCRATCH), so outputs survive between runs; see shared scratch.
Confirmed-dead detached launches reconcile interruption evidence and resource/session claims during
maintenance or resume admission. Missing or uncertain process generations stay protected; one damaged
launch receipt reports a per-task refusal while unrelated discovery continues. Human launch-settle
uses the same death checks. See abandoned launch recovery.
Non-question workflow continuation can bind the originally displayed
attention_checkpoint_id; Monitor requires capability
workflow-attention-checkpoints.v1 and this token for resume/recovery. Stale
requests refuse the answer and grants; refresh and review before resubmitting.
Questions retain their decision-ID path. See checkpoint contracts.
Workflow scheduler recovery is explicit; see supervision and recovery.
If a decision cannot be encoded for persistence, scheduling stops with needs_attention
and an error in attention_reason. After correcting the cause, resume the run to retry the
retained decision. An interrupted active run with a confirmed-dead scheduler instead uses
recover_workflow; see workflow recovery.
Task status distinguishes the dispatching server, execution owner and responding server.
A normal attachment to a task launched by this server is not recovered; another observer or missing
identity is explained explicitly. Detail reads separately report dispatcher liveness, and routine
status polling provides a successor reference without scanning history. See supervision and recovery.
Git outcomes observe up to eight repositories, including explicit absolute observe_repos targets
and repositories discovered from structured commands and edits. Observation grants no additional
access. Outcomes retain partial evidence with per-probe failure and budget diagnostics. Commit
ranges include imported history and cannot identify task-created commits or authorship; see
observed task outcomes.
Task observations retry transient metadata replacements up to three reads and retain uncertainty
when metadata cannot be read reliably.
Recovered tasks disclose owner/process uncertainty and capture continuity. Qualified Claude
transcripts can supply bounded display-only recovery activity; see public contracts.
Live-input capability does not promise that stdin is still open: status reports input_channel
and input_closed_reason. Wait for settlement before resuming a task whose input has closed.
MCP task status exposes paged successor links; resumes and continuations retain their source IDs.
Claude permission previews and launches disclose bounded candidate inherited rules; managed policy and effective applicability remain uncertain. See harness permissions.
Claude read-only plan mode permits built-in plan files; successful observed plan writes appear
as metadata-only task artifacts. Harness session history and logs can also persist outside the
checkout. See harness permissions.
New launches and resumes require at least 256 MiB free on state, checkout and temporary-storage
filesystems. Confirmed-dead detached executions can resume their recorded conversation; live or
uncertain sessions remain protected. See supervision and recovery.
Backend discovery reports qualification gates for writable paths, caller approvals and command
grants, with network caveats returned as complete entries. At unrestricted access, validated extra writable paths are disclosed as a no-op.
Waits return for approvals that still need a decision or require reconciliation; a recorded
approval or rejection awaiting delivery does not by itself interrupt the next wait.
Live background wait bounds are persisted and configurable; see task continuation.
Use harflow-ctl version-info --json to inspect runtime identity and compatibility without initializing state. Engine operations require compatible Harflow state, task metadata, saved workflow definitions, workflow run documents and workflow ownership receipts. Known qualified storage lines migrate conservatively before new-line writes. Use harflow-ctl state-inspect --json to inspect an incompatible root without changing it, then explicitly confirm its state-recover proposal to retain a sibling backup and create fresh state. HARFLOW_STATE_ROOT can also select a separate fresh state directory; see state ownership and recovery for compatibility requirements.
Root workflow status and waits retain verified nested questions with their full source paths and usage-limit details, even when another child link is unavailable. Answers route by the current decision ID; unavailable decisions report specific retry guidance. Pending workflow questions, recovery and goal revision are answerable by both the qualified original caller and a verified human Monitor responder. The first valid answer wins, with its text, responder and time retained; answering in Harflow does not transfer ownership. Child questions still route through the root. Unknown caller identity retains conservative eligibility. The Mac app gates shared answering on the engine's advertised responders field. See the interaction contract.
- Getting started
- Workflows, including acknowledged context sections and bounded instruction inspection
- Task continuation
- Resources and worktrees
- Shared scratch folders
- Task artifacts
- Task and workflow notifications (qualified Harflow database required)
- Recent usage-limit hits (tasks and workflow runs)
- Public contracts and runtime compatibility
- Release validation and publication
- Development and technical references
History pages expose optional completion and ownership metadata for retained-history summaries. Workflow completion time records the terminal status transition independently of settlement; legacy and mixed-writer completion without a matching sequence witness remains unknown. See compact reads for ownership, pinned workflow identity and completeness requirements.
Finished retained-history statistics are available to verified direct callers through
harflow-ctl statistics-page --since=<ISO8601> --before=<ISO8601> --json.
Clients require capability statistics-page.v1; older engines remain unsupported. Results
disclose retention, missing accounting and bounded preparation rather than assuming complete
history or zero usage. Executions also report the backend-reported dollar cost and the model the harness observed
(capability statistics-cost-model.v1; unknown stays null, never zero). See statistics contracts.
Verified direct callers can read one task's history through ctl: harflow-ctl task-events TASK_ID --json
pages its normalized events in both directions with opaque cursors, a lifecycle log.state and
gap reporting (capability task-event-page.v1), and harflow-ctl task-prompt TASK_ID --json returns its
stored prompt with an integrity state (capability task-prompt.v1). Clients require the capability
on the version-info handshake before using either command. See task event pages and prompts.
harflow-ctl task-list-page --predecessor-task-id TASK_ID --json lists a task's recorded resumes and
continuations (capability task-successors.v1; see successor discovery).
A verified direct caller can also read the activity of a running workflow node with harflow-ctl workflow-inspect --view activity
(capability workflow-live-activity.v1; see live node activity).
harflow-ctl task-changes TASK_ID --json returns the repository differences captured when a task settled (committed range and working tree, bounded rows and patch text; capability task-changes.v1; see stored task changes). The text can contain secrets or uncommitted edits, so only verified direct callers can read it.
harflow-ctl continue TASK_ID [--extra-prompt TEXT | --extra-prompt-file PATH] --json starts a fresh session from a settled standalone task and consumes its queued follow-ups (capability task-continue.v1; see continue).
Ctl full/brief status and batch rows expose advisory chain-stop observations with
task-continuation-stop.v1 in the fresh version-info handshake. stopped,
not_stopped and unknown describe the marker observation, never launch eligibility;
successor reconciliation still uses task-successors.v1. See the
continuation-stop contract.
harflow-ctl task-list-watch [--cursor C] [--wait-seconds N] --json is one bounded task-list invalidation wait (capability task-list-watch.v1; see task-list invalidation wait). It returns baseline/changed/timeout/reset/unavailable signals, not task facts; public paging and status remain authoritative. Direct callers only; it never initializes a missing state root. Watch continuity requires corrected producer writers (0.0.10); concurrent older writers are unqualified and may not invalidate the watcher. Consumers must retain public deadline reconciliation.
For narrowly authorized branch preparation on qualified Claude Code, exact allowed_commands
grants for fetch, fast-forward-only pull and non-force branch switching/creation work at
write_in_repo as well as publish. Initial transitions refuse dirty checkouts without stashing
or resetting; commit/push authority remains separate. An exact git commit --no-edit or
git merge --continue grant is the one carve-out: it is usable only while a merge is in progress.
enforcement.local_commit says whether a direct local commit is denied, allowed, or not enforced.
Harflow can also fetch, and can create one branch from a fetched base, before the agent starts.
See the
[grant grammar and per-run workflow migration](docs/harness-permissions.md#dispatch-time-
Harflow MCP 질문
Harflow MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add harflowmcp -- uvx harflow-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Harflow MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Harflow에서 Cursor Agent CLI를 어떻게 사용하나요?
헤드리스 Cursor 할당을 위해서는 'agent login' 또는 CURSOR_API_KEY가 필요합니다. 'agent status'를 실행하여 액세스 토큰이 보고되는지 확인하여 상태를 점검할 수 있습니다.
에이전트가 실행할 수 있는 명령어를 제한할 수 있나요?
네, 특정 백엔드를 사용하는 macOS에서는 무제한 권한을 부여하는 대신 allowed_commands를 사용하여 작업에 특정 Bash 명령어 목록만 허용할 수 있습니다.
MCP server가 재시작되면 작업은 어떻게 되나요?
분리된 작업 소유자(Detached task owners)는 MCP server 재시작 시에도 출력 캡처와 실시간 입력을 유지하며, 실행이 지속되면 조용한 관찰 변경 사항으로 보고됩니다.
실행 중인 작업을 취소하려면 어떻게 하나요?
harflow-ctl cancel TASK_ID --json 명령어를 사용하여 작업을 취소할 수 있으며, 이를 통해 기록된 작업 및 대기 중인 실행에 대한 제한된 최종 관찰 결과를 확인할 수 있습니다.