<!-- markdownlint-disable MD033 MD041 -->
<div align="center">
<img src="https://raw.githubusercontent.com/Goldziher/basemind/HEAD/docs/media/basemind-banner.svg" alt="basemind — cybernetic core" width="820">
코딩 에이전트를 위한 컨텍스트 및 통신 계층.
basemind는 모든 리포지토리를 코드, 문서, 히스토리 및 메모리의 항상 최신 지도(map)로 변환합니다. 이를 통해 에이전트들은 grep이나 파일 읽기에 컨텍스트 윈도우를 소모하는 대신 구조와 검색을 기반으로 답변하며, 작업 중인 여러 에이전트 팀에게는 협업할 공유 채널을 제공합니다. 하나의 서버가 이 두 가지 기능을 모두 수행합니다.
코드 지도 지원: 300개 이상의 언어 · 문서 형식 지원: 90개 이상의 포맷 · 의미론적(semantic) + 전체 텍스트 검색 · git 히스토리 및 blame 추적 · 공유 메모리 · 에이전트 간 통신(agent-to-agent comms)
Docs
crates.io
npm
PyPI
CI
License: MIT
문서(Docs) · 설치 · 기능(Features) · 작동 방식(How it works) · 성능(Performance) · CLI 참조(CLI reference)
</div>
<!-- markdownlint-disable MD013 -->
<p align="center"><img src="https://raw.githubusercontent.com/Goldziher/basemind/HEAD/docs/media/mcp-demo.gif" alt="실시간 Claude Code 세션에서 파일 개요 및 호출 사이트로부터 답변하는 에이전트" width="820"></p>
<p align="center"><em>구조를 기반으로 추론하는 에이전트 — 실시간 세션에서 `코드(code)` 모드, `개요(outline)`, 그리고 `참조(references)`를 사용하며, 상태 표시줄은 저장된 토큰을 추적합니다.</em></p>
<!-- markdownlint-enable MD013 -->
<div align="center"><sub><a href="#demos">더 많은 데모 ↓</a></sub></div>
얻게 되는 것 (What you get)
basemind는 전체 파일이 아닌 파일 경로, 라인 번호, 시그니처로 답변하여, 코드에 대한 질문 비용을 소스 코드를 읽는 데 필요한 토큰의 극히 일부로 만듭니다.
<!-- markdownlint-disable MD013 -->
기능 및 역량
| Capability | 수행 내용 | 주요 도구 |
|---|
| Code intelligence | 파일을 여는 대신 코드 맵을 읽기: 파일의 구조(outline), 이름으로 정의 찾기(symbols), 정규 표현식 콘텐츠 검색(grep), 파일 열거 또는 퍼지 검색(files · find, 문서 포함), 참조 위치를 바인딩된 정의로 해결(definition — 스코프 및 임포트 인식, JS/TS는 oxc를 통해, Python & Java는 in-tree stack-graphs를 통해), 이름의 모든 호출 지점(references, 이름만) 또는 특정 정의의 호출자(callers), 트레이트/인터페이스/기반 클래스의 구현체(implementations), 역방향 임포트 조회(dependents), 하나의 심볼의 원시 본문(expand), 그리고 인덱싱된 청크를 의미로 검색(semantic → chunk, --features code-search 필요). 300개 이상의 언어에 걸쳐 계층화됨. | code (outline · symbols · grep · files · find · definition · references · callers · implementations · dependents · expand · semantic · chunk) |
| ... | | |
설치 (Installation)
basemind를 실행하는 세 가지 방법이 있으며, 쉬운 순서로 나열했습니다. 세 가지 모두 동일한 로컬 인덱스를 공유하며 나란히 실행해도 안전합니다.
MCP 플러그인이 첫 사용 시 basemind 프로그램을 다운로드해 줍니다. Pi, MCP 서버, 및 CLI 경로는 직접 설치해야 합니다 — 프로그램 설치하기를 참조하세요.
1. 플러그인으로 실행 (권장)
plugin/ 아래에 있는 선별된 플러그인은 11개의 런타임 프로파일을 위한 10가지 공개 스킬과 6가지 명령어를 포함하고 있습니다. 로컬 설치 및 릴리스 전제 조건은 플러그인 설치 가이드를 참조하세요. 리포지토리 루트에는 기존의 OpenCode 터미널 어댑터와 Pi 확장이 유지되어 있으며, 이 통합 기능들은 별도의 패키지 진입점을 가지고 있습니다.
<details>
<summary><strong >Claude Code</strong ></summary>
세션(쉘 아님)에서 다음 순서로 실행하세요:
/plugin marketplace add Goldziher/basemind
/plugin install basemind@basemind
<details>
<summary>재시작 후 초기 설정</summary>
Restart, then run `/bm-statusline`을 한 번 실행하여 라이브 상태 표시줄(live statusline)을 켜십시오 (일회성 단계이므로 [Statusline](#install-the-program) 참조). **basemind 마켓플레이스에 대한 자동 업데이트를 활성화하십시오** (Claude Code의 플러그인 관리자): 그러면 해당 플러그인이 각 새로운 릴리스를 자동으로 추적하고, 런처가 일치하는 게시된 릴리스를 해결합니다. 타이밍을 직접 제어하기를 선호하십니까? 대신 마켓플레이스를 수동으로 정기적으로 업데이트하십시오.
</details>
<details>
<summary><strong >Codex</strong></summary>
codex plugin marketplace add Goldziher/basemind
codex plugin add basemind@basemind
앱에서: Plugins 사이드바를 열고 basemind를 추가합니다. CLI와 IDE는 하나의 설정 파일을 공유합니다.
The generated plugin uses the matching published GitHub release, or a local BASEMIND_BIN override.
</details>
<details>
<summary><strong >Cursor</strong></summary>
에이전트 채팅에서: /add-plugin basemind (한 번 나열된 후), 또는 Dashboard → Settings → Plugins → Team Marketplaces → Import from Repo로 이동하여 https://github.com/Goldziher/basemind를 지정합니다.
</details>
<details>
<summary><strong >Gemini CLI</strong></summary>
git clone https://github.com/Goldziher/basemind
cd basemind
gemini extensions install ./plugin --skip-settings
나중에 gemini extensions update basemind로 업데이트하십시오.
</details>
<details>
<summary><strong >Factory Droid</strong></summary>
droid plugin marketplace add https://github.com/Goldziher/basemind
droid plugin install basemind@basemind
</details>
<details>
<summary><strong >GitHub Copilot CLI</strong></summary>
copilot plugin marketplace add Goldziher/basemind
copilot plugin install basemind@basemind
</details>
<details>
<summary><strong >OpenCode</strong></summary>
opencode.json (프로젝트) 또는 ~/.config/opencode/opencode.json (전역)에 추가합니다:
{ "plugin": ["basemind-opencode@latest"] }
</details>
<details>
<summary><strong >Kimi Code</strong></summary>
/plugins install https://github.com/Goldziher/basemind
Kimi는 통신 자동 알림(comms auto-notifications)을 지원하지 않지만, 채팅 도구는 여전히 작동합니다.
<details>
<summary><strong >Agent Plugins (agent-plugins.org)</strong></summary>
plugin/ 디렉토리를 에이전트 플러그인(Agent Plugins) 1.0.0 패키지로 로드합니다. 여기에는 plugin.json, mcp.json 및 열 개의 공개 스킬이 포함되어 있습니다. Copilot도 이 휴대 가능한 레이아웃을 공유합니다. MCP 런처는 일치하는 게시된 basemind 바이너리를 다운로드하거나, 로컬 빌드의 경우 BASEMIND_BIN을 사용합니다.
</details>
<details>
<summary><strong >Hermes</strong></summary>
프로그램 설치를 먼저 수행합니다. 로컬에서 생성된 휠(wheel)을 Hermes가 실행되는 동일한 Python 환경에 설치한 다음, 플러그인을 활성화합니다:
git clone https://github.com/Goldziher/basemind
cd basemind
uv build --wheel --out-dir dist/hermes plugin/.hermes/package
...
Hermes를 다시 시작합니다. 이 플러그인은 열 개의 스킬, 여섯 개의 슬래시 명령어(/), 범위 지정 통신 알림(scoped comms notifications), 그리고 로컬 MCP 서버의 도메인을 연결하고 JSON 텍스트를 반환하는 basemind_call을 등록합니다. 바이너리는 PATH에 있어야 합니다. 통신 알림은 최선 노력(best-effort)입니다. 또한 직접적인 도메인 도구를 위해 mcp_servers.basemind를 command: basemind 및 args: [serve]로 구성할 수 있습니다.
PyPI 버전 0.29.3은 스킬 등록 수정 및 MCP 브리지를 선행합니다. 이 변경 사항을 포함하는 새 릴리스가 나올 때까지 위의 소스 휠을 사용하십시오. 해당 게시된 버전을 재설치한다고 해서 추가되지 않습니다.
</details>
<details>
<summary><strong >Antigravity</strong></summary>
Antigravity는 공유된 MCP 설정을 사용합니다 — 프로그램 설치를 수행한 다음, 일반 MCP 블록(generic MCP block)을 추가합니다. 이미 Gemini 확장을 사용하는 경우, agy plugin import gemini가 이를 가져옵니다.
</details>
<details>
<summary><strong >Pi</strong></summary>
basemind 프로그램 설치를 먼저 수행한 다음, Pi 패키지를 설치합니다:
pi install git:github.com/Goldziher/basemind
<details>
<summary>basemind: 코딩 에이전트를 위한 컨텍스트 및 통신 계층</summary><br/>
이 패키지는 10개의 스킬과 세션 시작 및 압축(compaction) 후에 basemind 컨텍스트를 로드하는 네이티브 확장 기능을 포함합니다. Pi는 [CLI](#3-as-a-cli)를 사용하여 셸 도구를 통해 basemind를 실행합니다. MCP 브리지나 바이너리는 포함되어 있지 않습니다. 패키지를 현재 프로젝트의 구성에 저장하려면 `-l`을 추가하세요.<br/><br/>다음 릴리스에서는 이 리소스들을 기존의 `basemind-opencode` npm 패키지에 추가할 예정입니다. 해당 릴리스 이후에는 레지스트리 설치 및 Pi 패키지 카탈로그 검색을 위해 `pi install npm:basemind-opencode`를 사용하십시오. 두 설치 경로 모두 동일한 확장 기능과 스킬을 가집니다.</details>
공개 스킬만 해당합니다. 10개의 공개 스킬을 독립적으로 설치하십시오:
npx skills add Goldziher/basemind
검색은 루트 skills/ 미러를 사용합니다. 유지 관리자 거버넌스 및 비공개 에이전트는 포함되어 있지 않습니다. 큐레이션된 Pi 패키지의 10개 스킬과 6개 프롬프트의 경우, 이 체크아웃에서 pi install ./plugin을 실행하십시오. 이는 자동 컨텍스트 확장을 가지지 않습니다. 위의 루트 Git 패키지는 사용자 정의 확장 기능을 유지합니다.
플러그인이 있는 로컬 또는 개발 빌드. 런처는 플러그인 매니페스트와 일치하는 릴리스를 실행합니다. 대신 자체 빌드를 실행하려면 BASEMIND_BIN=/path/to/basemind로 설정하십시오: 이는 보고되는 버전과 관계없이 인정되며(런처는 이 버전이 매니페스트의 버전과 다를 경우 알림을 기록함), BASEMIND_FORCE_VERSION보다 우선합니다. 다른 릴리스 마이너 버전으로 빌드하면 첫 열기 시 캐시가 초기화됩니다(삭제 및 재구축). BASEMIND_FORCE_VERSION=<x.y.z>는 런처를 매니페스트 대신 게시된 단일 릴리스에 고정합니다.
2. MCP 서버로 사용하기
도구가 MCP를 지원하지만 플러그인을 사용하지 않는 경우, 프로그램을 설치한 다음 등록하십시오:
{
"mcpServers": {
"basemind": { "command": "basemind", "args": ["serve"] }
...
각 도구는 제목을 가지고 있으며, 읽기만 하는지 아니면 내용을 변경할 수 있는지 여부를 명시합니다. 따라서 클라이언트는 안전한 도구를 자동으로 승인하고 나머지에 대해서는 요청할 수 있습니다. 서버는 또한 일치하는 도구 결과와 동일한 본문을 가진 세 가지 온디맨드 (on-demand) MCP 리소스, 즉 basemind://status, basemind://outline/{path}, 그리고 basemind://memory/{key}를 노출합니다. 만약 basemind가 발견되지 않으면, which basemind에서 얻은 전체 경로를 사용하십시오.
<details>
<summary><strong id="per-tool-specifics">도구별 세부 정보 (Per-tool specifics)</strong> (Claude Code · Cursor · Windsurf · Codex · Gemini · Copilot · Droid · Cline · Continue · OpenCode · Hermes)</summary>
-
Claude Code — claude mcp add basemind -- basemind serve를 사용합니다. (모든 프로젝트에 대해 --scope user를 추가하고, --는 필수입니다). 또는 위 블록을 리포지토리 루트의 .mcp.json 파일로 커밋하십시오.
-
Cursor — 위의 블록을 .cursor/mcp.json(프로젝트) 또는 ~/.cursor/mcp.json(전역)에 넣으십시오.
-
Windsurf — ~/.codeium/windsurf/mcp_config.json (또는 Cascade → MCP servers → manage)에 설정한 후, 새로 고침(Refresh) 하십시오.
-
Codex — CLI와 IDE에서 공유되는 codex mcp add basemind -- basemind serve를 사용하십시오.
-
Gemini CLI — gemini mcp add basemind basemind serve를 사용하거나, 위의 블록을 ~/.gemini/settings.json에 넣으십시오.
-
GitHub Copilot CLI — 세션 내에서 /mcp add를 사용하거나, `
-
다른 모든 도구(Any other tool) — 해당 도구를 인자(argument) serve를 사용하여 명령어 basemind에 연결합니다.
3. CLI로 사용하기
스크립트, 헤드리스 실행(headless runs), 그리고 지속적 통합(CI)을 위한 독립형 프로그램입니다. 설치하기를 수행한 후, 다음 명령어를 사용합니다:
basemind scan
basemind code symbols "parseQuery"
basemind code references "processFile"
...