Threadry

Threadry는 Thread 안에서 여러 참여자가 함께 AI 작업을 진행하기 위한 local-first 협업 컨트롤 플레인입니다.

서버는 안전한 제품 상태와 메타데이터만 저장합니다. 로컬 Runner는 provider credential, provider/proxy 호출, 원시 실행 산출물을 소유합니다. 제품 화면은 인프라 세부 정보보다 협업 흐름을 먼저 보여줍니다. 주요 표면은 Workspace, Thread, AI Participant, 설정 준비 상태, 대화, 작업 보드, 필요한 시점에만 여는 inspector입니다.

현재 범위

• Workspace 생성, 시작 Thread 생성, 필수 Orchestrator 구성.
• 로컬 Runner attach/start, heartbeat readiness, 일회성 attach code 흐름.
• Runner 로컬 Provider/proxy registry, smoke readiness, chat dispatch, task/code command 처리.
• 안전한 Model Target projection, AI Participant 생성/수정, Thread 배정, pause/resume/remove, roster, inspector.
• @mention 타겟팅을 지원하는 Thread conversation composer, 안전한 AI reply materialization, blocked/failed/pending row, retry, inspector-gated metadata.
• Work Board 카드, Team Mode/code-work의 안전한 상태와 승인 문맥, review comment, 카드 상세 Dialog.
• Workspace 설정, Runner 설정, AI colleague 설정, contextual diagnostics, 그리고 package-level 검증.

모바일 전용 협업 레이아웃과 배포 환경의 Google consent 설정은 현재 저장소의 유지 범위 밖입니다.

개발 환경 실행

Threadry는 pnpm workspace입니다. 로컬에서 가장 빠르게 실행하려면 통합 dev process를 사용합니다.

pnpm install
pnpm dev

pnpm dev는 다음 프로세스를 함께 실행합니다.

• Website: http://localhost:3000
• API: http://127.0.0.1:3737
• domain, database, server, runner package watch build

프로세스를 터미널별로 분리해서 실행해야 한다면 다음 명령을 사용합니다.

pnpm --filter @threadry/website dev
pnpm --filter @threadry/server serve
pnpm runner

pnpm runner는 로컬 Runner package를 watch mode로 빌드합니다. 이 workspace 안에서 threadry-runner binary를 실행하기 전에 켜두는 것이 좋습니다.

로컬에서 Threadry 사용하기

1. 앱 실행

pnpm dev

브라우저에서 http://localhost:3000을 열고 계정을 만든 뒤 Workspace를 생성합니다. 첫 Workspace를 만들면 시작 Thread와 Orchestrator가 함께 생성됩니다. 단, 로컬 Runner가 연결되고 실행 가능한 model route가 준비되기 전까지 Orchestrator는 작업을 실행할 수 없습니다.

2. Runner 연결

Workspace 안에서 Runner 설정 또는 상태 화면을 열고 attach code를 생성합니다. 로컬 개발에서는 repo root에서 빌드된 Runner binary를 실행합니다. pnpm --filter @threadry/runner exec ...로 실행하면 process cwd가 apps/tools/runner로 잡혀 작업 workspace root도 runner package로 저장될 수 있습니다.

먼저 clone한 저장소의 root에서 아래 환경 변수를 설정합니다.

export THREADRY_REPO_ROOT="$(git rev-parse --show-toplevel)"
export THREADRY_RUNNER_HOME="$THREADRY_REPO_ROOT/.threadry-runner"
export THREADRY_RUNNER_BIN="$THREADRY_REPO_ROOT/apps/tools/runner/dist/bin/threadry-runner.mjs"

그다음 같은 터미널에서 Runner를 연결합니다.

cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" attach \
  --server http://127.0.0.1:3737 \
  --code trd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Attach code는 한 번만 사용할 수 있습니다. 첫 attach가 수락되면 Runner는 연결 메타데이터를 로컬 runner home에 저장합니다. 기본 경로는 현재 작업 디렉터리 아래의 .threadry-runner입니다. 필요하면 THREADRY_RUNNER_HOME 환경 변수나 --home 옵션으로 바꿀 수 있습니다.

Attach code는 일회성이므로 reason: "consumed_code"가 나오면 같은 code를 재사용하지 말고 UI에서 새 attach code를 생성해야 합니다.

3. Provider와 Model Target 설정

Threadry 서버는 provider credential을 저장하지 않습니다. Provider는 Runner 쪽에서 credential reference와 함께 설정합니다. 환경 변수에 저장된 OpenAI-compatible endpoint credential을 사용하는 예시는 다음과 같습니다.

export OPENAI_API_KEY="..."

cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" setup \
  --server http://127.0.0.1:3737 \
  --code trd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --provider-label "Local OpenAI" \
  --base-url "https://api.openai.com/v1" \
  --model "gpt-4.1-mini" \
  --credential-env OPENAI_API_KEY

로컬 OpenAI-compatible proxy가 실제 credential을 요구하지 않더라도 Runner는 --credential-env에 지정한 환경 변수가 존재하는지 확인합니다. 예를 들어 http://localhost:8317 proxy를 dummy credential로 사용할 때는 다음처럼 먼저 환경 변수를 만들어야 합니다.

export THREADRY_PROXY_API_KEY="dummy"

cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" setup \
  --server http://127.0.0.1:3737 \
  --code trd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --provider-label "Local OpenAI" \
  --base-url "http://localhost:8317" \
  --model "gpt-5.4" \
  --credential-env THREADRY_PROXY_API_KEY

Credential reference는 아래 방식 중 정확히 하나만 사용할 수 있습니다.

• --credential-env NAME
• --credential-keychain-service SERVICE --credential-keychain-account ACCOUNT
• --credential-file PATH

Credential reference를 로컬에서 해석할 수 있으면 Runner는 smoke check를 실행할 수 있습니다. 서버가 받는 것은 안전한 readiness metadata, summary, hash, safe ref뿐입니다. 서버는 raw provider credential, raw LLM response, bearer header, raw execution log를 받아서는 안 됩니다.

4. Thread에서 작업하기

Runner, Provider, Model Target, Orchestrator가 모두 준비되면 다음 흐름으로 사용합니다.

• Thread composer에서 메시지를 보내고 @mention으로 AI Participant를 호출합니다.
• Work tab에서 Work Board card를 만들고 상태를 이동합니다.
• Card detail dialog에서 status 변경, review comment, Team Mode/code-work의 안전한 상태와 승인 문맥, 안전한 diagnostics link를 확인합니다. 이 화면의 Team Mode 버튼은 현재 실행 요청을 보내지 않습니다.
• Diagnostics는 inspector-level metadata가 필요할 때만 엽니다.

유용한 Runner 명령

# 새 일회성 code로 Runner를 연결합니다.
cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" attach \
  --server http://127.0.0.1:3737 \
  --code trd_...

# 연결 정보와 선택적 provider/model을 한 번에 설정합니다.
cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" setup \
  --server http://127.0.0.1:3737 \
  --code trd_... \
  --provider-label "Local OpenAI" \
  --base-url "https://api.openai.com/v1" \
  --model "gpt-4.1-mini" \
  --credential-env OPENAI_API_KEY

# credential 값을 노출하지 않고 로컬 Runner 상태를 확인합니다.
cd "$THREADRY_REPO_ROOT"
node "$THREADRY_RUNNER_BIN" inspect

Runner 연결 실패 처리

setup 결과에서 reason: "consumed_code"가 보이면 attach code가 이미 사용된 상태입니다. UI에서 새 attach code를 만든 뒤 다시 실행해야 합니다.

toolReadiness.safeErrorCode: "credential_ref_unavailable"가 보이면 --credential-env에 넘긴 이름의 환경 변수가 Runner process에서 보이지 않는 상태입니다. --credential-env dummy를 쓰려면 export dummy="dummy"가 먼저 필요합니다.

출력의 workspaceRootPath가 Threadry repo root가 아니라 apps/tools/runner라면 pnpm --filter @threadry/runner exec ... 형태로 실행한 것입니다. 위의 THREADRY_REPO_ROOT와 THREADRY_RUNNER_BIN 설정을 사용해 다시 실행하세요.

검증

전체 준비 상태를 확인하려면 다음 명령을 사용합니다.

pnpm ready

Website만 빠르게 smoke check하려면 다음 명령을 사용합니다.

pnpm --filter @threadry/website build