wctx

코딩 에이전트를 위한 워크스페이스 컨텍스트.

당신의 시스템은 여러 저장소에 걸쳐 있습니다. 에이전트의 컨텍스트도 그래야 합니다.

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

코딩 에이전트 세션은 파일이 편집되는 저장소로 범위가 제한됩니다. 그러나 조사 대상 시스템은 그렇지 않습니다. 따라서 UI 저장소에서의 세션은 버그가 실제로 SDK에 있다는 것을 알아내지만, 일주일 후 SDK에서 새 세션을 열면 그 지식은 사라집니다.

wctx는 완료된 에이전트 세션을 구조화되고 증거 기반의 엔지니어링 컨텍스트로 변환하고, MCP를 통해 향후 세션에 제공합니다. 로컬 우선: 클라우드 계정, 임베딩, 전사 기록 업로드가 필요 없습니다.

2분 데모

pnpm install
pnpm demo

API 키도, 네트워크도 필요 없습니다. 세 개의 합성 저장소를 구축하고, 하나에서 완료된 세션을 가져온 다음, 다른 저장소에서 일반 언어 질문을 합니다:

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

그런 다음 SDK 파일이 변경되고, 증거가 신뢰할 수 없게 됩니다:

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

전체 워크스루: docs/demo.md.

Related MCP server: obsmcp

설치

Node 22+와 git이 필요합니다.

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

MCP 설정

claude mcp add wctx -- wctx mcp

또는 Codex 및 기타 MCP 클라이언트의 경우:

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

일곱 가지 도구, 점진적 공개를 위해 순서가 정해져 컨텍스트 창에서 비용 효율적으로 유지됩니다:

wctx mcp-info는 표면과 클라이언트 구성 스니펫을 출력합니다.

세션이 학습한 내용 기록

세션 종료 시 하나의 명령어입니다. 필요한 경우 세션을 가져오고 단일 단계로 증거를 기록하며, 기본적으로 실행 중인 세션을 사용합니다:

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

또는 에이전트에게 "우리가 배운 것을 기록해" 라고 요청하면, 자체 세션 ID로 finalize_session을 호출합니다. 내부 ID를 알 필요가 없으며, 하나의 세션에서 반복적으로 호출하면 세션이 중복되지 않고 증거가 누적됩니다.

사전 예방적으로 만들기

에이전트는 무언가가 지시할 때만 이 작업을 수행하며, 이를 명시하기 가장 강력한 장소는 프로젝트 자체의 에이전트 파일입니다. 이 파일은 모든 요청 시 읽힙니다:

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

지침은 언제 검색할지(중요하지 않은 것을 조사하기 전), 언제 기록할지(근본 원인, 근거가 있는 결정, 어렵게 얻은 제약 조건, 해결되지 않은 질문, 놀라운 점), 그리고 무엇을 기록하지 않을지를 다룹니다. 이것이 기억해야 하는 도구와 자동으로 축적되는 도구의 차이입니다.

요약이 전혀 제공되지 않으면 wctx capture는 세션의 기록된 도구 활동(파일 수, 명령어, 오류, 변경된 파일)에서 사실적인 요약을 도출합니다. 의도적으로 지루합니다: 도구 호출에서 서사를 만들어내는 것은 이 프로젝트가 생성하기를 거부하는 자신감 있는 넌센스일 것입니다.

핵심 개념

워크스페이스 — 저장소 위의 논리적 제품. 컨텍스트 경계. 저장소는 편집 경계로 유지됩니다; 여기서 에이전트의 쓰기 범위를 넓히는 것은 없습니다.

저장소 — 등록된 git 체크아웃으로, 실제 경로로 식별되어 동일한 저장소가 심볼릭 링크나 하위 디렉토리를 통해 두 번 등록될 수 없습니다. 여러 워크스페이스에 속할 수 있습니다.

관계 — 선언된, 방향성 있는, 타입이 지정된 엣지(uses, depends_on, calls, imports, consumes_api, provides_api, shares_schema_with, related). 탐색은 양쪽 방향으로 엣지를 따릅니다. verify-ui가 websdk를 사용한다면 websdk의 세션도 verify-ui가 배운 것을 원하기 때문입니다.

세션 — Xirp, Claude Code 또는 일반 JSONL의 정규화된 코딩 에이전트 세션으로, cwd, 브랜치, 커밋, 메시지 및 도구 활동을 포함합니다.

증거 — 발견 사항, 결정, 변경 사항, 해결되지 않은 질문, 알려진 문제, 아키텍처 노트 또는 제약 조건으로, 관련된 저장소(종종 세션이 실행된 저장소가 아님)에 첨부되며, 관련된 파일과 심볼 및 해당 커밋이 참인 시점을 포함합니다.

신선도 — git 기반 판정으로, 참조된 파일이 해당 커밋 이후 변경되었는지 여부: current, possibly_stale, stale 또는 unknown.

아키텍처

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

세부 사항 및 각 경계 뒤의 추론: docs/architecture.md.

Xirp 통합 상태

Xirp는 실제로 문서화된 읽기 경로를 노출하는 것으로 밝혀져, 어댑터는 스텁이 아닌 실제입니다.

어댑터는 두 스키마 문자열을 고정하고 알 수 없는 버전에서 추측하지 않고 큰 소리로 실패합니다. 확인되지 않은 사항과 재현 방법을 포함한 전체 증거: docs/research/xirp.md.

보안

아무것도 기계를 떠나지 않습니다. 클라우드, 텔레메트리, 임베딩 API, 전사 기록 업로드가 없습니다. 전체 종속성 목록은 @modelcontextprotocol/server, better-sqlite3, commander 및 zod입니다.

• 전사 기록은 데이터 디렉토리로 복사되며(Claude Code는 30일 후 자체 전사 기록을 삭제함), 수정된 복사본이 함께 생성됩니다. 수정된 복사본만 제공됩니다.

• 수정은 개인 키, JWT, 인증 헤더, AWS/GitHub/Slack/OpenAI/Google 토큰, 자격 증명이 있는 URL 및 비밀 할당을 다룹니다. 최선의 패턴 매칭이며 전사 기록이 공유하기에 안전하다는 보장이 아닙니다.

• 에이전트에 반환된 증거는 과거의 신뢰할 수 없는 데이터로 레이블이 지정되며, 명령어와 유사한 줄("이전 모든 지침 무시")은 무력화됩니다. 완화이지 면역이 아닙니다.

• 모든 git 호출은 인수 배열을 사용하며, 셸 문자열을 사용하지 않습니다. FTS5 쿼리는 구성되며, 보간되지 않습니다.

• 전사 기록 삭제와 증거 삭제는 독립적인 작업입니다.

세부 사항: docs/security.md.

기존 도구와의 비교

기능 주장은 각 프로젝트의 자체 README에서 가져왔으며, 2026-08-13에 확인되었습니다. 여기서 다른 프로젝트가 할 수 없다고 주장하는 것은 없습니다.

각 프로젝트의 메모리 경계, 캡처 메커니즘 및 아이디어로 재사용된 내용을 포함한 전체 조사: docs/research/competitive-landscape.md.

평가

합성 15개 쿼리, 28개 항목 코퍼스(pnpm eval)에서 관련 이전 세션이 15개 중 15개 쿼리에서 상위 5위 안에 들었고 15개 중 11개에서 1위를 차지했으며, 중간 로컬 검색 지연 시간은 1.6ms였습니다. 일반 FTS5에 워크스페이스 토폴로지를 추가하면 이 코퍼스에서 적중률은 변하지 않았지만 MRR이 0.839에서 0.867로 개선되었고, 저장소 귀속이 정확해졌으며(0.93 → 1.00), 관련 없는 저장소의 결과가 제거되었습니다(쿼리당 0.20 → 0.00).

코퍼스는 작고 합성적이며 쿼리를 작성한 동일한 사람이 작성했습니다. 이것이 숫자 읽기에 의미하는 바는 docs/evaluation.md에 설명되어 있습니다.

제한 사항

전체 정직한 목록: KNOWN_LIMITATIONS.md. 가장 중요한 세 가지는 다음과 같습니다:

• 검색은 키워드 중심입니다. FTS5는 토큰을 매칭합니다. 어휘적 중복이 없는 완전히 의역된 쿼리는 결과를 놓칠 수 있으며, 구조적 가중치는 이를 부분적으로만 보완합니다.

• 최신성은 검증이 아닙니다. "참조된 파일이 변경되었는가?"라는 질문에 답할 뿐, "이 주장이 여전히 사실인가?"라는 질문에는 답하지 않습니다. 변경되지 않은 파일에서의 동작 변화는 감지되지 않습니다.

• 관계는 선언되며, 추론되지 않습니다. 선언되지 않은 관계는 순위에 반영되지 않습니다.

로드맵

핵심 루프를 개선하는 정도에 따라 정렬:

1. 하네스 stop 훅을 통한 자동 세션 종료 (현재는 수동).

2. Xirp 어댑터를 여러 버전과 codex / gemini 하네스에 걸쳐 강화.

3. 충돌 감지 및 대체 제안 — 스키마는 둘 다 지원하지만, 현재는 이를 채우는 기능이 없음.

4. 기존 CatalogProvider 확장 지점을 통해 Backstage / Portal catalog-info.yaml 가져오기.

5. 거의 중복된 결과를 포함하는 더 어려운 평가 코퍼스를 구축하여, 위상이 순서뿐만 아니라 발견에도 도움이 되는지 테스트.

기여하기

CONTRIBUTING.md를 참조하세요. pnpm typecheck && pnpm lint && pnpm test가 통과해야 하며, pnpm demo가 자격 증명 없이 클린 클론에서 작동해야 합니다.

귀속 및 비소속

wctx는 Xirp, Spotify Portal, Backstage 및 MCP의 공개 아이디어에서 영감을 받은 독립적인 오픈 소스 실험입니다.

이 프로젝트는 Spotify와 제휴하거나 보증하지 않습니다.

비교 표에 있는 어떤 프로젝트의 소스 코드도 복사되지 않았습니다. Backstage의 Component/System 구분은 런타임 종속성이 아닌 설계 영감으로 사용되며, Backstage 인스턴스는 필요하지 않습니다.

라이선스

MIT. LICENSE를 참조하세요.