에이전트 주도 Repo Mesh 셋업

이 페이지는 이미 ADHDev가 설치된 머신들 위에 Repo Mesh를 세팅하라는 지시를 받은 AI 코딩 에이전트(Claude Code, Codex, Hermes 등)를 위해 작성되었습니다. 아래 단계를 순서대로 따르고 각 단계를 그대로 실행하세요 — 일부는 셸 명령이고 일부는 MCP 툴 호출입니다(바로 아래 박스 참고).

사람이 읽는다면: 이 페이지를 에이전트에 건네며 "메시 셋업 가이드대로 Repo Mesh를 세팅해줘" 라고 하세요. 에이전트가 탐색하고, 설정을 제안하고, 무언가를 쓰는 단계마다 멈춰 승인을 요청합니다. 당신은 승인만 하면 됩니다.

이 문서는 자동화된 지름길입니다. 개념은 Repo Mesh, 수동 경로 실습은 튜토리얼: 첫 실전 작업을 보세요.

전체 흐름: 머신들이 이미 세팅됨 → 메시 생성 → mesh_init이 설정 제안 → 승인 → 코디네이터 시작.

MCP 툴 vs. CLI 명령 — 서로 바꿔 쓸 수 없습니다

이 페이지의 모든 mesh_* 이름(mesh_plan_onboarding, mesh_create, mesh_add_node, mesh_init, mesh_status 등)은 MCP 툴입니다 — 셸이 아니라 에이전트의 툴 인터페이스를 통해 호출하세요. adhdev mesh init이나 adhdev mesh_status 같은 명령은 존재하지 않습니다. mesh_* 이름을 셸에서 실행하면 "unknown command"로 실패합니다.

이 단계들 중 일부는 CLI 등가물(adhdev mesh plan, adhdev mesh create, adhdev mesh add-node)도 있어 MCP 클라이언트 없이 동일한 작업을 할 수 있습니다 — 이런 것들은 전체적으로 ```bash 블록으로 표시됩니다. bash 라벨 없는 일반 코드 블록에 있는 것은 모두 MCP 툴 호출이지 셸 명령이 아닙니다. CLI 등가물은 2단계에서 끝납니다 — mesh_init(3단계)과 그 이후(슬롯, MAGI, 코디네이터 툴셋)는 CLI 형태가 없고 MCP 전용입니다.

전제 조건

메시 노드를 올릴 모든 머신에 ADHDev가 동작하고 있어야 합니다. 아직 세팅되지 않은 머신이 있다면 먼저 그 머신에서 에이전트 주도 새 머신 셋업을 진행한 뒤 돌아오세요.

단일 머신 vs 멀티 머신

	단일 머신 메시	멀티 머신 메시
동작 환경	스탠드얼론 및 클라우드	클라우드 전용
노드	한 머신에 있는 같은 저장소의 Git 워크트리들	여러 머신에 걸친 워크스페이스들
계정 필요	아니오(스탠드얼론)	예 — 모든 데몬이 동일 계정

단일 머신 메시는 셀프호스트 스탠드얼론 빌드에서도 온전히 동작합니다. 워크트리 노드, 태스크 큐, Refinery, MAGI, MCP 메시 모드가 전부 로컬에서 돌아갑니다. 스탠드얼론이 못 하는 건 머신 간 릴레이 — 동일 계정 데몬 여러 개를 코디네이션하는 것이 클라우드 기능입니다.

에이전트 판단 기준: 사용자가 한 대에서 워크트리 병렬성을 원한다면 스탠드얼론으로 충분합니다. 두 대 이상을 언급하면 각 머신에 클라우드 로그인이 필요합니다(멀티 머신 참고).

0단계 — 전제 확인

0a. 이 머신에서 데몬이 떠 있는가?

bash

adhdev status

기대 결과: 데몬이 정상 — 스탠드얼론은 localhost:3847, 클라우드 모드는 api.adhf.dev에 대해 머신이 online.

아니라면: 멈추고 에이전트 주도 새 머신 셋업을 먼저 진행하세요. 죽은 데몬 위에서 계속 진행하지 마세요 — 이후 모든 단계가 데몬을 필요로 합니다.

0b. 워크스페이스가 원격이 있는 Git 저장소인가?

Repo Mesh는 Git 원격에서 나오는 repo identity로 메시를 식별합니다. 추가할 워크스페이스에서 실행하세요:

bash

git rev-parse --show-toplevel
git remote -v

기대 결과: 저장소 루트 경로와 최소 하나의 원격. 원격이 없으면 2단계 탐색이 remote_not_found로 실패합니다. 메시 생성 시 --identity로 직접 지정할 수도 있지만, 실제 원격이 정상 경로입니다.

0c. mesh 툴을 가지고 있는가?

가장 자주 건너뛰는 단계이고, 이게 안 되면 이후 아무것도 동작하지 않습니다. mesh_* 툴은 메시 모드로 실행되는 ADHDev MCP 서버에서 나옵니다. 도달하는 방법은 두 가지이며 순서가 있습니다:

먼저 표준 모드 — 일반 MCP 등록으로 부트스트랩 툴 3개(mesh_plan_onboarding, mesh_create, mesh_add_node)를 얻습니다. 메시를 만들기엔 이걸로 충분합니다.
그다음 메시 모드 — 메시가 생긴 뒤 --repo-mesh <mesh_id>로 재등록하면 전체 코디네이터 툴셋이 열립니다.

메시 모드는 메시가 아직 없으면 시작을 거부하므로 바로 건너뛸 수 없습니다.

기존 .mcp.json을 믿기 전에 유령 메시부터 확인하세요

이 워크스페이스에 이미 --repo-mesh <mesh_id>가 들어간 .mcp.json이 있다면, 그 메시가 실재한다고 가정하지 마세요 — 이전 세션의 잔여물이고 그 메시가 이후 삭제됐을 수 있습니다. 먼저 확인하세요:

bash

adhdev mesh list

.mcp.json의 mesh_id가 이 목록에 없다면 기존 등록을 유령 설정으로 취급하세요: 메시 모드 시작에 실패하거나(또는 조용히 아무것도 안 가리키게 됩니다). 재사용을 시도하지 말고 아래 2단계에서 얻는 mesh_id로 삭제·교체하세요.

MCP 클라이언트 설정에 표준 모드를 등록하세요. 서버 이름은 자유이며 adhdev가 관례입니다:

json

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

Codex는 JSON 편집 대신 CLI 호출로 등록합니다:

bash

codex mcp add adhdev -- adhdev mcp

MCP 서버는 살아있는 데몬을 필요로 합니다

adhdev mcp는 툴을 등록하기 전에 데몬을 핑하고, 도달 못 하면 종료 코드 1로 죽습니다. local 모드는 3847 포트의 스탠드얼론 데몬(adhdev standalone), ipc 모드는 클라우드 데몬(adhdev daemon)을 봅니다. MCP 서버가 시작하자마자 죽으면 거의 항상 데몬이 안 떠 있는 것입니다 — 0a를 다시 확인하세요.

필요할 때 쓰는 플래그:

플래그	의미
`--mode <local\|ipc>`	전송 방식. `local` = 스탠드얼론 데몬, `ipc` = 클라우드 데몬
`--port <n>`	데몬 포트. 기본값: local `3847`, ipc `19222`
`--password <pass>`	스탠드얼론 데몬 패스워드(설정한 경우)
`--repo-mesh <mesh_id>`	메시 모드로 전환(2c 단계)

대응 환경변수: ADHDEV_PASSWORD, ADHDEV_MESH_ID, ADHDEV_MCP_TRANSPORT.

설정 변경 후 클라이언트 재시작

MCP 서버는 클라이언트 시작 시점에 읽힙니다. 등록을 바꿨다면 새 세션을 시작하세요 — 이미 떠 있는 세션은 새 툴을 인식하지 못합니다.

1단계 — 머신 인벤토리

멀티 머신 메시를 원한다면, 도달 못 할 노드를 추가하지 않도록 메시를 만들기 전에 모든 머신이 온라인인지 확인하세요.

bash

adhdev status

각 머신에서 실행하거나 클라우드 대시보드의 머신 목록을 확인하세요. 모든 호스트가 동일 계정으로 online이어야 합니다.

빠진 머신이 있다면: 에이전트 주도 새 머신 셋업으로 보내세요. 그 머신의 클라우드 로그인은 사람이 해야 하는 단계이며 에이전트가 대신할 수 없습니다.

머신이 한 대뿐이라면: 괜찮습니다, 계속 진행하세요. 2b에서 원격 노드 대신 워크트리 노드를 만들게 됩니다.

2단계 — 메시 구성

2a. 먼저 계획(읽기 전용, 아무것도 쓰지 않음)

항상 dry-run으로 시작하세요. mesh_plan_onboarding은 파일시스템 읽기와 로컬 Git 조회만 수행합니다 — fetch도, 설정 쓰기도, 브랜치·워크트리 생성도 없습니다.

MCP 툴 호출(에이전트의 툴 인터페이스로, 셸이 아님):

mesh_plan_onboarding(workspace: "<저장소 절대 경로>")

CLI 등가물 — 같은 계획을 출력합니다:

bash

adhdev mesh plan
adhdev mesh plan --json    # 전체 기계 판독용 계획

기대 결과: kind가 create_mesh_and_onboard, add_existing_workspace, clone_new_worktree 중 하나인 계획과 discovery 블록(repo identity, 브랜치, clean/dirty), 그리고 각각 read-only 또는 approval-required로 표시된 단계 목록. CLI는 "Nothing was written." 로 끝납니다.

행동하기 전에 계획을 읽으세요. 다음에 어떤 툴을 호출할지 알려주고, 막힐 요소를 중간이 아니라 앞에서 드러냅니다.

자주 나오는 실패 코드:

코드	의미
`not_git_repository`	디렉토리가 틀림 — `workspace`를 저장소 루트로
`remote_not_found`	Git 원격 없음, 0b 참고
`dirty_workspace`	커밋 안 된 변경 — 커밋/스태시 후 재계획
`nested_worktree`	워크트리의 워크트리 안 — 메인 체크아웃 사용
`compatible_mesh_exists`	이 저장소의 메시가 이미 있음 — 생성 대신 노드 추가
`detached_head`	먼저 브랜치를 체크아웃

2b. 메시 생성과 노드 추가

계획이 알려준 대로 진행하세요.

새 메시 생성(계획 kind create_mesh_and_onboard) — MCP 툴 호출:

mesh_create(name: "<메시 이름>", add_current: true)

add_current: true는 현재 워크스페이스를 같은 호출에서 메시의 첫 노드로 등록합니다. 응답에 이후 계속 필요한 mesh_id가 들어 있습니다.

mesh_create(add_current: true)는 providerPriority를 설정하지 않습니다

mesh_add_node와 달리 mesh_create에는 provider_priority 파라미터가 없습니다. 이 호출로 등록되는 첫 노드는 직접 설정하기 전까지 policy.providerPriority가 비어 있습니다 — 이 단계 끝의 콜아웃을 참고하세요.

CLI 등가:

bash

adhdev mesh create my-project --add-current

기존 워크스페이스를 노드로 추가(계획 kind add_existing_workspace) — 두 번째 머신이나 두 번째 체크아웃에 사용. MCP 툴 호출:

mesh_add_node(workspace: "<절대 경로>", mesh_id: "<mesh_id>")

선택: 쓰기 작업을 절대 주면 안 되는 노드는 read_only: true, 실행 에이전트를 고정하려면 provider_priority: ["claude-cli", "codex-cli"] — 이게 왜 중요한지는 아래 providerPriority 콜아웃 참고.

CLI 등가:

bash

adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli

워크트리 노드 생성(계획 kind clone_new_worktree) — 단일 머신에서 병렬성을 얻는 방법입니다. 실제로 git worktree add를 수행합니다. MCP 툴 호출(CLI 등가 없음):

mesh_clone_node(source_node_id: "<node_id>", branch: "<새 브랜치 이름>")

선택 base_branch — 기본값은 현재 HEAD.

다음으로 넘어가기 전에 providerPriority를 확인하세요

mesh_launch_session은 type을 명시하지 않고 호출했는데 노드의 policy.providerPriority가 비어 있으면 fail-closed(missing_provider_priority)됩니다 — mesh_create(add_current: true)도 mesh_clone_node도 이걸 설정하지 않습니다. 방금 만든 노드를 전부 확인하세요:

mesh_status()

노드의 providerPriority가 없다면 mesh_add_node로 등록할 때 provider_priority를 주거나, 그 노드에 대해서는 항상 mesh_launch_session을 명시적 type으로 호출하거나, 대시보드의 Repo Mesh 정책 편집기 / 커밋된 .adhdev/mesh.json으로 정책을 설정하세요. mesh_init(3단계)이 감지된 CLI 프로바이더로부터 providerPriority 목록을 추천하지만, 이는 참고용일 뿐 — 노드 정책에 대신 써주지 않습니다.

구성 결과 확인:

bash

adhdev mesh show mesh_abc123
adhdev mesh status mesh_abc123

show는 노드 목록, status는 각 노드 헬스 프로브입니다.

2c. MCP 서버를 메시 모드로 재등록

메시가 생겼으니 클라이언트를 메시 모드로 전환해 전체 코디네이터 툴셋을 엽니다. 플레이스홀더를 실제 mesh_id로 바꿔 MCP 설정을 수정하세요:

⏸ 에이전트 런타임이 이 편집을 막을 수 있습니다 — 우회하지 마세요

.mcp.json 편집은 이후 세션이 받을 툴셋을 바꾸므로, 일부 에이전트 런타임은 이를 일반 파일 편집과 별도의 승인 게이트로 막습니다. 에이전트인데 이 편집이 막혔다면: 게이트를 우회하려 하지 마세요. 멈추고, 사람에게 .mcp.json(또는 Hermes의 YAML 블록)에 대한 정확한 한 줄 diff와 실행할 명령을 제시해 사람이 직접 적용하게 하세요. 재시도하거나, 에스컬레이션하거나, 같은 내용을 다른 방법으로 쓰려 하는 것은 안전장치의 취지를 무력화합니다.

json

{
  "mcpServers": {
    "adhdev-mesh": {
      "command": "adhdev",
      "args": ["mcp", "--mode", "ipc", "--repo-mesh", "mesh_abc123"]
    }
  }
}

Hermes는 mcp_servers 아래 YAML로 같은 내용을 씁니다. 파일 위치는 hermes config path로 찾습니다:

yaml

mcp_servers:
  adhdev-mesh:
    command: adhdev
    args:
      - mcp
      - --mode
      - ipc
      - --repo-mesh
      - mesh_abc123
    enabled: true

Codex:

bash

codex mcp add adhdev-mesh -- adhdev mcp --mode ipc --repo-mesh mesh_abc123

그리고 에이전트 세션을 재시작하세요. 메시 모드에서는 툴 표면이 완전히 교체됩니다 — 표준 세션 툴이 사라지고 메시 코디네이터 툴이 나타납니다.

스탠드얼론 사용자

--mode ipc 대신 --mode local을 쓰세요. ipc는 클라우드 데몬, local은 3847 포트의 스탠드얼론 데몬과 통신합니다.

3단계 — `mesh_init`이 저장소 설정을 제안하게 하기

이것이 init 단계입니다 — 저장소를 읽고 합리적인 기본값을 써줘서 설정 파일을 손으로 작성하지 않아도 되게 합니다.

mesh_init은 MCP 툴이지 CLI 명령이 아닙니다 — adhdev mesh init 같은 건 없습니다. 에이전트의 툴 인터페이스로 호출하세요. 2단계 툴입니다: 기본은 미리보기이고, 명시적으로 지시할 때만 씁니다.

3a. 미리보기(기본 — 아무것도 쓰지 않음)

MCP 툴 호출(CLI 등가 없음):

mesh_init()

이게 전부입니다. write의 기본값이 false이므로 이 실행은 dry-run입니다. 응답은 dryRun: true로 돌아오고 제안된 각 설정은 written: false를 답니다.

저장소 수준 설정 파일 3개를 제안합니다:

파일	설정 내용
`.adhdev/refine.json`	Refinery 검증 — 브랜치가 수렴하기 전 통과해야 하는 명령들
`.adhdev/worktree_bootstrap.json`	새로 만든 워크트리에서 실행할 것(의존성 설치)
`.adhdev/change-impact.json`	변경 영향 분석 설정

providerPriority 추천도 반환하지만 이건 참고용일 뿐 — mesh_init이 대신 적용하지 않습니다.

검증 명령이 선택되는 방식. mesh_init은 package.json 스크립트를 읽어 typecheck, test, lint, build 네 카테고리와 매칭합니다. 이름이 카테고리와 정확히 같거나 <카테고리>:로 시작하는 스크립트가 npm run <script> 형태로 제안됩니다. 제안은 메시 수준 프로젝트 명령과 병합·중복 제거되고 최대 4개로 제한됩니다.

npm이 아닌 저장소는 제안이 나오지 않습니다

탐지는 정확히 typecheck / test / lint / build 이름이거나 typecheck: / test: 등으로 시작하는 npm 스크립트만 매칭합니다. cargo test, go test, poetry run pytest, 맨 tsc --noEmit, 또는 다른 이름의 스크립트(check, vitest)를 쓰는 저장소는 제안이 0개이고 skippedReason: "no_suggestion"이 나옵니다. 실패가 아니라 정상입니다 — 그런 저장소는 .adhdev/refine.json을 직접 작성하세요.

3b. 사람과 함께 검토 ⏸ 사람 개입 단계

⏸ 사람 개입 단계 — 쓰기 전에 제안을 보여주세요

제안된 refine, worktreeBootstrap, changeImpact 블록을 사용자에게 보여주고 명시적 승인을 받으세요. 이 파일들은 저장소 안에 들어가고 이후 작업 수렴 여부를 결정하는 게이트가 됩니다 — 여기 테스트 명령이 틀리면 이후 모든 머지가 조용히 막힙니다.

특히 refine 검증 명령을 콕 집어 물어보세요: 이 저장소에서 실제로 통과해야 하는 명령이 이게 맞는지. 사람이 항상 직접 눈으로 봐야 하는 필드는 이것입니다.

3c. 쓰기(승인 후에만)

MCP 툴 호출:

mesh_init(write: true)

mesh_init은 기존 설정을 절대 덮어쓰지 않습니다. 파일이 이미 있으면 skippedReason: "already_exists"로 돌아오고 그대로 둡니다. 의도적으로 교체하려면:

mesh_init(write: true, overwrite: true)

mesh_reinit도 있습니다. 같은 동작이지만 overwrite가 기본 true입니다 — 갱신이 의도라면 이쪽을 써서 의도를 호출에 드러내세요.

확인: 응답이 dryRun: false와 파일별 written: true를 보고합니다. 디스크에서도 확인:

bash

ls .adhdev/

이 파일들을 커밋하세요. 저장소 설정이며, 모든 노드와 이후 모든 코디네이터가 같은 규칙을 읽게 하는 것이 목적입니다.

4단계 — 모델, 상한, MAGI

이 단계의 모든 항목에는 동작하는 기본값이 있습니다. 사용자가 실제로 신경 쓰는 것만 바꾸고, 답이 결과를 바꿀 때만 물어보세요.

4a. 노드 슬롯 — 어디서 어떤 에이전트·모델이 도는가

슬롯은 프로바이더(그리고 선택적으로 모델과 thinking level)를 난이도 클래스에 묶습니다. 현재 상태 확인:

mesh_node_slots_list(node_id: "<node_id>")

노드에 명시적 슬롯이 없으면 프로바이더 우선순위와 메시별 난이도 프리셋에서 유도되며, 기본값은 다음과 같습니다:

난이도	모델	Thinking level
`easy`	`haiku`	`low`
`medium`	`sonnet`	`medium`
`difficult`	`opus`	`high`

freeform은 네 번째 유효 난이도이며 의도적으로 프리셋이 없습니다.

사용자가 요청하지 않으면 건드리지 마세요. 유도된 기본값이 대부분의 메시에 맞습니다. 사용자가 비용을 통제하고 싶거나(싼 작업을 작은 모델에 고정) 특정 머신에만 있는 프로바이더가 있을 때만 명시적으로 설정하세요.

mesh_init과 마찬가지로 이 툴도 기본이 dry-run입니다:

mesh_node_slots_set(node_id: "<node_id>", slots: [...])            # 미리보기
mesh_node_slots_set(node_id: "<node_id>", slots: [...], write: true)  # 적용

슬롯은 통째로 교체됩니다

slots는 기존 값에 병합되지 않고 노드의 슬롯 목록 전체를 교체합니다. 항상 mesh_node_slots_list를 먼저 실행해 현재 값에서 새 배열을 만드세요. 안 그러면 설정을 조용히 잃습니다. 쓰기 전에 dry-run으로 currentSlots와 proposedSlots를 비교하세요.

슬롯별로 provider는 필수이고, model, thinkingLevel, difficulty(배열), capability(배열), maxParallel은 선택입니다. difficulty가 비어 있으면 모든 난이도를 처리합니다.

4b. 정책 상한 — 기본값을 쓰세요

메시 정책은 체크포인트, 푸시 승인, 재시도, 동시성을 관장합니다. 동시성은 의도적으로 관대하고 안전은 보수적으로 잡혀 있으니 셋업 중에 건드리지 마세요. 특히:

maxParallelTasks는 기본적으로 사실상 무제한이며, 대시보드가 의도적으로 이 컨트롤을 숨깁니다.
requireApprovalForPush 기본 true — 푸시는 먼저 물어봅니다.
requirePostTaskCheckpoint 기본 true — 태스크마다 이후 체크포인트를 찍습니다.
delegatedWorkerAutoApprove 기본 true — 워커 세션이 자체 툴 프롬프트에서 멈추지 않습니다.

사용자에게 물어볼 것은 하나뿐입니다: 푸시 승인을 계속 켜둘 것인지. 나머지는 기본값으로 두고 넘어가세요. 정책은 대시보드의 Repo Mesh 정책 편집기나 커밋된 .adhdev/mesh.json으로 설정하며, 메시 셋업 툴로 설정하지 않습니다.

4c. MAGI — 선택 사항이지만, 에이전트를 두 종류 이상 쓴다면 켤 가치가 있음

MAGI는 같은 질문을 여러 에이전트에 동시에 던지고 답을 비교합니다. 교차검증 기능이며, 이걸 작동하게 하는 축은 에이전트/벤더 다양성입니다 — 서로 다른 모델은 서로 다르게 실패하므로, 두 벤더가 엇갈리는 지점이 바로 얻고자 하는 신호입니다.

이건 머신을 몇 대 가졌느냐가 아니라 어떤 CLI가 깔려 있느냐의 문제입니다. 서로 다른 에이전트가 2개 이상 — 예를 들어 claude-cli와 codex-cli — 있다면 단일 머신에서도 MAGI 패널이 온전히 성립합니다. 요즘은 대부분 여러 CLI를 이미 깔아 두므로, 건너뛰기보다 권해볼 만합니다. 패널을 여러 머신에 분산하면 독립성이 더해지지만, 그건 보너스이지 전제 조건이 아닙니다.

사용자에게 원하는지 물어보세요. 에이전트 벤더를 둘 이상 쓴다면 권하고, CLI가 하나뿐이면 이유를 말하고 건너뛰세요.

동작상 MAGI는 최소 2개의 독립적인 (노드, 프로바이더) 타겟을 요구하며 단일 에이전트로 조용히 격하되지 않습니다. 타겟은 노드와 프로바이더를 함께 묶어 식별하므로, 한 노드에 있는 서로 다른 프로바이더 2개는 서로 다른 타겟 2개로 요건을 충족합니다. 여기에 더해 서로 다른 프로바이더가 2개 미만이거나 서로 다른 노드가 2개 미만이면 참고 경고가 붙는데, 이는 패널이 얼마나 상관돼 있는지에 대한 힌트이지 실패가 아닙니다. 실제로 중요한 구성은 서로 다른 벤더 2개입니다. 한 프로바이더를 두 번 복제한 패널이 약한 경우이며, 머신에 걸쳐 있든 아니든 마찬가지입니다.

원한다면 태스크 종류에 패널을 바인딩하세요. 유효한 종류는 claim_audit, rca, design, freeform입니다:

mesh_magi_kind_panel_list()                                        # 현재 설정 확인
mesh_magi_kind_panel_set(task_kind: "rca", slots: [...])           # 미리보기
mesh_magi_kind_panel_set(task_kind: "rca", slots: [...], write: true)

노드 슬롯과 규칙이 같습니다: 기본 dry-run, 그리고 슬롯 목록이 패널을 통째로 교체합니다. 슬롯마다 provider가 필요하고 nodeId, model, capabilityTags, n(리플리카 수, 기본 1)은 선택입니다. nodeId는 이 메시의 노드여야 하며 아니면 호출이 거부됩니다.

패널은 메시별로 저장되며 머신 로컬입니다 — 저장소가 아니라 ~/.adhdev/meshes.json에 있습니다.

5단계 — 코디네이터 시작

코디네이터는 메시 툴을 쥐고 노드들에 작업을 넘기는 세션입니다.

코디네이터는 스스로를 띄울 수 없습니다

mesh_launch_coordinator 툴도, 코디네이터를 시작하는 adhdev mesh 서브커맨드도 없습니다. 이걸 읽는 게 에이전트라면 툴 호출로 이 단계를 완료할 수 없습니다 — 사람에게 넘기거나 아래 경로 B를 쓰세요.

경로 A — 대시보드(일반적인 방법) ⏸ 사람 개입 단계

⏸ 사람 개입 단계 — 사람이 클릭합니다

대시보드에서 Repo Mesh 페이지(/mesh)를 엽니다.
메시에 호스트가 아직 고정되지 않았다면 호스트 데몬을 지정합니다 — 실행과는 별개의 의도적 동작입니다.
드롭다운에서 CLI 프로바이더를 고릅니다.
Launch Host를 클릭합니다.

데몬이 해당 프로바이더에 메시 MCP 서버를 자동 등록하고 코디네이터 세션을 대시보드 탭으로 엽니다. 고른 프로바이더가 수동 MCP 설정을 필요로 하면 UI가 붙여넣을 설정 블록을 보여줍니다 — 적용한 뒤 새 CLI 세션을 시작하세요.

실패는 명시적 코드로 드러납니다: mesh_coordinator_node_not_found(워크스페이스 해석 실패), mesh_coordinator_provider_priority_unusable(그 노드에 쓸 수 있는 에이전트 없음), mesh_coordinator_mcp_registration_failed(등록 실패로 세션을 띄우지 않음 — 의도된 fail-closed).

경로 B — MCP 메시 모드(대시보드 없이)

2c를 이미 했다면 사실상 코디네이터입니다 — 세션이 메시 모드 툴 표면을 쥐고 있습니다. 확인:

mesh_status()

기대 결과: 노드 목록이 담긴 집계 스냅샷. 툴이 없다면 메시 모드 등록이 적용되지 않은 것입니다 — 2c를 다시 확인하고 세션을 재시작하세요.

6단계 — 스모크 테스트

실제 작업을 맡기기 전에 루프가 도는지 증명하세요. 작고 안전한 태스크 하나를 큐에 넣습니다:

mesh_enqueue_task(...)

유휴 노드가 큐 작업을 가져가는 것이 의도된 경로입니다. mesh_send_task는 특정 세션에 직접 보내 큐를 우회하므로, 그럴 의도가 있을 때만 쓰세요.

진행 관찰:

mesh_view_queue()
mesh_status()

기대 결과: 태스크가 queued → claimed → completed로 이동하고, mesh_git_status가 실행한 노드에서 변경을 보여줍니다.

완료는 증거 기반입니다 — 에이전트의 자기 보고가 아니라 git status, 체크포인트, 원장 이벤트입니다. 태스크가 성공을 보고하면 믿기 전에 부수효과를 확인하세요.

더 실질적인 첫 작업은 튜토리얼: 첫 실전 작업을 따르세요.

사람이 실제로 한 것

이 페이지를 에이전트에 붙여넣음.
각 머신에서 로그인 — 머신당 한 번, 브라우저 승인(클라우드만).
mesh_init 설정 제안을 승인.
대시보드에서 Launch Host 클릭. 4′. 조건부: 2c 단계에서 에이전트 런타임이 .mcp.json 편집을 막았다면, 에이전트가 건넨 한 줄 diff를 직접 적용.
나머지 — Git 탐색, 메시 생성, 워크트리 노드, 설정 탐지, 슬롯 기본값 — 는 전부 에이전트가 했습니다.

문제 해결

세션에 mesh_* 툴이 없음 — MCP 서버가 메시 모드가 아니거나, 세션이 설정 변경보다 먼저 시작됐습니다. 2c를 다시 확인하고 새 세션을 시작하세요. MCP 설정은 클라이언트 시작 시점에 읽힙니다.
MCP 서버가 즉시 종료됨 — 툴 등록 전에 데몬을 핑하고 도달 못 하면 1로 종료합니다. adhdev status를 실행하세요. local 모드는 adhdev standalone, ipc 모드는 adhdev daemon이 필요합니다.
메시 모드가 시작을 거부함 — 메시 모드는 기존 메시를 요구합니다. adhdev mesh list로 ID를 확인하고, 없으면 표준 모드로 먼저 만드세요.
.mcp.json에 이미 --repo-mesh <id>가 있는데 메시 모드가 안 뜨거나 adhdev mesh list에 안 보임 — 삭제된 메시의 유령 설정입니다(0c 단계 콜아웃 참고). adhdev mesh list로 확인하고 2단계에서 얻은 실제 ID로 교체하세요.
adhdev mesh init이 unknown command라고 함 — mesh_init은 MCP 툴이지 CLI 서브커맨드가 아닙니다. 메시 모드로 등록한 뒤(2c 단계) 에이전트의 툴 인터페이스로 호출하세요. 셸에서 실행하지 마세요.
에이전트 런타임이 .mcp.json 편집을 막음 — 일부 런타임에서 정상입니다(2c 단계). 에이전트는 우회를 시도하는 대신 정확한 diff를 사람에게 건네야 합니다.
mesh_launch_session이 missing_provider_priority / "no providerPriority policy"로 실패 — 노드에 policy.providerPriority가 없고 명시적 type도 안 줬습니다. mesh_launch_session을 type을 지정해 호출하거나, 노드에 provider_priority를 설정하세요(mesh_add_node로 재등록하거나 메시 정책 편집). mesh_init의 providerPriority 제안은 참고용일 뿐이며 자동으로 적용되지 않습니다.
계획에서 dirty_workspace — 커밋하거나 스태시한 뒤 재계획하세요. 온보딩은 커밋 안 된 작업 위에 노드를 만드는 것을 의도적으로 거부합니다.
compatible_mesh_exists — 이 저장소의 메시가 이미 있습니다. mesh_create 대신 mesh_add_node를 쓰세요.
mesh_init이 아무것도 안 씀 — 파일이 이미 있거나(skippedReason: "already_exists" — 교체할 의도면 overwrite: true), 탐지된 게 없습니다(skippedReason: "no_suggestion" — npm이 아닌 저장소, 직접 작성하세요).
adhdev mesh status에서 노드가 probe-failed — 그 머신의 데몬이 오프라인이거나, 스탠드얼론에서 멀티 머신 메시를 시도한 것입니다. 머신 간 코디네이션은 클라우드가 필요합니다.
MAGI가 magi_kind_not_configured 오류 — 해당 태스크 종류에 mesh_magi_kind_panel_set으로 패널을 먼저 바인딩하세요. 자동 폴백 패널은 없습니다.
MAGI가 magi_insufficient_targets 오류 — 독립적인 (노드, 프로바이더) 타겟이 2개 미만입니다. 보통은 두 번째 에이전트 CLI를 설치하거나 활성화하면 해결되며, 두 번째 머신은 필요 없습니다. 타겟 하나로는 MAGI가 실행되지 않습니다.

다음으로

Repo Mesh — 개념: 노드, 미션, 큐, 원장, Refinery
튜토리얼: 첫 실전 작업 — 전체 수동 실습
MCP 서버 — 전체 툴 레퍼런스와 모든 등록 방식
멀티 머신 — 노트북 + 데스크톱 + 회사 머신 연결(클라우드 전용)
에이전트 주도 새 머신 셋업 — 새 머신을 합류 준비 상태로

에이전트 주도 Repo Mesh 셋업 ​

전제 조건 ​

단일 머신 vs 멀티 머신 ​

0단계 — 전제 확인 ​

0a. 이 머신에서 데몬이 떠 있는가? ​

0b. 워크스페이스가 원격이 있는 Git 저장소인가? ​

0c. mesh 툴을 가지고 있는가? ​

1단계 — 머신 인벤토리 ​

2단계 — 메시 구성 ​

2a. 먼저 계획(읽기 전용, 아무것도 쓰지 않음) ​

2b. 메시 생성과 노드 추가 ​

2c. MCP 서버를 메시 모드로 재등록 ​

3단계 — mesh_init이 저장소 설정을 제안하게 하기 ​

3a. 미리보기(기본 — 아무것도 쓰지 않음) ​

3b. 사람과 함께 검토 ⏸ 사람 개입 단계 ​

3c. 쓰기(승인 후에만) ​

4단계 — 모델, 상한, MAGI ​

4a. 노드 슬롯 — 어디서 어떤 에이전트·모델이 도는가 ​

4b. 정책 상한 — 기본값을 쓰세요 ​

4c. MAGI — 선택 사항이지만, 에이전트를 두 종류 이상 쓴다면 켤 가치가 있음 ​

5단계 — 코디네이터 시작 ​

경로 A — 대시보드(일반적인 방법) ⏸ 사람 개입 단계 ​

경로 B — MCP 메시 모드(대시보드 없이) ​

6단계 — 스모크 테스트 ​

사람이 실제로 한 것 ​

문제 해결 ​

다음으로 ​

에이전트 주도 Repo Mesh 셋업

전제 조건

단일 머신 vs 멀티 머신

0단계 — 전제 확인

0a. 이 머신에서 데몬이 떠 있는가?

0b. 워크스페이스가 원격이 있는 Git 저장소인가?

0c. mesh 툴을 가지고 있는가?

1단계 — 머신 인벤토리

2단계 — 메시 구성

2a. 먼저 계획(읽기 전용, 아무것도 쓰지 않음)

2b. 메시 생성과 노드 추가

2c. MCP 서버를 메시 모드로 재등록

3단계 — `mesh_init`이 저장소 설정을 제안하게 하기

3a. 미리보기(기본 — 아무것도 쓰지 않음)

3b. 사람과 함께 검토 ⏸ 사람 개입 단계

3c. 쓰기(승인 후에만)

4단계 — 모델, 상한, MAGI

4a. 노드 슬롯 — 어디서 어떤 에이전트·모델이 도는가

4b. 정책 상한 — 기본값을 쓰세요

4c. MAGI — 선택 사항이지만, 에이전트를 두 종류 이상 쓴다면 켤 가치가 있음

5단계 — 코디네이터 시작

경로 A — 대시보드(일반적인 방법) ⏸ 사람 개입 단계

경로 B — MCP 메시 모드(대시보드 없이)

6단계 — 스모크 테스트

사람이 실제로 한 것

문제 해결

다음으로