Nimbalyst Wiki가 Claude Code와 Codex 세션을 로컬 위키로 정리한다

Nimbalyst Wiki는 Claude Code와 Codex 세션에서 나온 결정을 프로젝트 안의 마크다운 위키로 정리하는 플러그인이다. 기본 위키는 로컬에 저장되며 계정이나 서버가 필요 없다. Node.js 22 이상과 함께 제공되는 npm이 있어야 사용할 수 있고, Nimbalyst 앱은 설치하지 않아도 된다.

에이전트는 Home 페이지와 결정 사항, 결정 이유, 담당자가 있는 미해결 질문, 추적 항목을 위키에 기록한다. 사용자는 브라우저에서 페이지를 읽고 편집할 수 있으며, 에이전트가 작성한 내용도 실시간으로 표시된다. Claude Code, Codex, Cowork, Cursor, VS Code가 같은 파일을 사용하므로 에이전트를 바꿔도 위키를 공유할 수 있다.

설치와 시작

Claude Code에서 마켓플레이스를 추가하고 플러그인을 설치한다.

/plugin marketplace add nimbalyst/nimbalyst-wiki
/plugin install nimbalyst-wiki@nimbalyst-wiki

Codex에서는 다음 명령을 실행한다.

codex plugin marketplace add nimbalyst/nimbalyst-wiki
codex plugin add nimbalyst-wiki@nimbalyst-wiki

설치 후 Claude Code에서는 /nimbalyst-wiki:setup을 실행한다. Claude가 위키의 대상 독자를 물은 다음 README와 문서를 바탕으로 Home 페이지, 작성 가이드, 시작 페이지를 프로젝트 안에 만든다. Codex에서는 “이 저장소의 위키를 설정해줘”라고 요청하면 된다. 먼저 짧게 둘러보려면 /nimbalyst-wiki:start를 실행한다.

세션에서 정한 내용을 기록할 때는 /nimbalyst-wiki:capture를 사용한다. 결정 사항을 영향을 받는 페이지에 기록하고, 누가 언제 결정했는지와 선택하지 않은 대안, 담당자가 있는 미해결 질문을 남긴다. Claude Code는 커밋이나 계획, 여러 파일 수정이 포함된 세션이 끝나면 한 번 기록을 알린다. Codex는 플러그인 훅을 실행하지 않아 세션 종료 알림이 없으므로, 직접 “결정한 내용을 위키에 기록해줘”라고 요청해야 한다. 세션 인용은 Claude Code 기록만 읽기 때문에 Codex에서 남긴 결정에는 사용자 이름은 기록되지만 인용문은 붙지 않는다.

브라우저에서 열려면 에이전트에게 “브라우저에서 위키를 열어줘”라고 요청한다. 별도 설치 없이 페이지 트리와 편집기를 사용할 수 있으며, 페이지·그림·마인드맵·스프레드시트·목업을 편집할 수 있다. 수정 내용은 파일에 바로 저장된다. 터미널에서는 nim wiki serve를 실행한다. 설치와 데모 안내는 저장소의 시작 안내와 데모에서 볼 수 있다.

위키에 저장하는 내용과 파일 위치

기본 경로는 nimbalyst-local/wiki이며 Git에서 제외되므로 로컬에 비공개로 남는다. docs/wiki처럼 Git에 포함되는 폴더를 지정하면 코드처럼 변경 사항을 비교하고 커밋해 공유할 수 있다. 위키는 일반 파일로 구성되므로 Nimbalyst 도구 없이도 읽고 편집하고 커밋할 수 있다. 전체 형식은 FORMAT.md에 설명돼 있다.

위키에는 결정과 그 이유, 미해결 질문, 설정한 선호와 제약, 경험을 통해 얻은 교훈을 기록한다. 실제 작업은 세션·코드·추적 도구에 남고 위키는 관련 내용을 연결해 보여주는 전략적 관점의 기록이다. 에이전트에게 인증에 관한 위키 내용을 묻거나, 배포 절차 페이지를 만들거나, 브라우저에서 위키를 열어달라고 요청할 수도 있다.

각 결정은 영향을 받는 페이지 안에 표시한다. 형식 예시는 다음과 같다.

[We store and evaluate flags in Flagship.]{decided by="Dana Lee" email=dana@example.com on=2026-09-30 over="our own Durable Object store"}

미해결 질문도 같은 형식으로 기록하되 open을 사용한다. 사용자가 실제 세션에서 한 말이 근거가 될 때 에이전트는 세션 기록에서 인용을 가져온다. 결정을 지어내거나 이유·인용문을 만들어내지 않는다. 로컬 위키에서는 이름과 이메일을 git config user.name, git config user.email에서 가져온다. 수정 횟수에 따른 기록 알림 기준은 NIMBALYST_WIKI_NUDGE_MIN_EDITS로 바꿀 수 있다.

페이지는 고유 ID와 순서를 담은 <Title>.md 파일이며, 유형이 지정된 페이지에는 유형과 필드도 들어간다. 페이지 이름을 바꾸면 파일과 하위 폴더 이름도 바뀐다. 페이지 간 링크는 상대 경로와 대상 ID를 사용하므로 GitHub와 편집기에서도 동작하며, 페이지를 옮기면 Nimbalyst가 링크를 고친다. 유형 정의는 .nimbalyst/trackers/<type>.yaml에 저장한다. 항목은 각자 페이지로 저장하거나 하나의 CSV에 행으로 저장할 수 있다. 삭제한 페이지는 .trash/로 옮겨 복원할 수 있다.

위치 설정은 .nimbalyst/local-wiki.json의 location 값으로 지정한다. 설정이 없으면 nimbalyst-local/wiki를 사용한다. Git worktree는 기본 체크아웃의 위키를 공유한다. 에이전트가 파일을 직접 편집할 수도 있지만 MCP 도구와 nim은 ID, 정렬 순서, 이동 시 링크 수정, 유형 필드, CSV 행, 휴지통 처리를 지원한다.

페이지 종류와 활용

에이전트에게 경쟁사·고객·기능 등을 추적하라고 요청하면 필요한 필드를 가진 유형을 만들고, 항목별 페이지와 전체 항목을 보여주는 표를 만든다. 예를 들어 “경쟁사를 위키에서 추적해줘: 각 회사의 분류, 위협도, 설정 속도, 결제 복구”라고 요청할 수 있다.

텍스트 페이지 외에도 다음 자료를 위키 페이지로 만들 수 있다.

• 그림: 흐름이나 아키텍처를 나타내는 Excalidraw 파일이다. 에이전트가 도형과 화살표를 배치하고 브라우저에서 사용자가 위치를 바꾼다.
• 마인드맵: 미해결 질문, 위험, 브레인스토밍을 노드로 정리하며 노드를 추가·이동·접을 수 있다.
• 스프레드시트: 에이전트가 작성하는 CSV 파일로, 사용자는 일반 시트처럼 정렬하고 편집한다.
• 데이터 모델: Prisma 스키마에서 표와 관계를 그려 만들고 배치를 바꿀 수 있다.
• 목업: HTML 화면 목업을 만들어 UI 결정과 화면을 함께 둔다.
• 캔버스: 페이지를 나란히 배치하고 각 카드를 페이지의 실시간 보기로 보여준다.

각 항목은 별도의 파일로 유지된다. 예를 들어 .excalidraw, .csv, .prisma, .mockup.html 파일은 다른 도구에서도 열 수 있다. 브라우저의 새 페이지 메뉴에서 직접 만들거나 에이전트에게 요청할 수 있다.

팀 위키로 옮기기

팀과 공유할 때는 로컬 위키를 Nimbalyst Teams로 옮긴다. 텍스트 페이지, 유형이 지정된 페이지, 유형 정의와 페이지 간 링크가 팀 위키로 이동하고 팀원들은 브라우저에서 같은 페이지를 편집한다. 팀원들의 에이전트도 그 위키에 기록한다. 로컬 파일은 원래 위치에 남는다.

팀 위키에는 Google 계정으로 로그인하고 팀을 만든 뒤 이메일로 팀원을 초대한다. 팀 위키는 Cloudflare의 Nimbalyst 서버에서 실행되며 console.nimbalyst.com에서 이용한다. 이 기능은 별도 플러그인 nimbalyst-wiki-team을 사용한다. 로컬 위키가 로그인 없이 작동하도록 팀용 서버와 로그인을 별도 플러그인에 분리했다. 미리 설치할 필요는 없으며 위키 공유 과정에서 설치 안내가 나온다.

Claude Code에서는 플러그인을 0.8.0 이상으로 업데이트한 뒤 팀 이름을 붙여 /nimbalyst-wiki:team Northwind를 실행한다. 또는 “이 위키를 Northwind 팀 위키로 옮겨줘”라고 요청할 수 있다. 진행 과정에서 Claude는 추가 플러그인 설치에 동의를 구하고, 로그인, 팀과 프로젝트 선택, 이동 승인, 페이지 이동, 팀원 초대, 연결 정보 커밋을 안내한다. 플러그인을 추가한 뒤에는 Claude Code가 세션 시작 때 플러그인을 불러오므로 /exit 후 같은 폴더에서 claude --continue를 실행해 대화로 돌아온다.

팀을 아직 만들지 않았다면 Claude가 팀 이름을 제안하고 팀과 첫 프로젝트, Home 페이지를 만든다. 프로젝트는 저장소의 Git 원격 주소와 연결한다. 이미 팀이 있으면 기존 프로젝트에 연결하거나 새 프로젝트를 만들 수 있다. 이동 전에 옮길 항목을 보여주며, 중단되면 다시 실행해 이어갈 수 있다. 팀원 초대 이메일 목록은 먼저 읽어 확인받거나 초대 링크를 만들 수 있다. 팀 프로젝트를 동료 에이전트가 찾을 수 있도록 .nimbalyst/wiki.json을 커밋한다. Claude Code용 저장소 설정 .claude/settings.json에 두 플러그인을 추가할 수도 있으며, 그 파일도 커밋하면 동료가 저장소를 열 때 플러그인 설치 제안을 받는다. 로컬 파일은 삭제되지 않고 이동 표시가 붙으며 로컬 Home 페이지에 팀 위키 링크가 남는다.

Codex에서는 “이 위키를 팀 위키로 옮겨줘”라고 요청한다. 추가 플러그인을 설치한 다음 터미널에서 로그인하고 프로젝트에서 새 Codex 세션을 시작해 이어서 요청한다.

codex plugin add nimbalyst-wiki-team@nimbalyst-wiki # Codex runs this for you after you agree
codex mcp login nimbalyst-team

플러그인을 사용하지 않는 Cursor, VS Code, Cowork 등에서는 터미널에서 nim 명령으로 옮긴다. 다음 명령은 로그인, 팀 생성, 이동 항목 미리 보기, 이동을 차례로 수행한다.

nim login
nim wiki team-create "Northwind"
nim wiki move-to-team --dry-run # preview what will move
nim wiki move-to-team

팀 위키에 연결하는 다른 에이전트는 nim mcp에 사용한 것과 같은 MCP 설정에 팀 서버를 추가한다. 처음 연결할 때 Nimbalyst 로그인을 요청한다.

{
 "mcpServers": {
 "nimbalyst-team": {
 "type": "http",
 "url": "https://sync.nimbalyst.com/mcp"
 }
 }
}

초대 이메일이나 링크를 받은 사람은 브라우저에서 로그인해 팀 위키를 열 수 있다. 설치 없이 읽고 편집하고 댓글을 달 수 있다. 에이전트에서도 사용하려면 nimbalyst-wiki와 nimbalyst-wiki-team 플러그인을 설치하고 같은 이메일로 로그인한다. Claude Code에서는 두 플러그인을 설치하고 재시작한 뒤 /mcp에서 nimbalyst-team을 선택해 인증한다. Codex에서는 두 플러그인을 추가하고 codex mcp login nimbalyst-team을 실행한다. 저장소에 .nimbalyst/wiki.json이 커밋돼 있으면 해당 팀 프로젝트를 바로 사용하고, 없으면 저장소의 Git 원격 주소로 프로젝트를 찾는다.

다른 에이전트와 터미널에서 사용하기

Cursor, VS Code, Copilot 에이전트 모드, Cowork, Codex 앱 등은 플러그인 대신 nim mcp를 통해 같은 로컬 서버를 사용한다. 먼저 CLI를 설치한다.

npm install -g @nimbalyst/cli

그런 다음 에이전트별 MCP 설정에 서버를 등록한다. Cursor는 .cursor/mcp.json의 mcpServers, VS Code와 Copilot 에이전트 모드는 .vscode/mcp.json의 servers를 사용한다. Cowork는 Claude 데스크톱 앱의 MCP 설정을 사용하며 작업 공간 값은 /path/to/your/project다. Codex 앱과 다른 MCP 클라이언트는 각 클라이언트의 MCP 설정과 프로젝트 경로를 사용한다.

{
 "mcpServers": {
 "nimbalyst-wiki": {
 "command": "nim",
 "args": ["mcp", "--workspace", "${workspaceFolder}"]
 }
 }
}

앱이 nim을 찾지 못하면 which nim이 출력하는 전체 경로를 지정한다. 이후 에이전트에게 “이 저장소의 위키를 시작해줘”라고 요청하면 된다. 한 에이전트에서 만든 위키는 다른 에이전트에서도 사용할 수 있다. 이 방식에서는 플러그인의 스킬(setup, capture, 작성 가이드)을 사용할 수 없으므로 원하는 작업을 자연어로 요청한다. 브라우저 열기도 가능하며 브라우저 앱은 nim과 함께 설치된다. 플러그인 업데이트와 nim 업데이트는 별개다. nim mcp는 하루에 한 번 npm에서 새 버전을 확인하고 다음 위키 사용 때 에이전트가 알린다. 터미널에서 nim update를 실행한 뒤 새 세션을 시작해야 서버가 다시 실행된다.

nim CLI는 플러그인 사용에 필수는 아니며 스크립트와 터미널 작업에 쓸 수 있다. nim wiki는 로컬 위키와 팀 위키 모두에서 작동한다. 기본 명령은 다음과 같다.

nim wiki init # create the wiki in nimbalyst-local/wiki (ignored by git)
nim wiki init --location docs/wiki # or in a checked-in folder
nim wiki list # the page tree
nim wiki read "Product" # a page by title, path or id
echo "..." | nim wiki write "Notes" --create
nim wiki search "deploy"
nim wiki move "Notes" --parent "Product"
nim wiki serve # open the wiki in your browser
nim wiki move-to-team --dry-run # preview moving the local wiki to Teams
nim update # update nim and the Claude Code and Codex plugins
nim doctor # which versions are installed, and from where

프로젝트에 로컬 위키가 있으면 list, read, move, search는 로컬 위키를 사용하고, 없으면 팀 위키를 사용한다. --team 또는 --local로 대상을 지정할 수 있다. write는 표준 입력이나 --file의 내용으로 페이지 본문을 바꾼다. read --json에서 얻은 버전을 --expected-version으로 넘기면 읽은 뒤 페이지가 바뀐 경우 덮어쓰기를 거부한다. nim wiki serve --no-open은 브라우저를 열지 않고 URL을 출력하며 --port로 포트를 지정한다. 터미널의 nim은 새 버전이 있으면 하루에 최대 한 번 백그라운드에서 확인해 한 줄로 알린다. nim tracker list/get/create/update는 로컬 위키의 유형 페이지에서 작동한다. 팀 명령인 status, edit, create, items 등에는 nim login이 필요하며 전체 명령은 nim --help에서 확인할 수 있다.

개인정보, 연결과 업데이트

로컬 위키의 브라우저 화면은 사용자의 기기에서만 대기하며 토큰으로 보호된다. 페이지, 세션, 코드는 위키를 팀으로 옮기지 않는 한 기기에 남는다. 플러그인의 MCP 서버와 훅은 플러그인 버전에 고정된 npm 패키지 @nimbalyst/cli를 npx로 실행한다. 플러그인 자체에는 코드가 없다. 소스는 각 릴리스와 함께 공개된다. 첫 세션에서 브라우저 앱을 포함한 패키지를 내려받고, 이후에는 npm 캐시를 사용해 오프라인으로 작동한다.

연결되는 외부 주소는 다음과 같다.

• registry.npmjs.org: 처음 사용할 때 또는 npm 캐시를 지운 뒤 플러그인 버전의 @nimbalyst/cli를 받는다. npx는 회사 레지스트리 미러를 포함해 npm 설정을 따른다.
• raw.githubusercontent.com: 하루에 최대 한 번 이 저장소의 최신 플러그인 버전을 확인한다.
• sync.nimbalyst.com과 console.nimbalyst.com: 팀 위키에서만 사용하며, 로그인·공유·이동 또는 nimbalyst-team 서버 사용 때 연결한다.

에이전트는 위키 작업을 시작할 때 세션마다 사용할 위키를 한 번 결정한다. 사용자가 팀 위키나 로컬 위키를 지정하면 해당 위키를 선택한다. 저장소에 로컬 위키가 있으면 이를 사용하지만 팀 프로젝트에도 연결돼 있다면 어느 쪽을 쓸지 묻는다. 로컬 위키가 없으면 Git 원격 주소에 연결된 팀 프로젝트를 확인한다. 프로젝트가 없으면 현재 체크아웃에서 비공개로 시작하거나, 선택한 폴더에 Git으로 포함해 시작하거나, 지금은 시작하지 않는 선택지를 한 번 제안한다. 같은 내용을 두 위키에 동시에 쓰지 않으며 팀 데이터는 로컬 서버를 거치지 않는다.

Claude Code 플러그인은 세션 시작 때 로컬 위키의 범위와 수정한 파일을 다루는 페이지를 에이전트에 알린다. 실제 작업이 있었던 세션이 끝나면 수정된 파일과 관련된 페이지를 언급하며 /nimbalyst-wiki:capture 실행을 한 번 알리는 훅도 추가한다. 두 MCP 서버는 Claude Code의 /mcp와 Codex의 codex mcp list에서 볼 수 있다. nimbalyst-local은 로컬 위키와 브라우저 화면을 제공하고, 팀으로 옮길 때 페이지를 복사하려고 Nimbalyst에 로그인한다. nimbalyst-session은 현재 세션의 기록만 기기에서 읽어 결정 기록에 인용할 수 있도록 한다. nimbalyst-team은 별도 nimbalyst-wiki-team 플러그인에 포함된다. 0.7.0 이하에서 팀 위키를 사용했다면 업데이트 후 추가 플러그인을 한 번 설치해야 한다.

플러그인은 하루에 한 번 GitHub에서 새 버전을 확인하고, 새 버전이 있으면 다음 위키 사용 때 에이전트가 알린다. 이 확인은 사용자나 위키에 관한 정보를 보내지 않는다. 확인을 끄려면 NIMBALYST_WIKI_NO_UPDATE_CHECK=1을 설정한다. CLI가 설치돼 있으면 nim update가 nim과 Claude Code·Codex 플러그인을 업데이트하고 각 버전을 확인한 뒤 재시작이 필요한 항목을 알린다. nim update --check는 오래된 항목만 보고하고 nim doctor는 설치된 버전을 보여준다.

Claude Code는 마켓플레이스 자동 업데이트를 켠 경우에만 자동으로 업데이트한다. /plugin의 Marketplaces에서 설정할 수 있다. Claude 데스크톱 앱은 자동 업데이트가 꺼진 상태로 Claude Code를 실행하므로 FORCE_AUTOUPDATE_PLUGINS=1을 설정하지 않으면 그곳에서도 플러그인 자동 업데이트가 중단된다. 수동 업데이트는 어디서나 가능하다.

claude plugin marketplace update nimbalyst-wiki
claude plugin update nimbalyst-wiki@nimbalyst-wiki

Codex에서는 다음 명령을 실행하고 새 세션을 시작한다.

codex plugin marketplace upgrade nimbalyst-wiki

이미 열린 세션은 시작 당시 버전을 계속 사용한다. Claude Code에서는 /reload-plugins를 실행하거나 새 세션을 시작하고, Codex에서는 새 세션을 시작한다. 0.3.0을 사용 중이라면 이전 nimbalyst/nimbalyst 마켓플레이스 설치를 제거하고 현재 저장소에서 다시 설치해야 업데이트와 브라우저 화면을 사용할 수 있다. 위키 파일은 저장소에 그대로 있으므로 내용은 바뀌지 않는다.

/plugin uninstall nimbalyst-wiki@nimbalyst
/plugin marketplace remove nimbalyst
/plugin marketplace add nimbalyst/nimbalyst-wiki
/plugin install nimbalyst-wiki@nimbalyst-wiki

그 밖의 안내

위키는 무료 오픈소스 Nimbalyst 앱에서도 열 수 있다. 앱의 Local 위키는 같은 파일 폴더를 사용하므로 파일을 옮길 필요가 없다. 내비게이션 가장자리에서 Wiki를 열고 Cmd+D를 누른 뒤 Local을 선택한다. 앱에서는 세션과 코드 옆에서 실시간 표, 2×2 다이어그램, 목업과 다이어그램을 편집할 수 있다. 앱 안의 에이전트는 이미 위키 도구를 사용하므로 플러그인은 비활성화되고 페이지마다 쓰기 경로가 하나만 유지된다. 앱은 macOS, Windows, Linux에서 개인이 무료로 사용할 수 있으며 오픈소스다. Nimbalyst Teams는 여러 사용자가 함께 쓰는 기능을 제공한다. 자세한 내용은 Nimbalyst 앱 안내와 주 저장소에서 확인할 수 있다.

스킬은 다음과 같다. /nimbalyst-wiki:setup은 Home, 작성 가이드, 시작 페이지를 만들고 유형도 정의할 수 있다. 다시 실행하면 빠진 부분을 채우며 사람이 쓴 내용을 중복 생성하거나 덮어쓰지 않는다. /nimbalyst-wiki:capture는 세션의 결정과 답변, 미해결 사항을 각각 관련 페이지에 기록하며 남길 내용이 없으면 없다고 알린다. /nimbalyst-wiki:recall은 질문이나 주제에 관한 위키 내용과 결정, 수정하려는 코드 관련 페이지를 찾아 답하며 “왜 이렇게 했지?”라는 질문에도 자동으로 사용한다. /nimbalyst-wiki:team은 팀 위키로 옮기고 처음 사용할 때 추가 플러그인을 설치한 뒤 팀원을 초대한다. /nimbalyst-wiki:start는 플러그인 간단 안내다. /nimbalyst-wiki:connect는 세션에서 쓸 위키를 선택하고 저장소를 팀 프로젝트에 연결하며 필요할 때 자동 실행된다. /nimbalyst-wiki:update는 위키 편집 때 에이전트가 따르는 작성 가이드를 갱신한다.

저장소는 주 저장소에서 만들어 릴리스마다 공개되며, SOURCE 파일에 기반 커밋이 적힌다. 버그 신고와 기능 요청은 Issues, 기여 방법은 CONTRIBUTING.md에서 확인할 수 있다. 위키 저장소에 보낸 변경 제안은 승인되면 주 저장소에 반영되고 기여자를 표시한 뒤 다음 릴리스에 돌아오므로, 해당 저장소의 풀 리퀘스트는 병합하지 않고 닫는다. 라이선스는 MIT다.