t3code 딥다이브
— 여러 AI 코딩 도구를 하나의 작업실로 묶는 법

1프로젝트 한줄 요약

T3 Code는 이미 설치하거나 연결해 둔 코딩 에이전트에 공통 화면을 제공하는 애플리케이션입니다. README는 이를 agent harness control surface라고 부릅니다. 여기서 harness는 에이전트의 도구 실행·승인·대화 진행을 관리하는 실행 틀이고, control surface는 사용자가 그 작업을 조작하는 화면입니다.

프로젝트 파일과 에이전트 실행은 서버가 있는 컴퓨터에 두고, 여러 기기의 화면이 같은 작업을 제어하도록 만드는 것이 핵심입니다. 데스크톱 앱은 Electron으로 웹 화면을 감싸고 서버 실행기도 함께 제공합니다. 모바일 앱은 React Native로 별도 구현되어 다른 컴퓨터의 서버에 접속합니다. 이 역할 구분은 docs/internals/overview.md의 소유권 경계와 서버·클라이언트 패키지 구성에서 확인할 수 있습니다.

1-1. 사용자 요청 하나가 지나가는 여섯 단계

1. 사용자가 프로젝트와 에이전트를 고르고 요청을 입력합니다.
2. 클라이언트가 규약에 맞춘 RPC 요청을 WebSocket으로 보냅니다.
3. 서버가 권한과 현재 상태를 확인하고, 명령으로부터 이벤트와 후속 작업을 결정합니다.
4. 이벤트·조회용 상태·명령 처리 영수증·후속 작업을 SQLite 트랜잭션에 저장합니다.
5. 별도의 작업자가 공급자 어댑터를 통해 실제 에이전트를 실행하고 결과를 다시 상태에 반영합니다.
6. 구독 중인 화면이 변경 사항을 받고, 실행 후 체크포인트로 코드 차이를 확인할 수 있습니다.

1-2. 처음 읽을 때 잡아야 할 범위

입문자는 모델의 추론 원리를 구현하는 프로젝트로 접근하기보다, 외부 프로그램을 안정적인 제품으로 연결하는 방법에 주목하면 좋습니다. packages/contracts의 데이터 규약, apps/server의 실행·저장, packages/client-runtime의 화면 공통 상태를 한 줄로 연결해 보는 것이 첫 목표입니다.

2왜 주목받는가

2026-10-23 분석 기준 GitHub Trending Monthly 16위이며, 스타는 29,528개, 포크는 7,919개입니다. 이 숫자만으로 실제 사용자 수·성능·상승 원인을 알 수는 없습니다. 다음 세 가지는 README의 지향과 구현 구조를 함께 볼 때 추론할 수 있는 주목 요인입니다.

2-1. 기존 에이전트와 구독을 공통 화면으로 연결한다

README는 Claude Code·Codex·Cursor·Grok Build·OpenCode·Google Antigravity를 소개하며, 기존 구독과 연결하는 사용법을 설명합니다. 공급자마다 실행과 승인 방식이 다르지만, T3 Code는 공통 어댑터 규약으로 이를 받아들입니다. 공급자를 바꿀 때도 프로젝트·대화·차이 보기 같은 주변 경험을 이어 가려는 방향이 읽힙니다.

주목할 지점은 에이전트의 수보다, 서로 다른 에이전트를 하나의 상태 모델과 조작 방식으로 연결하는 설계입니다. 다만 실제 기능은 공급자별 역량에 따라 다릅니다. 공통 화면이 있다고 대화 복구·분기·실행 중 추가 지시까지 모두 같은 수준으로 지원되는 것은 아닙니다.

2-2. 원격 사용을 구조의 출발점에 둔다

웹·데스크톱·모바일이 서버를 공유하려면 인증, 끊긴 연결의 복원, 작은 데이터 전송이 필요합니다. apps/server/src/ws.ts의 subscribeOrchestrationV2Shell()은 마지막 수신 순서 번호와 재생 예산에 따라 변경분 재생이나 새 스냅샷을 선택합니다. packages/client-runtime은 연결과 상태 처리를 웹·모바일에서 공유합니다. 휴대폰 지원이 별도 화면 하나를 추가하는 문제를 넘어서는 이유입니다.

2-3. 경쟁 제품과 비교할 때 볼 축

README는 Codex 데스크톱 앱·Conductor·Claude Desktop·Cursor Glass에서 영감을 받았다고 밝힙니다. 아래는 이들 제품의 최신 기능 순위표가 아니라, 대안을 고를 때 확인할 설계 축입니다. 타 제품의 세부 기능이나 요금은 비교 범위에 포함하지 않습니다.

여러 에이전트를 같은 흐름으로 다루고 원격 화면까지 직접 확장하려는 개발자에게 구조적 장점이 있습니다. 반면 한 공급자의 고유 기능만 깊게 사용하는 경우에는 그 공급자의 전용 화면이 더 자연스러울 수도 있습니다. 범용성이 모든 작업에서 우위를 뜻하지는 않습니다.

2-4. README와 코드의 범위가 완전히 같지는 않다

3기술 스택 전체 지도

이 저장소는 여러 앱과 패키지를 함께 관리하는 모노레포입니다. pnpm-workspace.yaml이 apps/*, infra/*, packages/*, scripts, oxlint-plugin-t3code를 워크스페이스로 묶습니다. 아래 버전은 커밋 d7a8d6f3의 의존성 선언 또는 catalog 값입니다. 개별 선언이 공용 overrides로 바뀌는 경우에는 그 차이도 표시했습니다.

3-1. 백엔드: 실행·통신·저장을 한 환경 안에 묶는다

SQLite 엔진 버전을 별도 npm SQLite 드라이버 버전으로 적으면 부정확합니다. 이 구현은 Node 내장 API를 사용합니다. apps/server/src/persistence/Sqlite.ts는 readerWorker: true와 checkpointWorker: true로 읽기 전용 작업과 체크포인트 동기화를 별도 워커에 맡기도록 설정합니다. 워커를 사용할 수 없는 경우에는 주 연결을 사용하는 대체 경로가 있습니다.

3-2. 프론트엔드: 같은 제품, 서로 다른 화면 기술

웹과 모바일은 HTML 컴포넌트를 그대로 공유하는 구조가 아닙니다. 두 앱이 함께 의존하는 @t3tools/client-runtime과 @t3tools/contracts가 공통 동작을 담당합니다. 화면이 달라도 재연결 규칙을 따로 구현하지 않게 하는 선택입니다.

3-3. 인프라·빌드: 로컬 환경과 원격 제어 기반을 구분한다

infra/relay/src/worker.ts는 Cloudflare Worker와 Postgres 관련 계층을 조합합니다. infra/relay/README.md는 연결된 뒤 일반 API·WebSocket 통신이 선택한 환경으로 향한다고 설명합니다. 이 제어 평면을 로컬 SQLite 서버의 저장 계층과 혼동하면 전체 구조를 잘못 이해하게 됩니다.

의존성 목록을 읽는 목표는 라이브러리 이름 암기가 아니라, 각 부품이 어느 경계와 책임을 맡는지 설명하는 것입니다.

3-4. CI 설정도 아키텍처의 일부다

.github/workflows/ci.yml의 changes 작업은 패키지 영향 범위를 계산합니다. 린트는 문서를 포함해 항상 실행하고, 빌드·타입 검사·서버·웹·모바일 테스트 등은 영향 범위에 따라 실행합니다. 변경 감지에 실패하면 검사를 넓게 실행하는 방향으로 설계되어 있습니다.

4아키텍처 심화 분석

4-0. 전체 시스템 구조도

아래 그림의 핵심 경계는 조작하는 기기와 파일을 소유한 실행 환경 사이입니다. Electron의 렌더러도 이 규약을 따릅니다. T3 Connect의 연결 제어와 실제 에이전트 실행은 서로 다른 책임입니다.

4-1. 패턴 ①: 계약과 어댑터로 변경의 전파를 제한한다

packages/contracts/src/rpc.ts의 WsOrchestrationV2SubscribeShellRpc는 요청 입력, 성공 응답, 오류를 함께 선언합니다. TypeScript 타입을 공유하는 것에 더해 Effect Schema로 통신 경계의 데이터 모양을 표현합니다. 잘못된 JSON을 단순 타입 단언으로 믿는 방식과 구별되는 지점입니다.

// packages/contracts/src/rpc.ts의 선언
const WsOrchestrationV2SubscribeShellRpc = Rpc.make(
  ORCHESTRATION_V2_WS_METHODS.subscribeShell,
  {
    payload: OrchestrationV2RpcSchemas.subscribeShell.input,
    success: OrchestrationV2RpcSchemas.subscribeShell.output,
    error: Schema.Union([
      OrchestrationV2GetShellSnapshotError,
      EnvironmentAuthorizationError,
    ]),
    stream: true,
  },
);

반대쪽 경계에는 공급자가 있습니다. packages/provider-core/src/server/ProviderAdapter.ts의 ProviderAdapterV2는 getCapabilities()·planSelectionTransition()·openSession()을 노출합니다. 열린 세션의 ProviderAdapterV2SessionRuntime에는 startTurn(), interruptTurn(), rollbackThread(), 이벤트 스트림 등이 정의됩니다.

구체적인 예는 packages/provider-pi/src/server/adapter.ts의 makePiAdapterV2()와 PiAdapterV2Driver.create()입니다. Pi 고유의 프로토콜 처리는 이 어댑터 안에 두고, 상위 계층에는 ProviderAdapterV2Event의 message.updated·turn.terminal 같은 공통 사건을 전달합니다.

인증과 권한도 따로 읽어야 합니다. apps/server/src/auth/RpcAuthorization.ts의 RPC_REQUIRED_SCOPES는 목록 구독에 읽기 권한을, 명령 실행에 조작 권한을 지정합니다. 소켓에 접속할 수 있다는 사실과 모든 메서드를 실행할 수 있다는 사실은 다릅니다.

4-2. 패턴 ②: 이벤트 기록과 outbox를 함께 커밋한다

apps/server/src/orchestration-v2/Orchestrator.ts의 dispatchWithReceipt()는 스레드별 잠금을 적용합니다. 내부 dispatchWithReceiptEffect()는 같은 commandId의 영수증을 먼저 조회합니다. 이미 처리한 명령이면 기존 결과를 돌려주고, 다른 스레드에 같은 ID를 재사용한 충돌도 검사합니다.

새 명령은 현재 상태에 따라 이벤트와 후속 작업의 계획을 만듭니다. 이 단계에서 공급자 실행이나 프로젝트 파일 변경을 직접 수행하지 않습니다. 다만 저장된 상태를 조회하므로, 함수 전체가 데이터베이스와 무관한 순수 함수라고 부르는 것도 정확하지 않습니다.

// EventSink.ts의 commitCommandEffect() 내부 핵심 순서
// 예약·중복 처리·오류 처리를 생략한 발췌
const storedEvents = yield* eventStore.append({
  commandId: input.commandId,
  events: normalized,
});
const outcomes = yield* applyStoredEvents(storedEvents);
yield* effectOutbox.enqueue(input.effects);
// 이어서 결과 sequence를 담은 receipt를 upsert한다.
// 이 작업 전체를 commitThenPublish()의 withTransaction이 감싼다.

EventSink.ts의 commitCommandEffect()는 영수증 예약, 이벤트 추가, 조회용 상태 반영, outbox 등록, 최종 영수증 기록을 같은 트랜잭션에 넣습니다. commitThenPublish()는 커밋 후에 알림을 발행하며, 발행 순서를 위한 세마포어도 사용합니다. 화면에 보인 결과가 아직 저장되지 않은 상태가 되는 일을 줄이는 설계입니다.

EffectWorker.ts의 layerWithOptions()는 outbox.claimNext()로 작업을 확보하고, executor.execute()를 실행한 뒤 성공·재시도·실패를 기록합니다. 실행 직전 취소 상태를 다시 확인하고 실행과 취소 신호를 경쟁시키는 코드도 있습니다. runDaemonWithOptions()의 기본 작업자 동시성은 4입니다. 이는 에이전트 네 개만 실행할 수 있다는 제품 한도가 아니라 후속 작업 처리기의 기본 설정입니다.

서버가 요청을 수락했다는 응답은 의도가 저장됐다는 뜻이며, 에이전트 실행과 체크포인트까지 끝났다는 뜻은 아닙니다. 이 차이를 화면의 진행 상태와 테스트에서도 유지해야 합니다.

4-3. 패턴 ③: 전체 상태와 변경분 사이에 예산을 둔다

이 코드에서 shell은 문맥에 따라 뜻이 달라집니다. ShellStream.ts의 shell은 프로젝트·스레드 목록을 그릴 최소 요약입니다. 명령을 입력하는 터미널 셸과 구별해야 합니다. 전체 대화 본문은 별도 스레드 구독에서 다룹니다.

apps/server/src/ws.ts의 subscribeOrchestrationV2Shell()은 처음 접속하면 loadSnapshot()을 호출합니다. 재접속하면 먼저 latestApplicationSequence로 현재 상한을 읽고, 마지막 수신 번호부터 재생 가능한 범위인지 확인합니다. 가능하면 loadProjectMetadataSnapshot()으로 작은 메타데이터를 읽고, 해당 범위의 사건만 따라갑니다.

여기서 highWater는 “과거분을 어디까지 재생할지” 고정하는 경계입니다. 재생하는 동안 새 사건이 생겨도 과거분의 끝을 계속 옮기지 않고, 정해 둔 상한 뒤를 실시간 흐름으로 이어 붙입니다.

ShellStream.ts의 coalesceShellApplicationEvents()는 같은 프로젝트·스레드의 여러 사건을 최신 것 중심으로 묶습니다. bufferShellLiveStream()은 동일 요약 상태의 대기 중 갱신을 합칩니다. 반면 스냅샷·동기화 표식까지 같은 방식으로 버리면 순서 의미가 깨지므로 구분합니다.

커밋 제목도 이 학습 주제와 연결됩니다. d7a8d6f3의 제목은 fix(server): avoid full shell read on resume (#23987)입니다. 현재 소스에는 재개 경로가 전체 목록 로드를 우회하는 분기가 있으며, apps/server/src/ws.test.ts에는 알 수 없는 사건을 건너뛰고 동기화 뒤 실시간 사건을 받는 테스트가 있습니다. 성능 개선율을 수치로 주장할 근거는 이 코드만으로는 없습니다.

4-4. 패턴 ④: Git 객체로 작업 전후 상태를 남긴다

apps/server/src/checkpointing/Utils.ts의 checkpointRefForThreadTurn()은 refs/t3/checkpoints/…/turn/… 형태의 ref를 만듭니다. CheckpointStore.ts의 captureCheckpoint()는 현재 VCS 드라이버의 체크포인트 기능을 찾아 위임합니다.

실제 Git 구현은 apps/server/src/vcs/GitVcsDriver.ts의 GitVcsDriver.checkpoints.captureCheckpoint에 있습니다. 임시 인덱스를 만들고 GIT_INDEX_FILE로 지정한 뒤, write-tree·commit-tree·update-ref를 사용합니다. 체크포인트 커밋 객체는 만들지만 사용자의 브랜치를 앞으로 이동시키지 않는 방식입니다.

초보자에게 좋은 발견은 Git이 명령 모음인 동시에 파일 상태를 저장하는 객체 데이터베이스라는 점입니다. Git 공식 문서의 객체 설명을 함께 읽으면 트리와 커밋의 관계를 이해하기 쉽습니다. 이 저장소에서는 그 기능을 제품의 차이 보기와 되돌리기에 이용합니다. 단, 파일을 되돌리는 것과 에이전트가 기억하는 대화를 되돌리는 것은 함께 조정해야 합니다. 내부 아키텍처 문서는 공급자가 대화 롤백을 지원하지 않으면 파일 변경 전에 거부해야 한다고 설명합니다.

5디렉토리 구조 해부

5-1. 의존성은 아래에서 위로 쌓아 읽는다

폴더 이름이 비슷해도 역할은 다릅니다. packages/source-control-github 등은 호스팅 서비스와의 연동을 담당하고, apps/server/src/vcs는 작업 디렉터리의 버전 관리 연산을 담당합니다. GitHub API에서 PR을 읽는 일과 로컬 Git 인덱스를 다루는 일을 같은 책임으로 묶지 않습니다.

공급자 구현도 모두 packages/provider-*로 이동한 것은 아닙니다. Codex·Claude 관련 구현은 apps/server/src/provider에도 많이 남아 있습니다. 디렉토리의 대칭성을 가정하지 말고 실제 import와 서비스 연결을 따라가야 합니다.

5-2. 코드 규모와 집계 범위

집계 범위는 Git 추적 파일 중 apps·packages·infra·native·scripts·oxlint-plugin-t3code입니다. 경로 구성요소가 Vendor, vendor, deps, node_modules, dist, dist-electron, build인 파일은 제외했습니다. .repos의 참조 코드는 포함하지 않았습니다.

기타에는 .m·.mm·.py·.sh·.ps1·.qml·.zig를 포함했습니다. 공백·주석·테스트·생성 코드를 포함하는 물리 줄 수이며, 외부 유래 헤더까지 모두 제거한 순수 수작업 구현량은 아닙니다. JSON·YAML·Markdown·바이너리는 합계에서 제외했습니다.

이 범위의 TypeScript·TSX 테스트 파일은 .test.·.spec. 이름 기준 1,485개, 466,623줄입니다. TypeScript 계열 약 145만 줄의 약 32%지만, 테스트 비중만으로 검증 품질을 단정하지는 않습니다. 규모가 큰 이유 중 하나는 packages/effect-codex-app-server처럼 상세한 프로토콜 스키마가 코드로 들어 있기 때문입니다.

6학습 포인트 (기술별)

6-1. TypeScript: 종류에 따라 데이터가 달라지는 타입

ProviderAdapterV2Event는 type으로 사건 종류를 구분하는 유니온입니다. 메시지 갱신과 명령 출력 조각은 필요한 필드가 다릅니다. 모든 필드를 선택 사항으로 만드는 대신 종류별 모양을 나누면, 분기 안에서 필요한 값이 존재한다는 것을 타입으로 설명할 수 있습니다.

// 학습용 축소 모형. 실제 계약의 필드와는 다르다.
type Update =
  | { type: "message.updated"; text: string }
  | { type: "turn.terminal"; status: "completed" | "failed" };

function summarize(update: Update): string {
  switch (update.type) {
    case "message.updated":
      return update.text;
    case "turn.terminal":
      return update.status;
  }
}

실습 아이디어: 새 사건 종류를 추가하고 처리하지 않은 분기를 찾아보세요. 이어서 실제 packages/provider-core/src/server/ProviderAdapter.ts에서 command_output.delta와 turn.terminal의 필드를 비교합니다. 타입만 맞는 데이터와 실행 중 검증을 통과한 데이터의 차이도 설명해 봅니다.

6-2. Effect: 작업의 결과·실패·필요 서비스를 읽는다

Effect 코드의 낯선 기호부터 줄여 봅시다. Effect.Effect<A, E, R>에서 A는 성공값, E는 예상 가능한 실패, R은 필요한 서비스입니다. yield*는 이 작업을 조합하는 문맥에서 값을 받는 표현이며, Layer는 서비스와 그 의존성을 구성합니다. 세 타입 매개변수의 의미는 Effect 4 공식 타입 문서에서도 확인할 수 있습니다.

apps/server/src/checkpointing/CheckpointStore.ts의 make는 VcsDriverRegistry를 받아 체크포인트 서비스를 만듭니다. 마지막의 Layer.effect(CheckpointStore, make)는 “이 서비스는 이 구성 작업으로 만든다”는 연결입니다. 단순 유틸리티 함수와 외부 자원을 사용하는 서비스를 구분해서 읽어 보세요.

실습 아이디어: 체크포인트 서비스 선언의 각 메서드에서 성공값과 실패 타입을 표로 옮깁니다. Effect.Effect<boolean, CheckpointStoreError>에서 false와 오류가 서로 다른 상태인 이유를 설명해 보세요. 없는 ref를 찾는 일과 Git 실행 자체가 실패한 일은 같지 않습니다.

6-3. React 상태: 값이 같으면 기존 객체를 살린다

packages/client-runtime/src/state/shellReducer.ts의 reuseUnchangedThreadShells()는 이전 스레드를 ID로 찾고, 의미상 같으면 기존 객체를 재사용합니다. applyShellStreamEvent()는 같은 요약이 와도 수신 순서 번호를 갱신할 수 있습니다. 화면에 보이는 값의 변화와 동기화 진행을 분리한 사례입니다.

mergeShellSnapshotProjects()는 프로젝트 메타데이터 보강 응답과 전체 상태를 확정하는 응답도 구분합니다. 작은 보강 응답의 빈 스레드 배열을 전체 상태로 오해해 목록을 지우면 안 됩니다. “응답 모양이 비슷하다”는 이유만으로 같은 병합 규칙을 적용하지 않는 것이 핵심입니다.

실습 아이디어: 이름이 같은 스레드 객체가 다시 왔을 때 객체 참조를 유지하는 경우와 새로 만드는 경우를 그림으로 비교합니다. 이후 렌더링 횟수를 측정할 수 있는 작은 별도 예제로 옮겨 보세요. 객체를 재사용한다는 사실만으로 모든 React 렌더링이 사라진다고 단정하지는 않습니다.

6-4. 데이터베이스: 디스크의 안전성과 응답성을 함께 본다

apps/server/src/persistence/Sqlite.ts는 journal_mode = WAL, synchronous = NORMAL, busy_timeout = 5000, foreign_keys = ON을 설정합니다. WAL은 변경 기록을 별도 로그에 쌓는 방식이고, busy timeout은 잠긴 데이터베이스를 만났을 때 기다리는 시간을 지정합니다.

같은 파일은 WAL 재사용 시 남길 파일 크기의 기준을 32 * 1024 * 1024바이트로 지정합니다. 설정 이름은 journal_size_limit이며, 실행 중 WAL이 절대 넘지 못하는 상한은 아닙니다. 체크포인트 디스크 동기화는 별도 워커에 맡기도록 설정합니다. 여기서 SQLite 체크포인트는 앞 절의 Git 체크포인트와 다른 개념입니다. SQLite에서는 WAL 내용을 주 데이터베이스에 반영하는 작업을 뜻합니다.

실습 아이디어: “앱 종료”, “운영체제 중단”, “네트워크 단절”을 서로 다른 열로 놓고 어떤 데이터가 이미 디스크에 있는지 표시합니다. 실제 데이터베이스를 열거나 변경하지 않아도 트랜잭션과 동기화의 차이를 연습할 수 있습니다.

6-5. 네트워크: 느린 소비자도 시스템의 일부다

LiveStreamBudget.ts는 보관 중인 항목 수와 직렬화 바이트를 따로 셉니다. 큰 사건 몇 개와 작은 사건 수천 개는 서로 다른 부담이기 때문입니다. ShellStream.ts의 composeShellStreamWithEnrichment()는 초기 응답이 메타데이터 보강 응답보다 먼저 나가도록 흐름을 구성합니다.

실습 아이디어: 서버가 100개의 갱신을 만들고 화면이 10개만 읽는 상황을 그려 보세요. 같은 대상의 전체 상태 갱신은 최신 것으로 합칠 수 있지만, 모든 종류의 사건을 버려도 되는 것은 아닙니다. 어떤 사건에 합치기를 허용할지 먼저 분류합니다.

6-6. 테스트: 시간을 기다리지 말고 완료 조건을 기다린다

packages/shared/src/DrainableWorker.ts의 makeDrainableWorker()는 대기열뿐 아니라 처리 중인 작업을 포함한 outstanding을 관리합니다. drain은 이 값이 0이 되는 것을 기다립니다. 대기열에서 꺼냈지만 아직 끝나지 않은 작업을 놓치지 않는 설계입니다.

apps/server/src/ws.test.ts는 재연결 중 알 수 없는 미래 사건이 있어도 이후 정상 사건과 실시간 꼬리를 받는 경우를 다룹니다. 이런 테스트는 성공 화면만 확인하는 것보다 프로토콜 호환성의 경계를 잘 드러냅니다.

비동기 테스트의 완료 기준은 몇 초가 지났는지가 아니라, 필요한 사건과 작업이 실제로 끝났는지여야 합니다.

실습 아이디어: “대기열이 비었다”와 “작업이 완료됐다”가 다른 상황을 두 단계 도식으로 작성합니다. 이후 별도 연습 예제에서는 Deferred 신호나 drain을 완료 조건으로 사용해 봅니다.

7하드웨어 / 시스템 요구사항

2026-10-31 기능 개정: 고정 커밋 79f1fadfc602과 v0.1.6 릴리스에서 사이드 채팅, 프로젝트 고정·보관, 1Password 자격증명 연결을 확인했다. 사이드 채팅은 lineage.sideChat와 parentThreadId로 부모 스레드를 검증한 뒤 별도 탭을 연다. 도구 diff와 셸 실행은 부모의 diff 패널·터미널로 연결하므로 대화 분리와 작업 환경 분리는 구별해야 한다.

1Password 드라이버는 op CLI의 read와 inject를 호출하며 읽기를 45초로 제한한다. 여러 참조는 한 번에 읽고, 제한시간이 끝나면 참조별 재호출로 대기를 늘리지 않는다. 프로젝트 고정·보관 시각은 SQLite projection의 pinned_at·archived_at 열에 남긴다. 실습에서는 보관과 파일 삭제가 어떻게 구분되는지 확인하고, 1Password는 별도 CLI 설치·인증을 먼저 준비한다.

코드 근거: 사이드 채팅 패널 연결 · 1Password 읽기 드라이버 · 프로젝트 상태 마이그레이션 · v0.1.6 릴리스.

2026-10-31 추가 소스 검토: 고정 커밋 d2d1e4f에서 데스크톱 원격 노출 상태는 현재 네트워크 인터페이스를 다시 읽어 광고 주소를 계산합니다. Wi-Fi·DHCP 주소가 바뀌어도 오래된 접속 주소를 계속 보여 주지 않도록 한 변화입니다. 네트워크 접근 모드의 바인딩과 사용자에게 안내하는 endpoint를 구분해서 읽습니다.

Clerk 로그인 저장소는 전용 디렉터리 0700·토큰 파일 0600 권한을 적용하고, 옛 파일을 이관하며, 심볼릭 링크·일반 파일 여부를 검사합니다. 읽기·쓰기·삭제 작업 뒤에도 파일 권한을 다시 좁힙니다. 이는 파일 접근 권한 관리이며 암호화를 보장한다는 뜻은 아닙니다. Linux 테마는 XDG portal의 변경 신호를 따라가고 portal이 없으면 Chromium의 선택을 유지합니다.

2026-10-30 소스 대조: 고정 커밋 32ecd71의 서버 package.json은 0.1.5입니다. 아래 Node 허용 범위와 루트 Node·pnpm 조건은 여전히 일치합니다. 초판의 0.1.2·스타·포크는 당시 기록으로 남깁니다. 현재 README는 Codex·Claude·Cursor·Grok Build·OpenCode·Antigravity 경로를 안내하며 스레드를 시작하기 전에 최소 한 provider의 설치·인증이 필요합니다.

최신 내부 문서는 설정 소유권을 더 명확히 구분합니다. 클라이언트 선호는 해당 클라이언트에, 환경 기본값과 프로젝트 덮어쓰기는 작업 서버에 있습니다. 사용할 수 없는 설정 대상에서 다른 환경으로 자동 대체하지 않으며, All environments는 현재 연결되고 로드된 서버에 대한 명시적 일괄 수정입니다. 오프라인·미래 환경까지 동기화하는 전역 기본값으로 해석하면 안 됩니다. 원격 단말이 자기 파일·인증 정보를 서버 상태 대신 쓰지 않는다는 기존 실행 경계도 유지됩니다.

7-1. 소스와 문서에 명시된 조건

배포 실행 파일이나 Electron 앱을 쓰는 경우와, Node로 소스를 직접 실행하는 경우의 준비물이 다릅니다. 또한 공급자 자체의 요구사항이 추가될 수 있습니다. Node 허용 범위를 만족한다는 것만으로 공급자·네이티브 모듈까지 검증됐다는 뜻은 아닙니다.

7-2. 학습용 권장 사양: 공식 최소 사양은 아니다

아래는 이 구조를 공부하기 위한 보수적인 출발점입니다. 저장소에서 보장하는 최소 RAM·CPU·디스크 수치가 아니며, 에이전트 수·프로젝트 크기·브라우저 테스트·시뮬레이터에 따라 달라집니다.

필요한 자원은 화면의 크기보다, 호스트에서 동시에 실행하는 에이전트와 개발 작업의 양에 더 크게 좌우됩니다. T3 Code 자체를 사용하는 것과 로컬 LLM을 추가로 실행하는 것은 별도 문제입니다. 로컬 모델을 선택하면 그 모델의 메모리·GPU 조건이 추가됩니다.

7-3. 저장 공간과 네트워크도 요구사항이다

apps/server/src/config.ts의 deriveServerPaths()는 statev2.sqlite, 첨부 파일, 브라우저 산출물, 로그, worktree 경로를 나눕니다. 기본 포트 상수는 3773입니다. 데이터베이스 파일 크기만으로 전체 디스크 사용량을 계산하면 worktree와 산출물 증가를 놓칠 수 있습니다.

• 호스트 파일 권한: 프로젝트와 상태 디렉터리에 필요한 접근 권한이 있어야 합니다.
• Git: Git 체크포인트와 worktree 흐름을 공부할 때 호스트의 Git 동작을 함께 이해해야 합니다.
• 원격 주소: 휴대폰의 127.0.0.1은 휴대폰 자신을 가리킵니다. 접속 가능한 호스트 주소와 인증 절차가 필요합니다.
• 연결 경로: LAN·Tailscale·T3 Connect 등 선택한 방식의 도달 가능성과 세션 권한을 구분합니다.

8직접 해볼 수 있는 실습 과제

처음 두 과제는 소스를 읽고 표를 만드는 것만으로 끝낼 수 있습니다. 코드를 작성하는 과제는 원본 제품과 분리된 연습용 프로젝트에서 진행합니다. 기존 계정·실제 프로젝트·운영 데이터베이스 없이도 핵심 규칙을 연습하도록 범위를 작게 잡았습니다.

rg -n 'WsOrchestrationV2SubscribeShellRpc' packages/contracts/src/rpc.ts
rg -n 'subscribeOrchestrationV2Shell' apps/server/src/ws.ts
rg -n 'RPC_REQUIRED_SCOPES' apps/server/src/auth/RpcAuthorization.ts
rg -n 'applyShellStreamEvent' packages/client-runtime/src/state/shellReducer.ts

type Thread = { id: string; title: string };
type State = { sequence: number; threads: ReadonlyArray<Thread> };
type Item =
  | { kind: "thread.updated"; sequence: number; thread: Thread }
  | { kind: "thread.removed"; sequence: number; threadId: string };

// reduce(state, item): State를 구현한다.
// 제목이 같으면 기존 Thread 객체를 재사용한다.
// 화면 내용이 같아도 수신 sequence는 진행할 수 있다.

가장 좋은 첫 기여 연습은 기능을 크게 늘리는 것이 아니라, 작은 규칙 하나의 정상·중복·실패 경계를 설명하는 것입니다. 실제 기여를 계획한다면 README와 CONTRIBUTING.md의 현재 수용 범위를 먼저 확인하세요.

9관련 기술 심화 학습 로드맵

주당 4~6시간을 가정한 학습안입니다. TypeScript 기본 문법이 낯설면 1주차를 두 주로 늘려도 좋습니다. 매주 읽는 코드와 남길 산출물을 연결하면 큰 저장소에서도 진도를 확인할 수 있습니다.

9-1. 다음 단계는 관심 있는 경계 하나를 고른다

• 프론트엔드: 요약 목록과 상세 대화의 데이터 범위를 비교한 뒤, 긴 대화의 페이지 단위 로딩과 렌더링 비용으로 확장합니다.
• 백엔드: 영수증·outbox·작업 확보를 읽은 뒤, 취소 경쟁과 프로세스 재시작의 복구 규칙으로 확장합니다.
• 모바일: apps/mobile에서 화면과 플랫폼 기능을 읽고, 공용 런타임이 어느 부분까지 맡는지 추적합니다.
• 인프라: infra/relay의 계정 연결·자격증명·알림과 환경 서버의 작업 실행을 서로 다른 시퀀스로 그립니다.

이 저장소를 공부한 결과물은 라이브러리 목록이 아니라, 요청의 성공과 실패를 끝까지 설명하는 자기만의 시스템 그림이어야 합니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 사용자 문서

• T3 Code 공식 저장소 · 프로젝트 진입점
• README · 제품의 목적과 주요 공급자 소개
• v0.1.2 릴리스 · 2026-10-22 기준 릴리스
• 설치와 공급자 연결 · 배포 방식과 준비 조건
• 원격 접속 안내 · T3 Connect·직접 페어링·네트워크 경로
• 내부 아키텍처 개요 · 소유권·영속 의도·후속 작업의 경계
• 기여 안내 · 이슈와 변경 제안의 범위

11-2. 핵심 소스로 바로 가기

11-3. 관련 기술 공식 문서

• Effect 4 공식 문서 · 이 저장소의 주 버전과 맞춰 학습하기
• Effect 타입의 성공·오류·요구 서비스 · 6-2절의 세 타입 매개변수
• React의 객체 상태 갱신 · 기존 값을 직접 바꾸지 않는 상태 처리
• SQLite WAL 문서 · 체크포인트와 동기화의 절충
• Git 객체 내부 구조 · 트리와 커밋 객체를 만드는 원리

현재 상태 (2026-10-23 확인)