AWR
GitHub
한국어
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

에이전트 연결

GitHub에서 소스 보기

AWR은 여러분의 에이전트를 실행하지 않습니다. 에이전트 클라이언트(Codex, Claude Code, Kimi, Cursor, Grok)가 자체 도구로 작업을 수행하며, AWR은 같은 초기화된 프로젝트에 대해 현재 프로젝트 사실, 작업 컨텍스트, 클레임, 복구 가능한 세션 메모리를 제공합니다. AWR 세션 기록의 제공자와 모델 레이블은 메타데이터일 뿐입니다 — 클라이언트를 실행하거나 구성하지 않습니다.

모든 지원 클라이언트는 같은 패턴을 따릅니다:

  1. AWR 체크아웃에서 두 실행 파일을 빌드합니다:
cargo build --locked -p awr-cli -p awr-mcp
  1. 검토된 소스 매니페스트로부터 대상 프로젝트를 초기화하고(빠른 시작 참조), --project를 프로젝트의 절대 경로로 지정하여 awr-mcp 서버를 클라이언트에 등록합니다. 각 서버는 하나의 정규 프로젝트 루트에 바인딩됩니다; 서로 다른 프로젝트의 서버에는 구분되는 이름을 부여하세요.
  2. 연결을 확인하세요 — 디스크의 구성 파일은 라이브 연결이 아닙니다 — 그리고 작업 전에 상태 읽기로 프로젝트 식별자를 확인합니다.
  3. 공유 세션 라이프사이클을 작업합니다: 세션을 시작하거나 재개하고, 컨텍스트를 읽고, 핸드오프 전에 체크포인트를 저장하고, 멈출 때 종료합니다. CLI와 MCP 도구를 참조하세요.

아래 섹션은 각 클라이언트의 병합 경로, 구성, 주의 사항을 제공합니다. 클라이언트가 자동 라이프사이클 훅을 문서화하는 경우, 실제 트리거와 영수증을 보기 전까지는 미검증으로 취급하세요; 수동 체크포인트/재개 플로는 항상 작동합니다.

Codex

Codex는 신뢰된 프로젝트에 대해서만 프로젝트 구성을 로드합니다; CLI, 데스크톱, IDE 클라이언트는 같은 호스트에서 MCP 구성을 공유합니다. 두 가지 옵션 중 하나를 선택하세요: MCP 구성 템플릿을 프로젝트의 .codex/config.toml에 병합(두 경로를 교체하고 기존 구성은 보존)하거나, 사용자 수준에서 등록합니다:

codex mcp add awr -- /absolute/path/to/awr-mcp \
  --project /absolute/path/to/initialized/project
codex mcp get awr --json

클라이언트의 /mcp 뷰에서 연결된 awr 서버를 확인하고 작업 전에 프로젝트 식별자를 검증하세요; 구성된 서버가 활성 연결의 증거는 아닙니다. 예상되는 읽기 도구: awr_project_status, awr_work_ready, awr_work_get, awr_context_compile, awr_search. 뮤테이션 도구: awr_work_transition, awr_event_append, awr_evidence_record. 서버는 모델 API 키를 요구하지 않습니다.

Codex는 자동 라이프사이클 훅을 위한 설치 프로그램이 있는 유일한 클라이언트입니다: awr client install로 --accept 전에 정확한 구성을 미리 봅니다. 설치는 기존 훅을 보존하며 신뢰를 자동으로 승인하지 않습니다. Codex는 SessionStart(startup|resume|clear|compact), PreCompact(manual|auto), SessionEnd(권고적, 짧은 타임아웃)를 문서화합니다. 클라이언트에서 실제 트리거 전달을 확인하세요 — 그 전까지는 핸드오프나 컴팩션 전에 수동으로 체크포인트를 저장하세요.

Claude Code

Claude Code는 명명된 제어 어댑터(어댑터 id claude_code)를 통해 연결합니다. 자동 시작은 불가능합니다: AWR은 Claude Code를 대신 시작하지 않으며, 스스로 중지하지도 않습니다 — 그 단계들은 여러분의 몫입니다. 어댑터가 지원하는 것은 상태 읽기, 재연결/재개, 결과 포렌식입니다.

운영자 경로:

  1. Claude Code를 직접 시작합니다.
  2. 제네릭 클라이언트와 네이티브 대화 ID로 AWR에 바인딩합니다:
awrj client bind --client generic --external-session claude:<native-id> \
  --work "$AWR_WORK" --session "$AWR_SESSION"
  1. AWR 관찰이 필요하면 공유 CLI의 외부 실행 보고를 통해 단계를 보고합니다.
  2. 재시도 시에는 새로운 것을 시작하기 전에 같은 실행 신원을 재연결합니다.

Kimi

이 가이드는 Kimi Code 0.41.0(2026-09-08 검사)을 대상으로 합니다; 이전 kimi-cli 릴리스는 다른 구성 경로와 플래그를 사용하므로 먼저 kimi --version과 kimi --help를 확인하세요. Kimi의 터미널 도구로 AWR CLI를 호출하고, 선택적으로 이 서버를 프로젝트의 .kimi-code/mcp.json(사용자 수준: ~/.kimi-code/mcp.json)에 다른 항목을 보존하면서 병합하여 같은 프로젝트를 stdio MCP로 연결합니다:

{
  "mcpServers": {
    "awr": { "command": "/absolute/path/to/awr-mcp",
      "args": ["--project", "/absolute/path/to/initialized/project"],
      "cwd": "/absolute/path/to/initialized/project" }
  }
}

프로젝트 구성에는 워크스페이스 신뢰가 필요합니다. 구성에는 /mcp-config를, 연결 상태 검사에는 /mcp를 사용하세요; 구성 편집으로 추가된 서버는 새로 생성되는 세션에 합류합니다. awr_project_status로 프로젝트 식별자를 확인하세요. Kimi 세션 메타데이터의 제공자 레이블은 moonshot입니다.

Kimi 자체의 kimi --continue, kimi --session <kimi-conversation-id>, /compact는 자체 대화에 대해 동작합니다; 이들의 ID는 AWR ID와 별개입니다. 컴팩트 후에는 같은 활성 AWR 세션에 대해 컨텍스트를 컴파일하세요 — 명시적 AWR 재개는 실제 핸드오프를 위한 것입니다. Kimi는 SessionStart, SessionEnd, PreCompact, PostCompact 훅을 문서화하지만, 이 통합은 자동 어댑터를 설치하지 않습니다; 수동 체크포인트 절차를 사용하세요.

Cursor

Cursor 3.18.9(2026-09-17)를 기준으로 확인했습니다. Cursor에서 awr client install을 실행하지 마세요(Unsupported), 그리고 바인딩에 --client cursor를 전달하지 마세요(InvalidInput) — 아래에 보이는 제네릭 클라이언트 신원을 사용하세요. stdio 템플릿을 프로젝트의 .cursor/mcp.json 또는 사용자 ~/.cursor/mcp.json에 병합합니다:

{
  "mcpServers": {
    "awr": { "type": "stdio", "command": "/absolute/path/to/awr-mcp",
      "args": ["--project", "/absolute/path/to/initialized/project"] }
  }
}

Cursor의 stdio 필드 테이블은 "type": "stdio"를 요구하며 cwd를 받지 않습니다. AWR에는 절대 경로 command와 --project만 필요합니다. 시작 실패 시 창을 다시 로드하고 Output → MCP Logs를 확인하세요; 두 구성 파일이 모두 존재하면 Agent Window가 어떤 것에 연결했는지 Customize에서 확인하세요. 두 가지 주의 사항:

그룹화된 도구. 현재 소스 트리에서 기본 tools/list는 플랫한 도구 이름 대신 여덟 개의 도메인 도구(awr_query, awr_context, awr_work, awr_evidence, awr_session, awr_continuity, awr_change, awr_compaction)를 반환합니다. awr_query를 통해 상태를 프로브합니다:

{"child_tool": "awr_project_status", "arguments": {}}

플랫한 이름은 여전히 호출 가능하지만 기본 카탈로그에는 없습니다; Cursor 빌드가 도메인을 통해 라우팅할 수 없는 경우에만 AWR_MCP_TOOL_EXPOSURE_MODE=flat을 설정하세요. 패키징된 릴리스는 그룹화된 awr_query를 노출하지 않습니다 — 이 경로를 위해서는 소스 트리에서 빌드하고, 먼저 빌드의 도구 카탈로그를 확인하세요.

Cloud Agents는 노트북의 awr-mcp나 127.0.0.1에 도달할 수 없습니다; 서버 측 프로젝트 루트가 있는 도달 가능한 HTTPS 프런트 도어가 필요합니다. AWR의 공유 HTTP 서비스는 bearer 토큰을 사용합니다(Cursor OAuth가 아님):

{
  "mcpServers": {
    "awr": { "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer ${env:AWR_ENGINEERING_TOKEN}" } }
  }
}

신원을 위해 네이티브 대화 ID로 제네릭 클라이언트를 바인딩하되, 비어 있으면 실패하도록 하여 리터럴 cursor:를 바인딩하는 일이 없게 하세요:

: "${HOST_CONVERSATION_ID:?set the native host conversation ID first}"
AWR_EXTERNAL="cursor:${HOST_CONVERSATION_ID}"
awrj client bind --client generic --external-session "$AWR_EXTERNAL" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

Cursor는 .cursor/hooks.json에 sessionStart, sessionEnd, preCompact 훅을 문서화하지만, 그 방언을 위한 설치 프로그램은 없습니다 — 라이브 훅 트리거와 체크포인트 영수증을 확보할 때까지 수동으로 체크포인트를 저장하세요.

Grok

Grok Build 1.0.13(2026-09-08)을 기준으로 확인했습니다. Grok의 터미널 도구로 AWR CLI를 호출하거나, 프로젝트 디렉터리에서 stdio MCP 클라이언트를 연결하세요:

cd /absolute/path/to/initialized/project
grok mcp add --scope project awr -- /absolute/path/to/awr-mcp \
  --project /absolute/path/to/initialized/project
grok mcp doctor awr --json

add --scope project는 .grok/config.toml을 작성하거나 갱신합니다(플래그를 생략하면 사용자 범위가 기본값); awr이 이미 다른 프로젝트를 가리킨다면 구분되는 서버 이름을 사용하세요. 동등한 테이블은 다음과 같습니다:

[mcp_servers.awr]
command = "/absolute/path/to/awr-mcp"
args = ["--project", "/absolute/path/to/initialized/project"]

Grok Build에서 /mcps로 연결을 검사하고 새로 고친 다음, awr_project_status를 호출하고 프로젝트 식별자를 확인하세요. 프로젝트 신뢰는 별도의 전제 조건입니다: 신뢰되지 않은 폴더는 서버가 시작되지 않은 상태로 남기므로, 먼저 클라이언트의 일반 신뢰 워크플로에서 프로젝트를 검토하세요. Grok 세션 메타데이터의 제공자 레이블은 xai입니다.

Grok의 네이티브 대화 계속하기는 AWR 세션 복구와 별개입니다:

grok --cwd "$AWR_PROJECT" --continue
grok --cwd "$AWR_PROJECT" --resume <grok-conversation-id>

Grok의 --session-id는 새 대화를 생성합니다 — AWR ID도 재개 플래그도 아닙니다. 네이티브 컴팩션 후에는 같은 활성 AWR 세션에 대해 컨텍스트를 컴파일하세요; 명시적 AWR 재개 플로는 실제 핸드오프에만 사용하세요.

Grok Build는 훅 시스템에 세션 및 컴팩트 이벤트를 문서화하지만, 여기에는 자동 어댑터가 설치되지 않습니다; 실제 트리거와 영수증을 확인할 때까지 수동 체크포인트 절차를 사용하세요. Grok 웹의 커스텀 커넥터는 도달 가능한 MCP URL을 요구합니다 — 로컬 실행 파일 경로는 그 URL로 입력할 수 없습니다; AWR의 공유 HTTP 서비스가 그 역할을 할 수 있지만, 배포와 커넥터의 인증 요구 사항 충족은 이 가이드가 검증하지 않는 별도의 단계입니다.

다음 단계

  • MCP 도구 — 연결 후 클라이언트가 호출할 수 있는 전체 도구 목록.
  • 일상 워크플로 — 어떤 클라이언트를 사용하든 시작-작업-체크포인트-재개 루프.